Conviva Plugin

Mobile		Web	TV Platforms

DIVA Conviva Plugin

The DIVA Conviva Plugin is an out-of-the-box implementation of a Media Analytics listener which is able to receive events from Diva and directly send them to Conviva.

This plugin is implemented for iOS, tvOS, Android and Web and is used in all our Integration Demo projects as well as in the DIVA Chromecast Receiver app.

The main parameters of this plugin are:

• Touchstone URL: Used while debugging the integration using the Conviva Touchstone online tool
• CDN Name: A string identifying which CDN solution is used by the project
• ViewerID: An identifier of the user or playback session
• customTagGenerator: A function used by the plugin to calculate Conviva Custom TAGs dynamically. Every time the VideoMetadata gets updated and receives a parameter, the function is called.
• player version: the version of the diva player used to provide additional informations (only Web TV)

Conviva documentation for more information.

Web

// Set plugin parameters
const convivaConfig = {
  playerVersion: Diva.version,
  customerKey: "<INSERT-CONVIVA-CUSTOMERKEY-HERE>",
  playerName: 'Diva',
  viewerId: "<INSERT-VIEWERID-HERE>",
  cdnName: "<INSERT-CDN-NAME-HERE>",
  customTagGenerator: (videoMetadata) => ({
    // just an example, custom tags are project-specific
    platform: 'Web',
    videoId: videoMetadata.videoId,
    eventId: videoMetadata.eventId,
    videoTitle: videoMetadata.title
  }),
  gatewayUrl: divaParams.debug ? "<INSERT-DEBUG-TOUCHSTONE-HERE>" : undefined,
}

mediaAnalyticPlugin = new d3lib.ConvivaPlugin()
mediaAnalyticPlugin.init(convivaConfig)
window.addEventListener("beforeunload", (e) => {
  mediaAnalyticPlugin.detachPlugin();
})

// Start Diva
const {
  element: divaElement, 
  api: divaAPI 
} = new Diva('.diva-player-container', {
  // ...
  onMediaAnalyticEvent: mediaAnalyticPlugin.handleEvent
})

Web TV

React version

const conviva = new ConvivaPlugin()
conviva.init({
  playerVersion: '<INSERT-PLAYER-VERSION-HERE>',
  customerKey: '<INSERT-CONVIVA-CUSTOMERKEY-HERE>',
  playerName: 'Diva',
  viewerId: '<INSERT-VIEWERID-HERE>',
  cdnName: '<INSERT-CDN-NAME-HERE>'
})

// ...

<DivaWebTV
  // ...
  onMediaAnalytics={conviva.handleEvent}
  // ...
/>

Vanilla js version

const conviva = new ConvivaPlugin()
conviva.init({
  playerVersion: '<INSERT-PLAYER-VERSION-HERE>',
  customerKey: '<INSERT-CONVIVA-CUSTOMERKEY-HERE>',
  playerName: 'Diva',
  viewerId: '<INSERT-VIEWERID-HERE>',
  cdnName: '<INSERT-CDN-NAME-HERE>'
})

const diva = new divaWebtv.createDivaWebTV (el, {
    // ...
    onMediaAnalytics: conviva.handleEvent
    // ...
});

Web Chromeless

React version

const conviva = new ConvivaPlugin()
conviva.init({
  playerVersion: '<INSERT-PLAYER-VERSION-HERE>',
  customerKey: '<INSERT-CONVIVA-CUSTOMERKEY-HERE>',
  playerName: 'Diva',
  viewerId: '<INSERT-VIEWERID-HERE>',
  cdnName: '<INSERT-CDN-NAME-HERE>'
});

const config = {
  // ...
  onMediaAnalytics: conviva.handleEvent
  // ...
};

// ...

<DivaWebChromelessComponent
  // ...
  config={config}
  // ...
/>

Vanilla js version

const conviva = new ConvivaPlugin()
conviva.init({
  playerVersion: '<INSERT-PLAYER-VERSION-HERE>',
  customerKey: '<INSERT-CONVIVA-CUSTOMERKEY-HERE>',
  playerName: 'Diva',
  viewerId: '<INSERT-VIEWERID-HERE>',
  cdnName: '<INSERT-CDN-NAME-HERE>'
});

const config = {
  // ...
  onMediaAnalytics: conviva.handleEvent
  // ...
};

const diva = new divaWebChromelessSdk.createDivaWebChromeless (el, config,
    {
      muted: false,
      volume: 1,
      adCover: true,
      videoCover: true
    });

iOS

// Set plugin parameters
let tracker = await ConvivaMediaAnalytics(
    customerKey: "<INSERT-CONVIVA-CUSTOMERKEY-HERE>",
    touchstoneURL: Diva.isDebugMode
        ? "<INSERT-DEBUG-TOUCHSTONE-HERE>"
        : nil,
    settings: .init(
        cdnName: "<INSERT-CDN-NAME-HERE>",
        playerName: "Diva",
        viewerId: "<INSERT-VIEWERID-HERE>",
        playerVersionFramework: Diva.version.framework(),
        applicationBuildVersion: (Bundle.main.infoDictionary?["CFBundleVersion"] as? String) ?? Diva.version.framework(),
        logLevel: Diva.isDebugMode ? .debug : .notice,
        tags: { metadata in [
            // just an example, custom tags are project-specific
            "platform": "iOS",
            "playerVersion": Diva.version.framework(),
            "videoId": metadata.videoId,
            "videoTitle": metadata.title
        ] }
    )
)

// Start diva
var config = DivaConfiguration(/* ... */)
config.onMediaAnalyticsUpdate = { 
  tracker.handle($0) 
}
let diva = await Diva(configuration: config)

tvOS

As per Conviva documentation, integrating apps need to add "-ObjC" to "Other Linker Flags" of Xcode.

// Set plugin parameters
let tracker = await ConvivaMediaAnalytics(
    customerKey: "<INSERT-CONVIVA-CUSTOMERKEY-HERE>",
    touchstoneURL: isDebugMode
        ? "<INSERT-DEBUG-TOUCHSTONE-HERE>"
        : nil,
    settings: .init(
        cdnName: "<INSERT-CDN-NAME-HERE>",
        playerName: "Diva",
        viewerId: "<INSERT-VIEWERID-HERE>",
        playerVersionFramework: DivaTV.version.framework(),
        applicationBuildVersion: (Bundle.main.infoDictionary?["CFBundleVersion"] as? String) ?? DivaTV.version.framework(),
        logLevel: .notice,
        tags: { metadata in [
            // just an example, custom tags are project-specific
            "platform": "tvOS",
            "playerVersion": Diva.version.framework(),
            "videoId": metadata.videoId,
            "videoTitle": metadata.title
        ] }
    )
)

// Start diva
var config = DivaTVConfiguration(/* ... */)
config.onMediaAnalyticsUpdate = { 
  tracker.handle($0) 
}
let initializedDiva = await DivaTV(configuration: config)
present(initializedDiva.playerViewController, animated: true)

Android

// Set plugin parameters
val mediaAnalyticsConfiguration = MediaAnalyticsConfiguration(
    divaVersion = com.deltatre.divaandroidlib.BuildConfig.VERSION_NAME,
    playerName = "Diva",
    cdnName = "<INSERT-CDN-NAME-HERE>",
    viewerID = "<INSERT-VIEWERID-HERE>",
    customerKey = "<INSERT-CLIENTID-HERE>",
    gatewayUrl = if (DivaEngine.debug) "<INSERT-DEBUG-TOUCHSTONE-HERE>" else "",
    customTagGenerator = {
      // just an example, custom tags are project-specific
      mapOf(
        Pair("platform", "android"),
        Pair("videoId", it.videoId),
        Pair("videoTitle", it.title),
        Pair("eventId", it.eventId),
        //...
      )
    })
)

// Create plugin instance
  val mediaAnalyticsCallback = DivaConvivaMediaAnalytics(
            context,
            lifecycleOwner,
            mediaAnalyticsConfiguration
        )

// Initialise the ViewModel with the media analytics parameter
divaPlaybackViewModel.init(..., mediaAnalyticsCallback, ...)

Android TV

// Set plugin parameters
val mediaAnalyticsConfiguration = MediaAnalyticsConfiguration(
    divaVersion = com.deltatre.divaandroidlib.BuildConfig.VERSION_NAME,
    playerName = "Diva",
    cdnName = "<INSERT-CDN-NAME-HERE>",
    viewerID = "<INSERT-VIEWERID-HERE>",
    customerKey = "<INSERT-CLIENTID-HERE>",
    gatewayUrl = if (DivaEngine.debug) "<INSERT-DEBUG-TOUCHSTONE-HERE>" else "",
    customTagGenerator = {
      // just an example, custom tags are project-specific
      mapOf(
        Pair("platform", "android"),
        Pair("videoId", it.videoId),
        Pair("videoTitle", it.title),
        Pair("eventId", it.eventId),
        //...
      )
    })
)

val mediaAnalyticsCallback = DivaConvivaMediaAnalytics(
        context,
        lifecycleOwner,
        mediaAnalyticsConfiguration
)

// Initialise the ViewModel with the media analytics parameter
divaPlaybackViewModel.init(..., mediaAnalyticsCallback, ...)

Roku

// Set plugin parameters
function getConvivaConfig(state as string) as dynamic
    config = {}
    config.divaVersion = "<INSERT-DIVA_VERSION-HERE>"
    config.customerKey = "<INSERT-CLIENTID-HERE>"
    config.playerName = "diva"
    config.viewerId= "<INSERT-VIEWERID-HERE>"
    config.cdnName= "<INSERT-CDN-NAME-HERE>"   
    if (state = "DEBUG")
        config.gatewayUrl = "<INSERT-DEBUG-TOUCHSTONE-HERE>"
    end if
    return config
end function

// Create Conviva plugin instance
m.convivaAnalytics = CreateObject("roSGNode", "ConvivaAnalytics")

// Initialize Conviva with configuration
m.convivaAnalytics.callFunc("initConviva", getConvivaConfig("DEBUG"))

// Connect Conviva with Diva Player media analytics events handler
sub onMediaAnalyticsEventHandler(evt)
    data = evt.getData()
    if (m.convivaAnalytics <> Invalid)
        m.convivaAnalytics.callFunc("handleEvent", data)
    end if
end sub

// Close Conviva plugin
sub closeConviva()
    if (m.convivaAnalytics <> Invalid)
        m.convivaAnalytics.callFunc("closeConviva")
        m.convivaAnalytics = Invalid
    end if
end sub