How to send custom events and metadata

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.

Contact Datazoom to learn more!

Custom Metadata

Custom metadata can be set as a JavaScript plain object, such as the following:

datazoom.setMetadata({ key1: 1, key2: "default" });

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:

datazoom.setMetadata(null);

The current custom metadata (which was previously set or was restored from the storage) can be read back as in the following example:

var oldMetadata = datazoom.getMetadata(); // read back
if (oldMetadata) {
    oldMetadata.pageCount ++;
}
datazoom.setMetadata(oldMetadata || { pageCount: 1 }); // set the updated metadata

An existing Custom Metadata field can be cleared by reading back the list of Custom Metadata and then deleting a specific item.

var currData = datazoom.getMetadata();
delete currData.foo; // clear a key
currData.bar = “baz”; // update a key
datazoom.setMetadata(currData);

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_“

datazoom.generateEvent("ButtonClick");

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:

datazoom.generateEvent("ButtonClick", { buttonName: "xyz" });

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.

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:

var main_video_player; // player initialized to play main feature
var sub_video_player; // player initialized to play supplementary content

var main_dz_context = datazoom.createContext(main_video_player);
var sub_dz_context = datazoom.createContext(sub_video_player);

// set custom metadata fields for the browser session globally
datazoom.setMetadata({ some_token: "xyz" });

// set custom metadata fields for a specific player only
main_dz_context.setMetadata({ player_desc: "main" });
sub_dz_context.setMetadata({ player_desc: "supplementary" });

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.

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:

var main_video_player;
var main_dz_context = datazoom.createContext(main_video_player);
var main_player_vid_index = 0;

datazoom.on(datazoom.sdkEvent.CONTENT_SESSION_START, function(context) {
    if (context == main_dz_context) {
        context.setMetadata({ vid_index: main_player_vid_index });
        main_player_vid_index ++;
    }
});

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:

var main_video_player; // player initialized to play main feature
var sub_video_player; // player initialized to play supplementary content

var main_dz_context = datazoom.createContext(main_video_player);
var sub_dz_context = datazoom.createContext(sub_video_player);

sub_dz_context.generateEvent("SomePlayerEvent", optionalExtraMetadata);

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 datazoom.generateEvent() method:

datazoom.generateEvent("ButtonClick", { buttonName: "xyz" }, true /*appSessionEvent*/);

Read Back Custom Metadata

Both the globally set custom metadata and player specific custom metadata can be read back as the following (the current metadata is returned as a JavaScript plain object):

var globalMetadata = datazoom.getMetadata();
var mainPlayerMetadata = main_dz_context.getMetadata();
var subPlayerMetadata = sub_dz_context.getMetadata();

Overridable 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:

console.log(datazoom.overridableMetadata);
// prints:
// { ADVERTISING_ID: "datazoom_advertising_id"
//   ASSET_ID: "datazoom_asset_id"
//   CASTING: "datazoom_casting"
//   PLAYER_NAME: "datazoom_player_name"
//   PLAYER_VERSION: "datazoom_player_version"
//   STREAMING_TYPE: "datazoom_streaming_type"
//   TITLE: "datazoom_title" }

For example, to set global custom and overridable metadata for the browser session globally:

var appMetadata = {};

appMetadata.foo = "foo"; // a custom metadata
appMetadata[datazoom.overridableMetadata.PLAYER_NAME] =
    "my_awesome_player"; // an overridable metadata, to set the player name

datazoom.setMetadata(appMetadata);

Similarly, custom and overridable metadata can be set for a particular content session through the collector context object:

datazoom.on(datazoom.sdkEvent.CONTENT_SESSION_START, function(context) {
    var contentMetadata = {};

    contentMetadata.bar = "bar"; // a custom metadata
    // the following are for overridable metadata
    contentMetadata[datazoom.overridableMetadata.TITLE] = "my_video_title";
    contentMetadata[datazoom.overridableMetadata.ASSET_ID] = "xyz1234";
    contentMetadata[datazoom.overridableMetadata.STREAMING_TYPE] = "VOD";

    context.setMetadata(contentMetadata);
});

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

Connector Effect

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.