Analytics

Dynamic Metadata

Normal

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

Tutorials

JavaScript

NodeJS

Online video training is huge. There are many companies that offer video training courses where the course follows one video after another. The only way to continue in the course is to finish a video, and when the video is completed, the next video is unlocked. This ensures that the video course is taken in the order designed by the instructor, and that the students are not 'skipping' ahead through the coursework.


Other use cases for this might be a corporate training, where it is required that every employee watches each video in a series to be compliant with the policies of an organization (as a veteran of AT&T, I have taken months of this sort of training)

In this post, we'll walk through how you can build a video training app with api.video. 

## Connecting a session to a user

The first step in any training course will be to login your user. In the case of training a video, we'll skip a secure login form (it is just a demo!) and simply ask you to enter your name:

large_screenshot-2021-06-28-at-18-14-33.png

medium_screenshot-2021-06-28-at-18-14-33.png

small_screenshot-2021-06-28-at-18-14-33.png

thumbnail_screenshot-2021-06-28-at-18-14-33.png

screenshot-2021-06-28-at-18-14-33.png

When you submit this form, we'll search through the videos connected to the course (in this case, they are hardcoded in the app as an array:

```
var videolist = ['vi47Q8KHXLYyaOoX2Yoznxqh','vi6QvU9dhYCzW3BpPvPsZUa8','vi1DrBc0VkPfedcfTc21U1TP'];
var videoDurations= [91,321,333];
```

Note, we also hardcode the duration of the 3 videos (but in a more dynamic app, you can get the video duration from the [video status](https://docs.api.video/reference/get-video-status) endpoint.

Now for each of these videos, I have created  dynamic metadata entry:


```
	"metadata": [
		{
			"key": "classUserName",
			"value": "__classUserName__"
		}
	],
```

when the value of a metadata entry has two underscores on either side of the value, any value can be applied to the metadata entry.  In this case, we'll apply the username as the value.  We can search for any video sessions that have the classUserName "Doug" for each of the videos in the training session. (in the code below, I am using the NodeJS client:

```
			currentPage = '1';
      pageSize = '25';
      var metadata = {'classUserName': userName};
      var params = { videoId, metadata, currentPage, pageSize};
      console.log("params",params);
      const result = client.rawStatistics.listVideoSessions(params);

```

This will result in the first 25 sessions where the variable userName (Doug) is saved as the classUsername metadata. (Of course, if you believe that your users might have more than 25 sessions per video, you can expand that number up to 100 - but for a training course, 25 viewing sessions per video per user is probably more than adequate).

The response from this will be every session that the user has had for the video.  For each of these sessions, we want to know if the video was watched all the way through.  We've [written up this analysis](https://api.video/blog/tutorials/video-event-analysis-using-api-video-sessions) of session events. As soon as we discover a session that has watched the video, we stop looking through the sessions.  

## How many videos to unlock?

This approach will then be completed for each video in the series, until we reach a video that has not been watched.  This is done through the recursive function iterateVideos:

```

function iterateVideos(videolist, videoDurations, userName, videoCounter){
  return new Promise(function(resolve, reject){
      //soo take list of videos, and iterate until we know which video can be watched.
      console.log("testing video "+videoCounter);
      var videowatched  = videoWatched(videolist[videoCounter], videoDurations[videoCounter], userName);
      videowatched
      .then(function(passfail){
    
        console.log("video "+videoCounter+ " "+ passfail);
        if(passfail){
          //video was watched, so lets check the next one
          videoCounter++;
          if (videoCounter < videolist.length){
            var nextVideo = iterateVideos(videolist, videoDurations, userName, videoCounter);
            resolve(nextVideo);
          }else{
            //the last video was watched so, stop and show all the videos...
            resolve(videoCounter -1);
          }
        }else{
          //video was NOT watched start wit this video
          console.log("resolve the counter of the first video not watched", videoCounter);
          resolve(videoCounter);
        }
      }).catch((error) =>{
        reject(error);
    });



  });
```

The videoWatched function checks each session to see if the video has been completed.  

If the video has been completed, it returns true.  Then we check the next video to see if it has been watched. (If we reach the end of the video list - we show all of the videos.).

If the video has not been watched - we know where to stop displaying playable videos, and we can display the page.

### What the user sees

For this simple example with three videos, there are just three potential views:

* If no videos have been watched - the first video will have no sessions, and the session analysis will stop immediately. The page will show the first video as playable, and the subsequent videos as locked.

* If the first video has been completed, but not the second: the page will show the first two videos as playable, but the third video will still be locked.

* If videos 1-2 are completed (or if all 3 videos are completed), all three videos appear as watchable.


### Looking at the HTML

```
<iframe type="text/html" src="https://embed.api.video/vod/vi6QvU9dhYCzW3BpPvPsZUa8?metadata[classUserName]=Doug" width="960" height="320" frameborder="0" scrollling="no"></iframe>

```

See how each video adds the ```metadata[classUserName]=Doug```  this will ensure that any video session that is started on this page will be assigned to the user Doug. Once a video is watched, the user can refresh the page, and all the session data will be recalculated, and the next video will be unlocked.


## Build your own video training app

With api.video, you can easily upload your videos for playback. Using our analytics and dynamic metadata, we can build a training application that unlocks each video as content is viewed. Build your own based on our code on [Github](https://github.com/apivideo/trainingavideo). If you have question, feel free to reach [our community](https://community.api.video/) or [test it now](https://dashboard.api.video/register) in our free Sandbox environment.

Build a self guided training course with api.video

large_build-a-self-guided-training-course-with-api-video.png

medium_build-a-self-guided-training-course-with-api-video.png

small_build-a-self-guided-training-course-with-api-video.png

thumbnail_build-a-self-guided-training-course-with-api-video.png

build-a-self-guided-training-course-with-api-video.png

Video Sessions (Analytics)

When I read a book, I fold a corner over the page I am reading to remember my place.  Sometimes I fall asleep while reading, and it takes a few minutes to figure out where I had finished the night before, and I wish to myself that I had folded over the corner.

Watching video online is the same way - if you're interrupted while watching a long video (Amazon delivery at the door, child is hungry, cat needs to be let out... you know) it would be nice to resume right where you left off.

## Resuming videos

YouTube recently remembered where I had left off on a knitting tutorial.. that I had watched 3 years ago.  I have small children, so we often have to pause movies for days before we finish them, and it is great that Netflix recalls that we turned off the TV at 42:11 into the feature.  No more scanning and seeing potential spoilers a scene or two ahead.

We can do the same with api.video's videos.  We've released a demo at [resume.a.video](https://resume.a.video) where you can test this feature out.



## Resuming Videos with api.video

### Identifying users

For each video that you'd like to resume, you should create a [dynamic metadata](https://api.video/blog/tutorials/dynamic-metadata) attribute that you will use to identify each user. For the videos in the demo, I created a dynamic metadata with key "userName"

screenshot showing metadata setting for video

large_screenshot-2021-01-11-at-15-46-51.png

medium_screenshot-2021-01-11-at-15-46-51.png

small_screenshot-2021-01-11-at-15-46-51.png

thumbnail_screenshot-2021-01-11-at-15-46-51.png

screenshot-2021-01-11-at-15-46-51.png

>You can create a Dynamic metadata with the [Update video](https://docs.api.video/reference#patch-video) endpoint.  For the 'key' use the key.  For 'value' add two'_' before and after the term. The API will know that this value can have any potential value.

> You can also use the GUI at go.api.video to add the metadata.

We can use this to uniquely identify users who watch the video.  I would recommend using a unique non-identifiable string for each user, but for simplicity, I'll use first names in this demo. In this way, we can identify who is watching the video:

https://embed.api.video/vod/vi4fvaDG9nqfdMTqRnmZuvlJ?metadata[userName]=Doug

This video will record its session with the metadata userName: Doug.  

Awesome - assuming we know the user's name, we can insert this URL paramater and now identify all of their sessions with the video.


### Identifying user sessions

When you use the api.video player, each session has video analytics recorded (and each session is based on a cookie set in the browser). Using the [analytics video session](https://docs.api.video/reference#get_analytics-videos-videoid) endpoint, you can search each session for a video played.  You can limit this search with the metadata term. In NodeJS, this looks like:

```
var firstSessionQuery = {
			method: 'GET',
			url: 'https://ws.api.video/analytics/videos/'+videoId+'?currentPage=1&pageSize=1&metadata[userName]='+userName,
			headers: {
				accept: 'application/json',
				authorization: 'Bearer ' +authToken
			}
		}
		request(firstSessionQuery, function (error, response, body) {
			if (error) throw new Error(error);
			body = JSON.parse(body);
		}

```

The request url uses the videoId and userName to get just the sessions for the user.  The response can return from 1 to 100 results, with the most recent session appearing at the end. In this query, I only request the first session:

```
data {
  session: {
    sessionId: 'ps5qU6t436lzoDftbAfuJPzP',
    loadedAt: '2021-01-05T12:52:21+00:00',
    endedAt: '2021-01-05T12:52:53+00:00',
    metadata: [ [Object] ]
  },
  location: { country: 'United Kingdom', city: 'Watford' },
  referrer: {
    url: null,
    medium: 'unknown',
    source: 'unknown',
    searchTerm: 'unknown'
  },
  device: { type: 'computer', vendor: 'unknown', model: 'Other' },
  os: { name: 'Mac OS X', shortname: 'Mac OS X', version: '11.0.1' },
  client: { type: 'unknown', name: 'Chrome', version: '87.0.4280' }
}
pagination {
  currentPage: 1,
  currentPageItems: 1,
  pageSize: 1,
  pagesTotal: 23,
  itemsTotal: 23,
  links: [
    {
      rel: 'self',
      uri: '/analytics/videos/vi4fvaDG9nqfdMTqRnmZuvlJ?currentPage=1&pageSize=1&metadata%5BuserName%5D=Doug'
    },
    {
      rel: 'first',
      uri: '/analytics/videos/vi4fvaDG9nqfdMTqRnmZuvlJ?currentPage=1&pageSize=1&metadata%5BuserName%5D=Doug'
    },
    {
      rel: 'next',
      uri: '/analytics/videos/vi4fvaDG9nqfdMTqRnmZuvlJ?currentPage=2&pageSize=1&metadata%5BuserName%5D=Doug'
    },
    {
      rel: 'last',
      uri: '/analytics/videos/vi4fvaDG9nqfdMTqRnmZuvlJ?currentPage=23&pageSize=1&metadata%5BuserName%5D=Doug'
    }
  ]
}

```
 
Ok, so when I created this video in January 2021, I watched it, to ensure that it worked.  You can see my approximate location (it's really where my ISP exits to the internet), and I was on a Mac running Chrome.

So, why just one entry?  We want to get the last session that was viewed, and that is always the last session in the list.

```
var sessionCount = body.pagination.itemsTotal;
```

There are really only three possibilities to worry about here:

* sessionCount = 0.  This is a new viewer of the video, and there are no sessions saved.  If there are no sessions for the user - we can immediately serve the page, and start the video at the beginning:

```
				//no sessions for this user
				//return the video at time =0
				var videoUrl = 'https://embed.api.video/vod/'+videoId+'?metadata[userName]='+userName+'#autoplay';
				return res.render('video', {videoUrl});
```
This will load the page with the video autoplaying.

* sessionCount=1. The viewer has watched the video once.  If that is the case, the sessionId returned in the response will be the session we want.  You can now skip ahead to the "parsing session data" section.
* sessionCount >1.  There is more than one session for this user. In the example above, the itemsTotal parameter indicates that there are 23 sessions for userName=Doug.

The API has a limit of 100 sessions in the video analytics response. In general, one user is unlikely to have >100 sessions for a single video, so one query would probably be sufficient. However, this is a demo app with a default user - it is possible that we might exceed 100 sessions.  If I queried for 100 sessions, the demo would appear to fail - we'd only ever see the 100th session. So, we request one, and then to ensure that we always get the last session, we can now make a second query for the last session (conveniently in the pagination.links.last.uri).

```
var lastUri = decodeURI(body.pagination.links[linksLength-1].uri);
					console.log("number of sessions with this username:", lastSessionCounter);
					console.log("uri", lastUri);
					//request that last session
					var lastSessionQuery = {
						method: 'GET',
						url: 'https://ws.api.video' +lastUri,
						headers: {
							accept: 'application/json',
							authorization: 'Bearer ' +authToken
						}
					}
					request(lastSessionQuery, function (error, response, body) {
						if (error) throw new Error(error);
						body = JSON.parse(body);
						console.log("body", body);
						console.log(body.data[0]);
						var sessionId = body.data[0].session.sessionId;
						console.log(sessionId);
						//now we can access this sessionId, and get the last time in the session
						getSession(authToken, videoId, sessionId, userName);

```

This response now tells me the last session for Doug and this video:

```
 session: {
    sessionId: 'pshSgwO44hBbc0nYKz1OZsz',
    loadedAt: '2021-01-11T19:02:43+00:00',
    endedAt: '2021-01-12T11:35:49+00:00',
    metadata: [ [Object] ]
  },
  location: { country: 'United Kingdom', city: 'Slough' },
  referrer: {
    url: 'http://localhost:3006/',
    medium: 'unknown',
    source: 'unknown',
    searchTerm: 'unknown'
  },
  device: { type: 'computer', vendor: 'unknown', model: 'Other' },
  os: { name: 'Mac OS X', shortname: 'Mac OS X', version: '11.0.1' },
  client: { type: 'unknown', name: 'Chrome', version: '87.0.4280' }
}

```

Again - on my Mac - but this time, I am in Slough, UK (and I was testing this app locally on my computer).  The sessionId I want is 'pshSgwO44hBbc0nYKz1OZsz'

### Parsing session data

If there was a previous session for this user - we now have the last session (and more importantly the sessionId for that session). It may have just been one request - or it may have taken two.

I use the [session events](https://docs.api.video/reference#get_analytics-sessions-sessionid-events) endpoint to find out what happened in the session:

```
	function getSession (authToken, videoId, sessionId, userName) {
		//lets get 100 session activities - i doubt there will ever be that many - (or more than 100)
		var getSession = {
			method: 'GET',
			url: 'https://ws.api.video/analytics/sessions/'+sessionId+'/events?currentPage=1&pageSize=100',
			headers: {
				accept: 'application/json',
				authorization: 'Bearer ' +authToken
			}
		}
		request(getSession, function (error, response, body) {
			if (error) throw new Error(error);
			body = JSON.parse(body);
			console.log("sessions", body.data);
			var numberofEvents = body.data.length;
			console.log("num events", numberofEvents);
			var lastTimeRecorded = body.data[numberofEvents-1].at;
			console.log("last event time", lastTimeRecorded);
	
			var videoUrl = 'https://embed.api.video/vod/'+videoId+'?metadata[userName]='+userName+'#autoplay;t='+lastTimeRecorded;
					return res.render('video', {videoUrl});
	
		});
	
	}
	
	  
});

```

So the API calls the session endpoint with the sessionId we discovered in the last section.  We get a response (write to console log) and we extract how many events were in the last session, and find out what the last event was. 

>You'll note that in the comments I make an assumption that there will never be 100 events (play, pause, seek, etc.) in a single session. I think this is safe  to make :)

The session response looks like this:

```
sessions [
  { type: 'ready', emittedAt: '2021-01-12T11:59:42+00:00', at: 0 },
  { type: 'play', emittedAt: '2021-01-12T11:59:42+00:00', at: 0 },
  { type: 'pause', emittedAt: '2021-01-12T11:59:45+00:00', at: 2 },
  {
    type: 'seek.forward',
    emittedAt: '2021-01-12T11:59:46+00:00',
    from: 2,
    to: 163
  },
  { type: 'resume', emittedAt: '2021-01-12T11:59:47+00:00', at: 163 },
  { type: 'pause', emittedAt: '2021-01-12T11:59:49+00:00', at: 165 }
]
num events 6
last event time 165

```

So I started the video at time =0, and then at time t=2, I jumped ahead "seek.forward" to 163s.  Then I paused at 165s.

**So the last time viewed was at 165s.**

### Starting the video

We have now found all the sessions for the user.  We grabbed the last (most recent) session, and then found the last event in that session - to give us the last time that the user saw the video.

In HTML5, if you add #t=X, where X is an integer to the end of a video URL, the video playback will begin at that time. Simply returning the url with this parameter will start the video at the last time the user viewed the video.

## Summary

With Dynamic metadata, we are able to assign video watching sessions to specific customers.  We can then search a specific user's sessions for the most recent session, and inside that session, parse all the events that occured during playback. 

Using the last session, and the last event, we get the last time that the viewer interacted with the video.  We can now use this time as the "resume time" for the video, and stat the video at that time.

Don't forget to try it out: [resume.a.video](https://resume.a.video)

This is a nice feature that makes watching longer videos easier - your viewers know they can come back and quickly pick up where they left off.  

Are you thinking about using 'resume' in your videos?  The code is all up on [Github](https://github.com/dougsillars/resumeAVideo) Let us know - we'd love to see if it improves the engagement of your viewers! Leave us a comment in the [community](https://community.api.video) forum.

medium_screenshot-2021-01-11-at-13-29-09.jpg

small_screenshot-2021-01-11-at-13-29-09.jpg

thumbnail_screenshot-2021-01-11-at-13-29-09.jpg

screenshot-2021-01-11-at-13-29-09.jpg

Resume a video

Organization of your videos helps you deliver the correct videos to the correct page.

If you look closely in our API, we also offer a metadata tag with key:value pairs to be used as an additional organizational tool. In many ways, metadata and tags are functionally similar.

However, we also support the concept of dynamic metadata. Dynamic metadata is not directly related to the video - but is more related to how the video has been consumed. The values of dynamic metadata are variable and are added during playback, allowing you to further segment your audience analytics.


## Analytics

By default the api.video analytics engine can report both [video stats]() and [session specific]() data. There is a [tutorial](https://api.video/blog/tutorials/video-analytics-a-primer) describing how to use the analytics endpoints.

Stats: each video can be parsed to quantify views, time/date of view, browser and location, and more. You can read more on the [Video Analytics](https://docs.api.video/reference/get_analytics-videos-videoid) endpoint.  
[Session](https://docs.api.video/reference/get_analytics-sessions-sessionid-events):  each video session has a unique ID.  For each session, several events are recorded in the player. Currently, this list is: ```ready, play, pause, resume, seek.backward, seek.forward, end```. 

By default, you gain a lot of insight as to how your audience views and consumes your video. We can use dynamic metadata to segment your audiences for deeper insights.

## Segmenting your video audience

Imagine that you have two segments of users on your website: dog lovers and cat lovers. You want to know which videos are more appreciated by each segment of your population.

For these videos you can add a dynamic metadata key:value where the value changes depending on the viewer.  For example:

```
[
{"key" : "dogcat", "value", "__dogcat__"}
]
```

The double underscore before and after the value tells the API that this is a dynamic attribute, and the value of the dogcat attribute will be measured on each session of the video.

## Using the segmentation

Now that you have added the dog/cat segmentation to the video, each view of the video can be segmented.  To do this, we append a url parameter.

For example, dog lovers would receive this video:

https://embed.api.video/vod/vi2WbMm8rUWIQSzMS53aculW?metadata[dogcat]=dog



and cat lovers would receive this video:

https://embed.api.video/vod/vi2WbMm8rUWIQSzMS53aculW?metadata[dogcat]=cat

The video is my dog Malla, who is named after Chewbacca’s wife (from the infamous Star Wars Holiday Special). You have to admit, she sounds a bit like a Wookie.

These urls can be built dynamically based on user profiles on the website. When the video is watched, this metadata is added to the analytics session. Each video play will mark the viewer as either a dog lover or a cat lover.

Now, since the viewer's cat/dog preference is added to the video statistics, you can learn how your two audiences interact with each video on your site, and which videos are preferred by dog or cat people.

Using the video stats endpoint, I have found that my team is:
* 50% dog
* 37.5% cat

and, well:
* 12.5% "know-it-all":

```
						"key": "dogcat",
						"value": "dog"

						"key": "dogcat",
						"value": "dog"

						"key": "dogcat",
						"value": "cat"

						"key": "dogcat",
						"value": "cat"

						"key": "dogcat",
						"value": "dog"

						"key": "dogcat",
						"value": "cat"

						"key": "dogcat",
						"value": "dog"
						
						"key":"dogcat",
						"value":"rhinoceros"

```

If you have unique IDs for each user, you could also track video watching per user (how often they view each video, or if they are watching the entire video).  This could be very useful for online training compliance, classes, or even to check on credential sharing.  The possibilities are endless!

### Conclusion

Using dynamic metadata and url parameters, you can segment your video analytics into different populations, and better understand how your users are using your videos. How are you using dynamic metadata in your app's videos? Leave a note on our [community forum](https://community.api.video). If you don't have an api.video account yet, you can create one in just a few moments by following [this link](https://dashboard.api.video/register). Happy building! 



large_dogcat.jpg

medium_dogcat.jpg

small_dogcat.jpg

thumbnail_dogcat.jpg

dogcat.jpg

Dynamic metadata: use variables in the metadata tag to segment your audience

Featured article

# api.video blog

Blog

Follow the api.video Blog to explore tutorials, video use cases, and learn about on-demand and live-streaming video updates.