Last updated: Sep-16-2024
Overview
Video Analytics can be used to understand and optimize your video content served by Cloudinary. The metrics are automatically collected for all videos delivered through the Cloudinary Video Player and you can also manually collect this data for your own video players using our JavaScript library.
1.9.9
.You can access the analytics by opening the Video sub-menu in your Cloudinary Console and selecting Analytics. Here, you will be presented with a set of metrics and graphs that show how your video content has been delivered, including:
- Plays: The total number of video plays during the specified time period. This show the popularity of your video content.
- Unique Viewers: The total number of individual users who have watched a video during the specified time period. This offers insights into the reach of your video content.
- Watch Time: The total duration viewers have spent watching all of your videos. This is another indicator of video content reach.
- Watch Rate: The percentage of total time videos have been watched in relation to the total duration. This can be used to identify which videos are the most engaging.
- Play Rate: The percentage of video plays in relation to the number of times the video player was loaded. This can be used to highlight any issues with discoverability of videos.
Other more specific metrics include:
- Top Videos: The most popular videos based on the number of views. This helps identify your best-performing content.
- Top Devices / OS / Browsers / Countries: A set of graphs showing how your video content is consumed. This offers insights into the demographics of your users, and can be used to optimize the formats and sizes you use to deliver your videos.
You can also export all of the data as a CSV from the UI or programmatically retrieve video analytics data using our Video Analytics API.
Video analytics for other players
To collect analytics for video players other than the Cloudinary Video Player, install our JavaScript library and include some configuration on any pages that include a video player. The library targets the HTML5 video tag and is designed to work with any other video players that use this tag.
Usage
1. Install the package:
2. Import the library:
3. Connect the analytics:
Connect the analytics by calling the connectCloudinaryAnalytics
method and provide the video element as a parameter. For example, if your video element has the id video-player
:
4. Start tracking:
Start tracking analytics for any Cloudinary video by calling the startAutoTracking
method:
Alternatively, to track each video manually, call the startManualTracking
method, providing your Cloudinary cloud name and the public ID of the video you want to manually track:
- Auto and manual tracking cannot be used together for the same video element. Manual tracking should only be used in cases where you need to track certain videos, you want to track a video tag element which is dynamic, or you have custom domains which require providing
cloudName
andpublicId
. - Manual tracking may be required for videos where the public ID or cloud name aren't able to be automatically identified.
- When using manual tracking, you'll need to call
startManualTracking
whenever the video source is changed, this will end the previous session and start a new one for the new video.
Custom fields
Alongside the fields captured automatically with video analytics, you can also capture up to 5 additional custom fields of your own choosing. This allows you to define, submit, and report on data points specific to your use case. This could be data such as page title, category, SKU, or subscription plan type.
Once these metrics have been captured they will appear in your Video Analytics dashboard, allowing you to filter your data based on these metrics.
To capture custom fields, use the cloudinaryAnalytics
constructor parameter of the Cloudinary Video Player or when when initiating analytics tracking using the cloudinary-video-analytics
JavaScript library.
Both methods take a customData
object with up to five customData
keys each named customData
with a number suffix (customData1
,customData2
,customData3
,customData4
,customData5
).
Below is an example of a custom data structure with 5 ecommerce related metrics:
Video player example
Here is an example for sending custom fields with the video player:
Video analytics library example
Here is an example for sending custom fields using the video analytics library with auto tracking:
Access video views data programmatically
To retrieve analytics data for your video views programmatically, make use of our Video Analytics API. Get detailed information about all of the views your videos have received, and use expressions to limit the results based on certain conditions such as public ID and when the view ended. You can use the returned data as part of your own analytics systems or dashboards.
Authentication
The API uses Basic Authentication, and your Cloudinary API Key and API Secret (which can be found on the API Keys page of your Console Settings) are used for the authentication. Send your credentials as part of the request header, for example:
Authorization: Basic <your basic auth token>
Where your basic auth token is a base64-encoded <api_key>:<api_secret>
string.
Endpoint
The base URL to access video analytics data is:
https://api.cloudinary.com/v1_1/<cloud_name>/video/analytics
Syntax
GET views?<expression>&<max_results>&<sort_by>&<next_cursor>
Parameters
Query Parameters
Parameter | Type | Description |
---|---|---|
expression |
String | A set of conditions used to limits the results to rows that match those conditions. See the expressions section for more details. |
max_results |
Integer | Specifies the number of items to include in the response. Default: 5 . Minimum: 1 . Maximum: 500 . |
next_cursor |
String | The value to be used to obtain the next batch of results. |
sort_by |
String | Specifies the expression field by which to sort the results. Possible fields: view_ended_at , video_duration ,view_watch_time . By default results are sorted by most recent view_ended_at value. Prepend values with a - to reverse the order. |
Examples
- Retrieve video views data for the video with the public id
skate
:
- Retrieve video views data for videos with a duration greater than 10 seconds and view ended date less than (older than) the UNIX timestamp
1695039446
:
The Video Analytics API is currently not supported by our SDKs, but you can make a direct call to the API as shown in the examples above.
Response
The response includes a data array
, where each entry is an object containing information about a specific video view, along with a request ID and the next cursor value.
Here's an example response:
Expressions
The expressions parameter is used to limit the results based on a set of provided conditions.
Fields
The available fields for refining your queries, all except video_public_id
and view_ended_at
can also be queried for null values.
Field Name | Type | Examples | Details |
---|---|---|---|
view_ended_at |
Date | view_ended_at<1486929412 |
The date when the video view ended as a UNIX timestamp. |
video_public_id |
String | video_public_id=elephants |
The full public ID of the video, including folder names when relevant. |
video_duration |
Numeric | video_duration>20 |
The duration in seconds of the video. |
viewer_application_name |
String | viewer_application_name=Chrome |
The application used to view the video. |
viewer_location_country_code |
String | viewer_location_country_code=GB |
The 2-digit ISO country code of the viewer location. |
viewer_os_identifier |
String | viewer_os_identifier=Mac OS X 10.15.7 |
The full identifier for the viewers operating system. |
view_watch_time |
Numeric | view_watch_time<5 |
The length of time the video was viewed. |
Operators
Operators allow you to both define the relationship between the field and the value and combine expressions using the boolean AND operator.
The field operators you can use will vary depending on the field type, with the following operators available:
-
=
- finds results where the value is an exact match, can be used with all fields -
<
- finds results where the value is less than the given condition -
>
- finds results where the value is greater than the given condition
The boolean AND
operator can be used to combine expressions, for example:
video_public_id=skate AND view_ended_at<1695037024
Custom Cloudinary Video Player analytics providers
If you'd like to capture custom analytics to pass to your Google Analytics account or other analytics trackers, you can manually push any events exposed by the Video Player.
You can either set the analytics parameter to true
, which monitors all available events except timeplayed
(percentplayed
is monitored), or you can specify the specific events you want to monitor, including additional event sub-settings where relevant ('percentsplayed', percents
and 'timesplayed', times
. See example below).
Or
You will then need to send the analytics to your chosen service, for example Google Analytics. See the relevant analytics documentation for more information on how to send the chosen metrics.