Media analytics

What you learn

You're instantiating DIVA Player in your web front-end and relying on DIVA Back Office as the video streaming source.

The goal of this article is to build the simplest front-end to stream a video from the DIVA Back Office with active Conviva and Youbora media analytics.

Before starting

• Ensure the DIVA Back Office instance you rely on is up and running.
• Ask your video engineers team the <video id> and the related <settings URL>.
• Ensure the settings file contains the mediaAnalytics section:

  "mediaAnalytics": {
    "conviva": {
      "enabled": true,
      "customerKey": "<yourCustomerKey>",
      "playerName": "Diva",
      "viewerId": "<yourViewerIdentifier>",
      "cdnName": "Akamai",
      "touchstoneUrl": "https://<yourSubdomain>.conviva.com"
    },
    "youbora": {
      "enabled": true,
      "playerName": "Diva",
      "cdnName": "<yourCDNName>",
      "userName": "<yourViewerIdentifier>",
      "accountCode": "<yourAccountCode>"
    }
  }

  Based on your project requirements, the settings file only contains either the Conviva or Youbora configuration.

Instantiation

Media analytics code

Enrich the Basic instantiation code with the media analytics configuration:

• viewerId: Viewer id passed down to media analytics platforms.

• userName: User name passed down to media analytics platforms.

• playerVersion: Player version passed down to media analytics platforms.

• cdnName: CDN name parameter passed down to media analytics platforms.

• playerType: Player type parameter passed down to media analytics platforms.

• mediaAnalyticsEventHandler: Additional callback for media analytics events.

• customTag: A callback function that receives videoMetadata as param and returns an object of key-value pairs that will be included in the properties field of analytics events.

• customDimensions: A callback function that receives videoMetadata as param and returns an array of values that must be configured as an ordered array of values (without keys) and will be displayed in the fields param1, param2, param3, ... up to a maximum of 20.

• omLibs: Open Measurement libs passed down to media analytics platforms. This object contains the following properties:

  • omWeb: URL to omWeb library
  • omSessionClient: URL to omSessionClient library
  • omValidation: optional URL to omValidation script

• setPALNonce: Async callback used to customize Google PAL nonce requests. This function receives a nonceRequest object and returns a Promise that resolves to the modified nonceRequest.

  The nonceRequest object contains the following properties pre-filled by the DIVA Player:

  • supportedApiFrameworks: [2, 7, 9]
  • videoHeight: Video height in pixels
  • videoWidth: Video width in pixels *playerType: Player type, set to 'DIVA' *playerVersion: Player version, set to the result of the getDivaVersion() function

  Integrator can customize the following properties:

  • adWillAutoPlay: Boolean value indicating whether the ad will auto-play
  • adWillPlayMuted: Boolean value indicating whether the ad will play muted
  • continuousPlayback: Boolean value indicating whether continuous playback is enabled
  • descriptionUrl: URL to be used for the description of the ad request
  • iconsSupported: Boolean value indicating whether icons are supported
  • ppid: Player-provided ID (PPID) for the ad request
  • sessionId: Session ID for the ad request
  • url: URL to be used for the ad request

• onPALError: Error handling callback for Google PAL integration that executes when nonce generation fails

• customDeviceMetadata: Callback that generates custom device-related information for Conviva analytics integration. This function returns an object containing device metadata properties such as:

  • DeviceBrand: Device brand (e.g., "Apple", "Samsung")
  • DeviceManufacturer: Device manufacturer (e.g., "Apple Inc.", "Samsung Electronics")
  • DeviceModel: Device model (e.g., "iPhone 12", "Galaxy S21")
  • DeviceType: Device type (e.g., "Mobile", "Tablet", "Desktop")
  • DeviceVersion: Device version (e.g., "14.4", "11")
  • OperatingSystemName: Operating system name (e.g., "iOS", "Android", "Windows")
  • OperatingSystemVersion: Operating system version (e.g., "14.4", "11")
  • DeviceCategory: Device category (e.g., "Smartphone", "Tablet", "Smart TV")
  • ScreenWidth: Screen width in pixels
  • ScreenHeight: Screen height in pixels
  • ScaleFactor: Scale factor of the device (e.g., 1.0, 2.0)

Check the media analytics events for more details.

Code sample

Write the media analytics configuration:

const mediaAnalyticsParam = {
  viewerId: "DivaWebUser",
  userName: "DivaWebUser",
  playerVersion: getDivaVersion(),
  cdnName: "AKAMAI",
  playerType: "player",
  mediaAnalyticsEventHandler: console.log,
  customTag: (videoMetadata: VideoMetadataClean) => {
    return {
      tag1Name: "<tag1Name>",
      tagNName: "<tagNName>"
    };
  },
  customDimensions: (videoMetadata: VideoMetadataClean) => {
    return ["<dimension1>", "<dimensionN>"];
  },
  // Open Measurement integration
  omLibs: {
    omWeb: string,           // URL to omWeb library
    omSessionClient: string, // URL to omSessionClient library
    omValidation: string     // optional URL to omValidation script
  },
  // Google PAL (Protected Audience List) integration
  setPALNonce: (nonceRequest: NonceRequest) => Promise<NonceRequest>,  // Customize nonce requests
  onPALError: (nonceLoader: NonceLoader, nonceRequest: NonceRequest, error: any) => void,  // Error handling
  
  // Device metadata for Conviva analytics
  customDeviceMetadata: () => {
    DeviceBrand: string,
    DeviceModel: string,
    DeviceType: string,
    DeviceVersion: string,
    OperatingSystemName: string,
    OperatingSystemVersion: string,
    // Additional device properties as needed
    [key: string]: string
  }
};

Finally, add the mediaAnalyticsParam to the DIVA Player instantiation:

<DivaWebBoAdapter
  settingsURL={"<settingsURL>"}
  languageCode={"en-US"}
  config={config}
  mediaAnalyticsParam={mediaAnalyticsParam}
/>

Working sample code (.tsx)

import React from "react";
import { DivaWebBoAdapter } from "@deltatre-vxp/diva-sdk/diva-web-bo-adapter";
import "@deltatre-vxp/diva-sdk/diva-web-sdk/index.min.css";

const videoId = "<videoId>";

const libs = {
  mux: "https://cdnjs.cloudflare.com/ajax/libs/mux.js/6.2.0/mux.min.js",
  shaka: "https://cdnjs.cloudflare.com/ajax/libs/shaka-player/4.11.2/shaka-player.compiled.js",
  hlsJs: "https://cdn.jsdelivr.net/npm/hls.js@1.5.7",
  googleIMA: false,
  googleDAI: false,
  googleCast: false,
  threeJs: false
};

const config = {
  videoId: videoId,
  libs: libs,
};

const customTags = {
    "userType": "premium",
    "device": "smart_tv",
    "sessionID": "12345ABC"
};

const customDimensionsArray = [
    "premium",       // param1
    "smart_tv",      // param2
    "12345ABC",      // param3
    "EU",            // param4
    "HD",            // param5
];

const mediaAnalyticsParam = {
  viewerId: "DivaWebUser",
  userName: "DivaWebUser",
  playerVersion: getDivaVersion(),
  cdnName: "AKAMAI",
  playerType: "player",
  mediaAnalyticsEventHandler: console.log,
  customTag: () => {
    return customTags;
  },
  customDimensions: () => {
    return customDimensionsArray;
  },
  setPALNonce: (nonceRequest: NonceRequest): Promise<NonceRequest> => {
    // Customize the nonce request here if needed
    // ...
    // Return the modified nonce request
    return nonceRequest;
  },
  onPALError: (nonceLoader: NonceLoader, nonceRequest: NonceRequest, error: any): void => {
    // Log detailed error information
    console.error('PAL nonce generation failed', {
      error,
      requestDetails: {
        playerType: nonceRequest.playerType,
        playerVersion: nonceRequest.playerVersion,
        videoWidth: nonceRequest.videoWidth,
        videoHeight: nonceRequest.videoHeight,
        url: nonceRequest.descriptionUrl
      }
    });
  },
  customDeviceMetadata: () => {
    return {
      DeviceBrand: "<brand>",
      DeviceModel: "<model>",
      DeviceType: "<type>",
      DeviceVersion: "<version>",
      OperatingSystemName: "<osName>",
      OperatingSystemVersion: "<osVersion>",
      ...
    };
  }
};

const props = {
  settingsUrl: "<Settings URL>",
  languageCode: "en-US",
  languageDictionary: "en-US",
  onDivaBoAdapterError: console.error,
  config: config,
  mediaAnalyticsParam: mediaAnalyticsParam
}

function App() {
  return (
    <DivaWebBoAdapter
      {
      ...props
      }
    />
  );
}

export default App;