MediaMelon Theo Player SDK Integration Document

This guide is for integrating the MediaMelon Player SDK for the javascript based Theo Player

Step 1: Add the MediaMelonPlayer SDK

Step 2: Register and Initialize the MediaMelon Player SDK

Step 3: Errors and Warnings (Important)

Step 4: Report Additional Metadata Fields

Release Notes

Step 1: Add the MediaMelonPlayer SDK

CDN URL:

<script type="text/javascript" src="https://sdks.mediamelon.com/web/theo/1.4.1/mmsmartstreaming_theoplayer.min.js"></script>

NPM:

npm i [email protected]

import {mmTheoJSAdapter} from 'mediamelon-js-theo-sdk'

Step 2: Register and Initialize the MediaMelon Player SDK

Step 2.1: Instantiate and Register SDK:

var mmTheoPlugin = new mmTheoJSAdapter();
mmTheoPlugin.registerMMSmartStreaming("PLAYER_NAME", 
    "CUSTOMER_ID", 
    "SUBSCRIBER_ID", 
    "DOMAIN_NAME", 
    "SUBSCRIBER_TYPE", 
    "SUBSCRIBER_TAG", 
    hashSubscriberId      //Boolean
);

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

Step 2.2: Report Player Information:

mmTheoPlugin.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");            
mmTheoPlugin.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");

Step 2.3: Report Application Information:

mmTheoPlugin.reportAppInfo("APPLICATION_NAME","APPLICATION_VERSION");
mmTheoPlugin.reportAppSessionId("APP_SESSION_ID");

Step 2.4: Report Experiment Name & Sub Property ID:

mmTheoPlugin.reportExperimentName("EXPERIMENT_NAME");
mmTheoPlugin.reportSubPropertyId("SUB_PROPERTY_ID");

Step 2.5: Report Device Information:

mmTheoPlugin.setDeviceInfo("DEVICE_MARKETING_NAME");
mmTheoPlugin.reportDeviceId("DEVICE_ID");

Step 2.6: Initialize Session with Content Metadata:

var player = new THEOplayer.Player(element, {
     libraryLocation: 'THEO_LIBRARY_LOCATION',
     license: 'LICENSE'
})

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"
    }
};

mmTheoPlugin.reportViewSessionId("VIEW_SESSION_ID");
mmTheoPlugin.initialize(player, "STREAM_URL", contentMetadata, isLive);

For Custom Metadata, first map the values in the SmartSight dashboard under Settings, then send them to the SDK accordingly. Refer to Custom Metadata Configuration Guide.

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 loaded. SDK will classify the errors based on severity.

⚠️ Note: Errors that occur before or during 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:

mmTheoPlugin.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 or during stream loading, or when auto-capture is disabled.

🔴 Report Fatal Error:

All errors reported via reportError are treated as fatal.

mmTheoPlugin.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.

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

Step 4: Report Additional Metadata Fields

Step 4.1: CDN:

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

mmTheoPlugin.reportCDN("CDN");

Step 4.2: Custom Metadata:

Check the custom metadata configuration in the SmartSight and report accordingly. If the custom tags are not configured, please configure them and use them as needed.

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

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

Step 4.3: Stream Information:

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

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

Step 4.4: 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.

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

Step 4.5: Report Stream Fallback Event

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

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

Release Notes

Current Release

v1.4.1

• Added App Session ID metadata field.

• Added Seek duration.

• Updated the rendition reporting to enable rendition metrics in the dashboard.

• Improved bitrate reporting.

• Added CDN_CHANGE event.

• Added ad buffering tracking for IMA and DAI ads.

---

Previous Releases

v1.3.1

• Fixed an initialisation crash issue.