Bitmovin SDK Integration Guide

This guide is for integrating the MediaMelon Player SDK for the javascript based Bitmovin Web Player v8

Step 1: Add the MediaMelonPlayer SDK

CDN URL:

<script type="text/javascript" src="https://sdk.mediamelon.com/SDK_RELEASES/Javascript/bitmovin/2.5.0/mmsmartstreaming_bitmovinplayer.min.js"></script>

NPM:

npm i [email protected]

import {MMBitmovinSDKIntgr} from 'mediamelon-js-bitmovin-sdk'

Step 2: Register and Initialize the MediaMelon Player SDK

<customer_id> is your MediaMelon-assigned Customer ID. If you do not know your Customer ID, contact MediaMelon at [email protected]

After the player instance has been created, create a new Plugin object, register, report player Info, and then initialize the plugin as shown below:

<body>
  <div id="video"></div>
  <script>
      const player = new bitmovin.player.Player(document.getElementById('video'), config);
      const playerEvent = bitmovin.player.playerEvent;

      var contentMetadata = {
        "assetName": "ASSET_NAME",
        "assetId": "ASSET_ID",
        "videoId": "VIDEO_ID",
        "contentType": "CONTENT_TYPE",
        "genre": "GENRE",
        "drmProtection": "DRM_PROTECTION",
        "episodeNumber": "EPISODE_NUMBER",
        "season": "SEASON",
        "seriesTitle": "SERIES_TITLE",
        "customTags": {
          "key1": "VALUE_STRING1",
          "key2": "VALUE_STRING2"
        }
      };

      var mmBitmovinPlugin = new MMBitmovinSDKIntgr();
      mmBitmovinPlugin.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", <hashSubscriberId>);
      mmBitmovinPlugin.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
      mmBitmovinPlugin.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
      
      mmBitmovinPlugin.reportExperimentName("EXPERIMENT_NAME");
      mmBitmovinPlugin.reportSubPropertyId("SUB_PROPERTY_ID");       
      mmBitmovinPlugin.reportAppInfo("APP_NAME", "APP_VERSION");
      mmBitmovinPlugin.reportDeviceId("DEVICE_ID");
      
      const streamURL = 'https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8';
      var isLive = false;
      
      mmBitmovinPlugin.reportViewSessionId("VIEW_SESSION_ID");
      mmBitmovinPlugin.initialize(player, streamURL, contentMetadata, isLive, playerEvent);

      player.load(source);
  </script>
</body>

Step 3: Errors and Warnings (Important):

The SDK provides two ways to report errors: automatic error capture and manual error reporting via API.

⚙️ Default Behavior (Auto Error Capture):

By default, the SDK automatically listens to and captures player errors that occur after the stream has started loading. SDK will classify the errors based on severity.

⚠️ Note: Errors that occur before stream loading are not captured automatically by the SDK, as they fall outside the player’s event lifecycle. Use the error and warning APIs below to manually report such issues.

🚫 Disabling Auto Error Capture:

If you prefer to handle error reporting manually, you can disable this automatic behavior by calling:

mmBitmovinPlugin.disableAutoErrorCapture();

⚠️ When disabled, the SDK will not listen for any player-generated errors. You will be responsible for reporting all errors & warnings manually using the APIs described below.

🛠️ Manual Error Reporting APIs:

Use these APIs to custom report errors and warnings to the SDK—especially for errors that occur before stream loading, or when auto-capture is disabled.

🔴 Report Fatal Error:

All errors reported via reportError are treated as fatal.

mmBitmovinPlugin.reportError("ERROR_CODE", "ERROR_MESSAGE", "ERROR_DETAILS");

🟠 Report Warning (Non-Fatal):

All warnings reported via reportWarning are treated as non-fatal and will be tracked accordingly.

mmBitmovinPlugin.reportWarning("WARNING_CODE", "WARNING_MESSAGE", "WARNING_DETAILS");

Step 4: Report Additional Metadata Fields:

Step 4.1: Experiment Name:

Reports a custom experiment label (e.g., for A/B testing or feature segmentation). This label helps categorize playback sessions under specific experiments for analytics and comparison.

mmBitmovinPlugin.reportExperimentName("EXPERIMENT_NAME");

Step 4.2: CDN:

Report the name or identifier of the Content Delivery Network (CDN) used for streaming. This helps track performance and quality across different CDNs.

mmBitmovinPlugin.reportCDN("CDN");

Step 4.3: Custom Metadata:

Use this method to report any additional metadata that doesn’t fall under predefined fields. This allows flexibility to send custom business-specific or platform-specific information to the SDK. This is the same as customTags in the contentMetadata object.

mmBitmovinPlugin.reportCustomMetadata("KEY", "VALUE");

Step 4.4: Stream Information:

Report key stream attributes that describe the encoding and delivery method.

mmBitmovinPlugin.reportStreamInfo("STREAM_FORMAT", "MEDIA_TYPE", "SOURCE_TYPE");

Step 4.5: Player resolution:

Report the width and height of the player window (in pixels). This is useful to understand playback size and user experience across different screen sizes or platforms.

mmBitmovinPlugin.reportPlayerResolution(<player_width>, <player_height>);

Step 4.6: Report Stream Fallback Event

Report fallback event in case the primary manifest URL fails and falls back on the secondary manifest.

mmBitmovinPlugin.reportFallbackEvent("FALLBACK_URL", "DESCRIPTION");

Step 5: Update Asset Information:

If Asset Information needs to be updated dynamically during the live session without re-initiating the player, then the updateAssetInfo API can be used to update the new AssetInfo

Note

This API must be called for updating asset info for the live streams only
This API must be called after the Player has started the playback of the live stream
New Asset Info Object will override the previous values. Hence, set all the fields that are required every time calling this API, including all Custom Tags.

// Create a new assetInfo object with the values need to be updated
var newAssetInfo =  { 
     "assetName": "ASSET_NAME",
     "assetId": "ASSET_ID",
     "videoId": "VIDEO_ID",
     "contentType": "CONTENT_TYPE",
     "drmProtection": "DRM_PROTECTION",
     "episodeNumber": "EPISODE_NUMBER",
     "season":"SEASON",
     "seriesTitle": "SERIES_TITLE",
     "customTags":{
         "key1": "VALUE1",
         "key2": "VALUE2"
     }          
}

// Update the new assetInfo
mmBitmovinPlugin.updateAssetInfo(newAssetInfo);

Step 6: Set Content Provider Details

Set the required content provider details via an URL. This URL should contain all the details like id's, token information and provider information. This step is required only to generate starz and toolbox events.

mmBitmovinAdapter.setContentProviderDetails(url);

PreviousShaka Player SDK Integration Document NextHLSJS SDK Integration Document

Last updated 3 days ago