Simple Use Cases
The following samples are suitable for simple use cases, where the browser page usually contains only a single video player, and the custom metadata are managed as a whole for the browser session.
The custom metadata will be persisted in the
sessionStorage, so it will remain valid until the browser tab is closed, or until it is cleared with the following call:
The current custom metadata (which was previously set or was restored from the storage) can be read back as in the following example:
An existing Custom Metadata field can be cleared by reading back the list of Custom Metadata and then deleting a specific item.
Generate Custom Event
To generate a Datazoom event with a custom name, call the following function with the custom name (which will be prefixed with “Custom_“
An optional argument can be included in the same function to add additional metadata (for the event generated by the specific call only) to the event message:
By default, if available, the playback related data points (such as the metrics of the current content session) from the first player on the page will be included in the custom event message generated.
If the extra metadata specified with the
generateEvent() call has duplicated keys as in the existing metadata previously set, the value from the extra metadata will take precedence over the existing one. However, since the extra metadata is only effective to the specific call where it is specified, the existing metadata’s value of the same key will not be affected in other places.
Advanced Use Cases
The custom event/metadata interface can support more advanced use cases, such as when there are multiple players playing on the page, or when it is necessary to control the scope of applying custom metadata fields.
Player Specific Custom Metadata
In addition to specifying custom metadata fields for the browser session globally (through the
datazoom.setMetadata() method), a separate set of custom metadata fields can be specified and scoped to a specific player on the page. For example, assume that two players are on the page and each of them has an associated Datazoom collector context initialized, the
setMetadata() method exposed by a collector context object can be used to set player specific custom metadata:
In the example above, the custom metadata fields set globally (“some_token“) will be included in the Datazoom events for both players. On the other hand, the custom metadata fields set specifically through a player’s associated context (“player_desc“) will be included only in the events for the corresponding player.
If the player specific custom metadata has duplicated keys as the globally specified custom metadata, the player specific values will take precedence.
Listen for CONTENT_SESSION_START Event to Update Custom Metadata on Content Session Boundary
Since a player can be used to play multiple content videos sequentially, it is useful to have the ability to update custom metadata fields (specifically for the player or globally) when a new content session has started. This can be achieved by registering a handler for the Datazoom SDK notification CONTENT_SESSION_START as the following:
Generate Custom Event Specific to a Player
As described above, the
datazoom.generateEvent() method can be used to generate a Datazoom custom event which automatically includes all data points (standard or custom) collected for the first player on the page. However, in a more complex scenario there could be multiple players on the page and the intention is to generate a custom event carrying data collected for a player other than the first one. For such a case, the
generateEvent() method exposed by a collector context object can be used:
Generate Custom Event with Session Data Only
Sometimes a lightweight custom event, which includes only the browser session data points and none of the player related data points, might be preferred. This can be achieved by specifying the third and optional argument of the
Read Back Custom Metadata
Some standard Datazoom metadata are overridable through the
setMetadata() method of a collector context or the
datazoom object. The
datazoom.overridableMetadata object enumerates the keys that can be used to set the value of an overridable metadata:
For example, to set global custom and overridable metadata for the browser session globally:
Similarly, custom and overridable metadata can be set for a particular content session through the collector context object:
Custom Metadata Reserved Names
Some data values that are key to functionality or reporting on your analytic systems have been designated as
Reserved Names so that these values can be handled properly within the context of the receiving Connector.
Current List of Reserved Names
session identifier exposed by the Amplitude plugin on the page.
unique user identifier set by the GA SDK. Application should retrieve this value from the installed GA SDK.
unique user identifier set by the Mixpanel SDK. Application should retrieve this value from the installed Mixpanel SDK.
unique internal user identifier set by the customer's identity management system.
Genre classification of the content
When a Reserved Name is properly set using Custom Metadata, it will be correctly placed within designated fields within the relevant Connector. For all other Connectors, these values will be treated like regular Custom Metadata and passed through if the Connector can support custom key value pairs.