[object Object] Icon

Encoding
Learn how to create, start, manage and modify Encodings

[object Object] Icon

Player
Learn how to create, start, manage and modify Players

[object Object] Icon

Analytics
Learn how to create, start, manage and modify Analyticss

Docs Home
User shortcuts for search
Focus by pressing f
Hide results by pressing Esc
Navigate via   keys

Mon Sep 10 2018

Tracking users and impressions

OverviewLink Icon

To build a successful video platform, it’s important to understand your audience. How many users watch videos on your platform? How much time do they spend watching videos? And what devices do they typically use?

In this article you’ll learn how to answer these questions using the Bitmovin Analytics API.

Counting your usersLink Icon

To understand how popular your video platform is, an important metric is the number of unique users on your platform. Make sure you’ve set up the Bitmovin JavaScript client according to the “Getting Started” guide.

To determine the number of unique users watching your videos, we count the number of user ids:

1queryBuilder
2 .count('USER_ID')
3 .between(fromDate, toDate)
4 .query()
5 .then(console.log);

The result will look something like this:

1{
2 rowCount: 1,
3 rows: [[1503]],
4 columnLabels: [{ key: 'USER_ID', label: 'User id' }],
5}

The number of unique users in the given period is stored in result.rows[0][0]. A unique user is identified by a browser cookie, so if several videos are played in the same browser on the same device, all of these video impressions are assigned to the same user. If the same person watches a video in a different browser or on another device, like their smartphone or their TV, these impressions are counted as separate users. Therefore the number of unique users doesn’t necessarily correspond to the number of “physical” users.

Tracking your own user idLink Icon

If your viewers create user accounts on your platform, you’re able to track their video impressions across different devices. To tell Bitmovin Analytics which of your users is watching a video, you can pass the user’s id as userId property to the Analytics Config. The user id can be a database record id, the user’s email address or the user name. It doesn’t matter as long as the value uniquely identifies a single user (we strongly suggest you hash any email-addresses or otherwise personally identifiable information before submitting it to our database).

Once you’re passing your own user ids, you can change the above query to

1queryBuilder
2 .count('CUSTOM_USER_ID')
3 .between(fromDate, toDate)
4 .query()

Identifying usage patternsLink Icon

On most platforms, usage varies in the course of a day. It’s beneficial to find out these usage patters for several reasons:

  • You can identify peak hours and plan your content releases and IT infrastructure according to them.
  • You can maintain your site and release new features when fewer users are online.
  • You can schedule regular background tasks at times of little load on your servers.

To see how many users are watching videos at what times, we can divide a day into hourly intervals. Make sure the between period is exactly one day:

1queryBuilder
2 .count('USER_ID')
3 .between(new Date('2017-11-16'), new Date('2017-11-17'))
4 .interval('HOUR')
5 .query()
6 .then(console.log);

Now we get several rows, one for each hour of the day:

1{
2 rowCount: 24,
3 rows: [
4 [1510822800000, 33],
5 [1510848000000, 30],
6 [1510804800000, 10],
7 [1510837200000, 40],
8 [1510862400000, 25],
9 [1510819200000, 39],
10 [1510794000000, 11],
11 [1510851600000, 22],
12 [1510833600000, 35],
13 [1510808400000, 10],
14 [1510866000000, 20],
15 [1510790400000, 10],
16 [1510873200000, 13],
17 [1510797600000, 10],
18 [1510830000000, 30],
19 [1510855200000, 18],
20 [1510812000000, 25],
21 [1510844400000, 26],
22 [1510869600000, 13],
23 [1510826400000, 41],
24 [1510801200000, 17],
25 [1510858800000, 25],
26 [1510840800000, 38],
27 [1510815600000, 39],
28 ],
29 columnLabels: [{ key: 'USER_ID', label: 'User id' }],
30}

If your result contains less than 24 rows, there were hours when no user watched a video. Each row starts with the unix timestamp of the beginning of the hour:

1new Date(1510866000000); // => 2017-11-16T21:00:00.000Z

The second value is the number of unique users watching videos during this hour. So in this example, 20 unique users watched videos between 9pm and 10pm UTC.

The results are not particularly ordered, so to get the number of unique users sorted by time, you can order the result:

1queryBuilder
2 .count('USER_ID')
3 .between(new Date('2017-11-16'), new Date('2017-11-17'))
4 .interval('HOUR')
5 .orderBy('MINUTE', 'ASC')
6 .query();

ImpressionsLink Icon

Bitmovin Analytics tracks all impressions of your videos, so we’re able to look at usage during the day at an even finer-grained level. To count impressions per hour, we just need to replace the USER_ID in our query with the IMPRESSION_ID:

1queryBuilder
2 .count('IMPRESSION_ID')
3 .between(new Date('2017-11-16'), new Date('2017-11-17'))
4 .interval('HOUR')
5 .query()

Similarly, we can query for the number of impressions on each day of a month:

1queryBuilder
2 .count('IMPRESSION_ID')
3 .between(new Date('2017-11-01'), new Date('2017-12-01'))
4 .interval('DAY')
5 .query()

The available intervals for your queries are 'MINUTE', 'HOUR', 'DAY' and 'MONTH'.

Determining your top usersLink Icon

It might be interesting to understand who the top users of your platform are. Who spends most time watching videos? Who has watched most videos?

To find out the top 5 users in terms of play time, you can use the following query:

1queryBuilder
2 .sum('PLAYED')
3 .between(fromDate, toDate)
4 .groupBy('CUSTOM_USER_ID')
5 .orderBy('FUNCTION', 'DESC')
6 .limit(5)
7 .query()
8 .then(console.log);

Ordering by 'FUNCTION' means the results get sorted by the aggregated values. In this case the users will be ordered by their video play times with the longest-watching users on top.

1{
2 rowCount: 2,
3 rows: [
4 ["user5", 243990],
5 ["user1", 185362],
6 ["user3", 112823],
7 ["user2", 3712],
8 ["user4", 0],
9 ],
10 columnLabels: [{ key: "PLAYED", label: "Played" }]
11}

The play times are given in milliseconds, so "user5" watched 243.99 seconds of video between fromDate and toDate.

Analyzing single usersLink Icon

Global metrics give you a lot of information about general usage of your site, but sometimes you might be interested in retrieving metrics for a single user only. A use case would be to present some metrics on a public user profile.

It’s easiest to query for users if you pass a custom user id to Bitmovin Analytics. Then we can use the following query to find out the total time a user spent watching a video:

1queryBuilder
2 .sum('PLAYED')
3 .between(fromDate, toDate)
4 .filter('CUSTOM_USER_ID', 'EQ', myUserId)
5 .query()

Similarly, we can count the impressions of a single user:

1queryBuilder
2 .count('IMPRESSION_ID')
3 .between(fromDate, toDate)
4 .filter('CUSTOM_USER_ID', 'EQ', myUserId)
5 .query()

You’ll find more attributes to track for your users in the Bitmovin Analytics API docs. Check them out!

Give us feedback