# MediaMelon VideoJS 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 (Important)](#step-3-errors-and-warnings-important)

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

[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/videojs/1.3.0/mmsmartstreaming_videojsplayer.min.js"></script>
```

**NPM:**

```bash
npm i mediamelon-js-videojs-sdk@1.3.0

import {VideoJSMMSSIntgr} from 'mediamelon-js-videojs-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 mmVideoJSPlugin = new VideoJSMMSSIntgr();
mmVideoJSPlugin.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
mmVideoJSPlugin.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");            
mmVideoJSPlugin.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
```

#### Step 2.3: Report Application Information:

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

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

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

#### Step 2.5: Report Device Information:

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

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

```javascript
<video id="video-js" class="vjs-default-skin" preload="auto"></video>
..
var player = videojs('video-js');

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

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

player.src({
      src: "STREAM_URL"
});
player.play();
```

{% 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
mmVideoJSPlugin.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
mmVideoJSPlugin.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
mmVideoJSPlugin.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
mmVideoJSPlugin.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
mmVideoJSPlugin.reportCustomMetadata("KEY", "VALUE");
```

#### Step 4.3: Stream Information:

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

```javascript
mmVideoJSPlugin.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
mmVideoJSPlugin.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
mmVideoJSPlugin.reportFallbackEvent("FALLBACK_URL", "DESCRIPTION");
```

### Release Notes

<details>

<summary>Current Release</summary>

#### v1.3.0[^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.

</details>

***

<details>

<summary>Previous Releases</summary>

</details>

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