# MediaMelon Shaka Player SDK Integration Document

**Step 1:** [Add the MediaMelonPlayer SDK](#step-1-add-mediamelon-smartstreaming-sdk-hardbreak)

**Step 2:** [Register and Initialize the MediaMelon Player SDK](#step-2-register-and-initialize-mediamelon-sdk)

**Step 3:** [Errors and Warnings](#step-3-errors-and-warnings-important)

**Step 4:** [Report Additional Metadata Fields](#step-4-report-additional-metadata-fields)

**Step 5:** [Update Asset Information](#step-5-update-asset-information)

[Release Notes](#release-notes)

### **Step 1: Add** the MediaMelonPlayer SDK <a href="#step-1-add-mediamelon-smartstreaming-sdk-hardbreak" id="step-1-add-mediamelon-smartstreaming-sdk-hardbreak"></a>

**CDN URL:**

```javascript
<script type="text/javascript" src="https://sdks.mediamelon.com/web/shaka/2.5.1/mmsmartstreaming_shakaplayer.min.js"></script>
```

**NPM:**

```bash
npm i mediamelon-js-shaka-sdk@2.5.1

import {SHAKAPlayerMMSSIntgr} from 'mediamelon-js-shaka-sdk'
```

### **Step 2: Register and Initialize** the MediaMelon Player SDK <a href="#step-2-register-and-initialize-mediamelon-sdk" id="step-2-register-and-initialize-mediamelon-sdk"></a>

#### Step 2.1: Instantiate and Register SDK:

```javascript
var mmShakaPlugin = new SHAKAPlayerMMSSIntgr();
mmShakaPlugin.registerMMSmartStreaming("PLAYER_NAME", 
    "CUSTOMER_ID", 
    "SUBSCRIBER_ID", 
    "DOMAIN_NAME", 
    "SUBSCRIBER_TYPE", 
    "SUBSCRIBER_TAG", 
    hashSubscriberId      //Boolean
);
```

{% hint style="info" %}
`CUSTOMER_ID` is your MediaMelon-assigned Customer ID. If you do not know your Customer ID, contact MediaMelon at [support@mediamelon.com](https://emailto:support@mediamelon.com/).&#x20;
{% endhint %}

#### Step 2.2: Report Player Information:

```javascript
mmShakaPlugin.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");            
mmShakaPlugin.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
```

#### Step 2.3: Report Application Information:

```javascript
mmShakaPlugin.reportAppInfo("APPLICATION_NAME","APPLICATION_VERSION");
mmShakaPlugin.reportAppSessionId("APP_SESSION_ID");
```

#### Step 2.4: Report Experiment Name & Sub Property ID:

```javascript
mmShakaPlugin.reportExperimentName("EXPERIMENT_NAME");
mmShakaPlugin.reportSubPropertyId("SUB_PROPERTY_ID");
```

#### Step 2.5: Report Device Information:

```javascript
mmShakaPlugin.setDeviceInfo("DEVICE_MARKETING_NAME");
mmShakaPlugin.reportDeviceId("DEVICE_ID");
```

#### Step 2.6: Initialize Session with Content Metadata:

```javascript
const video = document.getElementById('video');
const player = new shaka.Player(video);

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

mmShakaPlugin.reportViewSessionId("VIEW_SESSION_ID");
mmShakaPlugin.initializeSession(player, video, "STREAM_URL", contentMetadata, isLive);

player.load("STREAM_URL");
```

{% hint style="info" %}
For Custom Metadata, first map the values in the [SmartSight](https://smartsight.mediamelon.com/) dashboard under Settings, then send them to the SDK accordingly. Refer to [Custom Metadata Configuration Guide](https://docs.mediamelon.com/mediamelon-sdk-integration/custom-metadata-configuration-guide).
{% endhint %}

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

{% hint style="info" %}

> ⚠️ 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.
> {% endhint %}

🚫 **Disabling Auto Error Capture:**

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

```javascript
mmShakaPlugin.disableAutoErrorCapture();
```

{% hint style="info" %}

> ⚠️ 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.
> {% endhint %}

**🛠️ 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**.

```javascript
mmShakaPlugin.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.

```javascript
mmShakaPlugin.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.

```javascript
mmShakaPlugin.reportCDN("CDN");
```

#### Step 4.2: Custom Metadata:

Check the custom metadata configuration in the [SmartSight](https://smartsight3.mediamelon.com/settings) and report accordingly. If the custom tags are not configured, please configure them and use them as needed.&#x20;

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.

```javascript
mmShakaPlugin.reportCustomMetadata("KEY", "VALUE");
```

#### Step 4.3: Stream Information:

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

```javascript
mmShakaPlugin.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.

```javascript
mmShakaPlugin.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.

```java
mmShakaPlugin.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

{% hint style="info" %}
**Note**

* This API must be called for updating asset info for the live streams only&#x20;
* This API must be called after the Player has started the playback of the live stream&#x20;
* 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.**
  {% endhint %}

```javascript
// 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
mmShakaPlugin.updateAssetInfo(newAssetInfo);
```

### Release Notes

<details>

<summary>Current Release</summary>

#### v2.5.[^1]1

* Added App Session ID metadata field.
* Fixed the buffering and seek complete events order issue.
* Added Seek duration.
* Updated the rendition reporting to enable rendition metrics in the dashboard.
* Improved bitrate reporting.
* Added `CDN_CHANGE` event.

</details>

***

<details>

<summary>Previous Releases</summary>

#### v2.4.0[^2]

* Added Shaka 2.x support

#### v2.3.2[^3]

* Fixed buffering and seek-related issues.
* Fixed heartbeat missing in case of registration response delayed.

</details>

[^1]: **Release Date:** Mar 9, 2026

[^2]: **Release Date:** Sep 12, 2025

[^3]: **Release Date:** Sep 3, 2025