Unique Users

In this topic, you will learn about how to obtain data on unique users via the Analytics API and how unique users are calculated.

Introduction

The unique_users field which gives customers an estimated number of unique viewers per day at the account level. The data is returned in a field which is called daily_unique_viewers. This field is available at the account or video level. See Overview: Data Collection API for more information on how user data is collected and used.

Note that unique users data is returned only for reconciled data.

Sample calls

Here is a sample call for a user report for a day, using the day dimension:

    https://analytics.api.brightcove.com/v1/data?accounts=789967572001&dimensions=date&from=2014-07-09&to=2014-07-22&limit=10&format=json&fields=daily_unique_viewers,date,video_view

Sample output:

    {
      "item_count": 14,
      "items": [
        {
          "daily_unique_viewers": 73,
          "date": "2014-07-09",
          "video_view": 454
        },
        {
          "daily_unique_viewers": 203,
          "date": "2014-07-10",
          "video_view": 287
        },
        {
          "daily_unique_viewers": 150,
          "date": "2014-07-15",
          "video_view": 257
        },
        {
          "daily_unique_viewers": 170,
          "date": "2014-07-12",
          "video_view": 195
        },
        {
          "daily_unique_viewers": 120,
          "date": "2014-07-14",
          "video_view": 166
        },
        {
          "daily_unique_viewers": 118,
          "date": "2014-07-11",
          "video_view": 155
        },
        {
          "daily_unique_viewers": 95,
          "date": "2014-07-16",
          "video_view": 150
        },
        {
          "daily_unique_viewers": 89,
          "date": "2014-07-17",
          "video_view": 136
        },
        {
          "daily_unique_viewers": 57,
          "date": "2014-07-18",
          "video_view": 132
        },
        {
          "daily_unique_viewers": 99,
          "date": "2014-07-13",
          "video_view": 108
        }
      ],
      "summary": {
        "video_view": 2334
      },
      "account": "789967572001"
    }

Based on that results set, this entry...

    {
      "daily_unique_viewers": 73,
      "date": "2014-07-09",
      "video_view": 454
    },

...means that this account had 454 views from 73 estimated unique users on July 9, 2014.

Span Multiple Days Is Average

If you do a request which spans multiple days, like this:

    https://analytics.api.brightcove.com/v1/data?accounts=789967572001&dimensions=account&from=2014-07-09&to=2014-07-22&limit=10&format=json&fields=daily_unique_viewers,video_view

The response will contain the average value of daily_unique_viewers for the time period.

    {
      "item_count": 1,
      "items": [
        {
          "account": "789967572001",
          "daily_unique_viewers": 99,
          "video_view": 2334
        }
      ],
      "summary": {
        "video_view": 2334
      },
      "account": "789967572001"
    }

Availability of data

The uniques estimate happens in the batch processing system, which means this daily_unique_viewers value is not available in real time. The value of daily_unique_viewers will not be available for 3-5 days after the day being measured has passed. If you call the API and get a NULL response that means that the data is not available yet.

Identifying Users

Video Cloud Analytics uses a string composed of the Source IP address + the User-Agent String as the unique identifier for users.

You can also send a user identifier to the analytics data collector. This makes most sense if you have logged in or subscribed users you can identify. See the following section for information on how to send the information.

Send viewer id - Brightcove player

First, you need to set the user identifier to store that user's viewing activity.

Brightcove Player

If you are using Brightcove Player, follow these steps:

Even though viewer data is sent to Brightcove analytics automatically, you need to set the user identifier. To do this, use the setUser() method. For example:
```
myPlayer.bcAnalytics.client.setUser('viewer id');
```
On your websites that host Brightcove Player, you can use an authentication gateway or some identity management solution to keep track of viewers. Use this viewer id as the viewer identifier to pass to Brightcove analytics.

The viewer id value must be a unique string. An invalid value, such as a number, will be ignored.

It is important to set the viewer id before any source is set on the player. It should be called immediately after initializing the player.

<video-js
  id="myPlayerID"
  data-account="1752604059001"
  data-player="hyQW6GByl"
  data-embed="default"
  controls=""
  data-video-id="6156696074001"
  data-playlist-id=""
  data-application-id=""
  width="640" height="360"></video-js>
<script src="https://players.brightcove.net/1752604059001/hyQW6GByl_default/index.min.js"></script>

<script>
  videojs.getPlayer('myPlayerID').ready(function() {
    var myPlayer = this;

    // Set the viewer id for Brightcove analytics
    myPlayer.bcAnalytics.client.setUser('viewer id');
  });
</script>

When the setUser() method is used, the value is not hashed and will be sent in the clear with all subsequent beacons.
Note that the player_init event will not include the user field in this case, but all video_* events should include it.

Custom web player

If you are building a custom implementation that does not use Brightcove Player, add the user parameter to your Data Collection API requests. For details, see the Overview: Data Collection API v2 document.

On your websites that host your player, you can use an authentication gateway or some identity management solution to keep track viewers. Use this viewer id as the viewer identifier to pass to Brightcove analytics.

Total unique users

Because storing unique identifiers for all users is not feasible, we use an algorithm to estimate the total users for an account.

That means if you know the exact number of viewers and compare that to our number, you will see a small discrepancy. This error rate increases as the number of unique viewers increase.