Integrating Third-Party Players with IQ Using the JS SDK

Use the new Ooyala IQ JavaScript SDK to communicate your third-party player's events to Ooyala IQ. You must integrate this SDK with your player for IQ to work. The JavaScript SDK only supports web-based platforms that support JavaScript. Use the Ooyala IQ JSON API for devices that do not support JavaScript or the Ooyala IQ SDK for Roku for Roku devices.

Events

Ooyala IQ needs to receive information about player events to properly display analytics data. The figure below shows the flow of when each player event should be recorded.

  • setDeviceInfo: Called once to setup the device information.
  • setPlayerInfo: Called once to setup player information.
  • reportPlayerLoad: Called when the player is created (loaded).
  • initializeMedia: Measures when a piece of video content is loaded and displayed within the player before it gets played (if a pre-roll ad is present, this should not be captured until the pre-roll ad is complete and the main video loads). This is called whenever the loaded video changes, also when the player goes to the next video in a playlist, for example.
  • setMediaDuration: Called after the media is initialized.
  • reportPlayRequested: Measures when the play button is triggered either manually or automatically. The requested content could be ad content or the actual video content.
  • reportPlaybackStarted: Called when the media has successfully started playback.
  • reportPlayHeadUpdate: Called when the video playhead moves. This event is reported periodically (at least every 2 to 3 seconds).
  • reportPause: Called when the video is paused.
  • reportResume: Called when the video is resumed after it has been paused.
  • reportSeek: Called when the viewer seeks through the video, jumping from one time in the video to another.
  • reportReplay: Called when the video is replayed.
  • reportComplete: Called when the full length of the video was played.
  • reportCustomEvent: Called whenever you want to report custom events to Ooyala IQ.
    Note: At this time custom events can be ingested, but we can only store the information. Ooyala IQ is not able to process custom events, and you will not be able to access this information from the Ooyala IQ backend. However, you may wish to start sending Ooyala IQ your custom events now so that you have the data there for when custom events are supported by Ooyala IQ.

Additional Data

Ooyala IQ also collects the following data from the player for analytics purposes:
  • Device information (setDeviceInfo): the device's unique identifier, which is generated if not set, the browser used to load the player, the browser version, the operating system, the device type (like, mobile or desktop), the device's brand and model. This information is used for the Device Panel in IQ.
  • Player information (setPlayerInfo): the player's unique identifier, player name and player version.

JavaScript SDK

The JavaScript SDK is the file analytics.js and is hosted at https://analytics.ooyala.com/static/v3/analytics.js. You can view API documentation for the SDK at http://apidocs.ooyala.com/iq_standalone/index.html.

The following diagram shows the architecture for any third-party player integration with Ooyala IQ (where Player is the third-party player).

  1. To integrate with the JavaScript SDK, you need to use an adapter that translates your player's events and APIs to correlate with the events defined in the Ooyala IQ JavaScript SDK.

    You can use an Ooyala adapter or create your own adapter.

    Ooyala provides adapters for the relevant standard versions of the following platforms:
    Note: These adapters, except for the Xbox One adapter, do not yet support reporting seek events or custom events, nor do they collect information about the device.
    You can implement our integration solutions yourself for free, or Ooyala Professional Services can help you implement the above solutions for a fee. All other web-based players or native mobile/tablet SDKs that can run on JavaScript can be supported as well through an Ooyala Professional Services engagement, at a cost.

    Alternatively, you can create an adapter yourself. If you create the adapter, you will need to host it. If Ooyala creates the adapter, Ooyala will host it. If you create an adapter, the adapter must report the following information to the Ooyala JavaScript SDK. See the figure in the Events section above for the order in which events must be captured.

  2. Create your third-party player.
    1. Reference the analytics.js in the page where your player is hosted. This needs to be done for any page that has a player.
    2. Include the adapter code (see adapter-specific documentation for details).
    3. (Optional) Specify a media content type with the MediaContentType parameter to show if the mediaid specifies an Ooyala video asset or a non-Ooyala video asset. You can set the media content type as one of the two following values. If you do not specify a media content type, the default value is EXTERNAL_CONTENT (non-Ooyala media assets).
      • OOYALA_CONTENT: Indicates that the mediaid is an Ooyala embed code. To get the information you need to specify the Ooyala asset, make the Backlot API query: /assets/<ASSET EMBED CODE>/streams for the asset and copy the result of the desired encoding. The example below shows how OOYALA_CONTENT is specified with the JW Player adapter.
        <script type="text/javascript">
            var jwPlayer = jwplayer("video").setup({
                file: 'pathToYourOoyalaMp4VideoAsset',
                mediaid: 'yourOoyalaEmbedCode',
                type: 'mp4'
            });
            var jwOoyalaReporter = Ooyala.Analytics.JWReporter("<pcode>", jwPlayer, {
                contentType: Ooyala.Analytics.MediaContentType.OOYALA_CONTENT
            });
        </script>
      • EXTERNAL_CONTENT: Indicates that the mediaid is not an Ooyala embed code (and is customer-defined media ID from a non-Ooyala CMS). The example below shows how EXTERNAL_CONTENT is specified with the JW Player adapter.
        <script type="text/javascript">
            var jwPlayer = jwplayer("video").setup({
            file: 'pathToYourVideoAsset',
            mediaid: 'yourMediaID'
            });
            });
            var jwOoyalaReporter = Ooyala.Analytics.JWReporter("<pcode>", jwPlayer, {
                contentType: Ooyala.Analytics.MediaContentType.EXTERNAL_CONTENT
            });
        </script>
      Note: The Ooyala IQ JavaScript SDK does not support specifying multiple content types within the same player instance in a page. However, we do support specifying multiple content types for different players on the same page. For example, we do not support analytics for the use case where you have one player on a page that plays Ooyala video assets and external assets. We do support analytics for the use case where you have two players on the same page where one plays Ooyala video assets and the other plays external (non-Ooyala video assets).

Was this article helpful?