Integration Instructions

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.

Remotely Instrument Custom Events and Metadata

Overview

On-demand custom data, also known as remote instrumentation, allows you to collect new custom events and metadata from your Javascript applications without writing new code or waiting for an app release.

This feature uses the Element Query method, which empowers you to target any HTML element in the DOM using a CSS selector. Once targeted, you can either:

• Create Custom Events: Trigger a new custom event when a user interacts with the element (e.g., "Click", "Hover", "View").

• Collect Custom Metadata: Scrape the value of an element's attribute (like href, src, or data-product-sku) and attach it to events as custom metadata.

Prerequisites

Before you can create an on-demand key, your account must have at least one Javascript-based Collector Configuration.

Note: If you do not have a Javascript-based Collector Configuration, the "Create a new key" option will be disabled.

How to Create a New On-Demand Key

You can create a new on-demand key from the "Mapped Keys" section of an existing alias.

1. Navigate to Settings > Custom Data.

2. Select a custom data alias from the side panel (e.g., "product_view" or "product_price").

3. In the main panel, find the Mapped Keys section.

4. Click the ADD NEW button.

5. The "Map a key to [alias name]" overlay will appear. This overlay allows you to map existing unmapped keys.

6. At the bottom of this overlay, click + Create a new key. The "Create a key for [alias name]" overlay will open.

The fields shown in this overlay depend on whether the parent alias is an "Event" or "Metadata".

Event Key Configuration

If you are creating a key for an Event alias , you will see the following fields:

• Key Name: A unique name for this key.

• Collector Configuration: A dropdown list of your available Javascript-based Collector Configurations. If you only have one, it will be pre-selected.

• Element Selector Query: The CSS selector query to identify the HTML element.

• Interaction Type: A dropdown to select the user interaction that will trigger the event. Options include interactions like "Click", "Double Click", "Hover", "View".

Metadata Key Configuration

If you are creating a key for a Metadata alias , you will see more detailed fields:

• Key Name: A unique name for this key.

• Collector Configuration: A dropdown list of your available Javascript-based Collector Configurations.

• Element Selector Query: The CSS selector query to identify the HTML element

• Element Attribute: The specific attribute of the element whose value you want to collect.

• Results Limit: A dropdown to limit how many matching elements' values are collected.

• Event Specific: A radio button to determine if this metadata should be collected all the time or only with a specific event.

  • No (Default): The metadata will be collected and attached to any event fired by the Datazoom SDK.

  • Yes: If you select "Yes" , a new dropdown will appear allowing you to select a specific Event alias. The metadata will only be collected when that specific event occurs.

How On-Demand Keys Work at Runtime

• For Event Keys: When the Datazoom SDK is loaded on your web application , it will listen for the Interaction Type (e.g., "Click") on the element(s) matching your Element Selector Query. When the user performs that action, the custom event associated with the alias is fired and collected.

• For Metadata Keys: When the Datazoom SDK is loaded and an event is fired , the SDK will find the element(s) matching your Element Selector Query. It will then get the value from the specified Element Attribute and attach that value to the fired event as custom metadata.

Editing an On-Demand Key

You can edit an on-demand key at any time.

1. In the Mapped Keys table, find the row you want to edit.

2. Click on the row, ensuring its Method is "Element Query".

3. The "View / Edit Key for [alias name]" overlay will appear.

4. You can see and edit all the previously saved values. The "Save" button will become enabled if you make changes and all fields are valid.