# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/web/mediamelon-shaka-player-sdk-integration-document.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.