Custom SDK Integration Document

This guide is for integrating the MediaMelon Custom SDK for the JavaScript-based Web Players

Step 1: Add MediaMelon Player SDK

Step 2: Register and Initialize MediaMelon Player SDK

Step 3: Custom Metadata

Step 4: Stream and Network Information

Step 5: Chunk/Segment Information

Step 6: Player Events

Step 7: Fallback & Request Status

Step 8: Ad Data & Ad Events

Step 1: Add MediaMelon Player SDK

• CDN:

<script type="text/javascript" src="https://sdk.mediamelon.com/SDK_RELEASES/Javascript/customsdk/1.3.11/mmsmartstreamingsdk.min.js"></script>

• NPM (1.3.11):

npm i mediamelon-js-custom-sdk

import { mmJSCustomAdapter, MMPlayerState, RenditionInfo, RequestStatus} from 'mediamelon-js-custom-sdk'

Step 2: Register and Initialize MediaMelon Player SDK

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

Step 2.1: Instantiate and Register SDK:

var mmJSPlugin = new mmJSCustomAdapter();
mmJSPlugin.registerMMSmartStreaming("PLAYER_NAME", 
    "CUSTOMER_ID", 
    "SUBSCRIBER_ID", 
    "DOMAIN_NAME", 
    "SUBSCRIBER_TYPE", 
    "SUBSCRIBER_TAG", 
    hash_subscriber_id      //Boolean Value
);

hash_subscriber_id: Set it to true to hash the subscriber ID, and to false to process the subscriber ID without hashing.

Step 2.2: Report Player Information:

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

Step 2.3: Report Application Information:

mmJSPlugin.reportAppInfo("APPLICATION_NAME","APPLICATION_VERSION");

Step 2.4: Report Device Information:

var deviceInfo = {
    "deviceName": "DEVICE_NAME",
    "deviceBrand": "DEVICE_BRAND",
    "deviceModel": "DEVICE_MODEL",
    "deviceId": "DEVICE_ID",
    "deviceOS": "DEVICE_OS",
    "deviceOSVersion": "DEVICE_OS_VERSION",            
    "screenWidth": screen_width,        //Integer Value
    "screenHeight": screen_height       //Integer Value
};
mmJSPlugin.reportDeviceInfo(deviceInfo);

Step 2.5: Report Experiment Name & Sub Property ID:

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

Step 2.6: Initialize Session with Content Metadata:

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",
    "videoType": "VIDEO_TYPE"
};

mmJSPlugin.initializeSession(contentMetaData, "STREAM_URL");
mmJSPlugin.reportUserInitiatedPlayback();

Step 2.7: Report View Session ID:

mmJSPlugin.reportViewSessionId("VIEW_SESSION_ID");

Step 3: Custom Metadata

Check the custom tags configuration in your dashboard and report accordingly. If the custom tags are not configured, please configure and use them accordingly.

mmJSPlugin.reportCustomMetadata("custom_1", "value1");
mmJSPlugin.reportCustomMetadata("custom_2", "value2");

Step 4: Stream and Network Information

Step 4.1: Report Stream Information:

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

Step 4.2: Update Stream URL:

mmJSPlugin.updateStreamURL("STREAM_URL");

Step 4.3: Report Presentation Info:

mmJSPlugin.reportPresentationInfo(<is_live>, <video_duration>);

• is_live: Set to true for live video stream and to false for the VOD stream.

• video_duration: Integer value in milliseconds.

Step 4.4: Report Track Information

Call this API with initial values and every time there is a change in the track info. Call this API when the user enables/disables subtitles or when the user changes the audio track.

mmJSPlugin.reportTrackinfo(<is_subtitle_active>, "SUBTITLE_TRACK", "AUDIO_TRACK", <is_vds_active>);

is_subtitle_active: Set it to true if the subtitles are active; otherwise, set it to false.

is_vds_active: Set it to true if the type of audio is Virtual Dialogue Sound, otherwise, set it to false.

Step 4.5: Report Rendition:

At the start of the video, create a ReditionInfo object, assign initial rendition values to the object, and report it to the SDK. For any subsequent rendition change, update only the fields that changed in the same RenditionInfo object. Leave the unchanged fields as-is, and report the updated object to the SDK.

var renditionInfo = new RenditionInfo();
rendition.bitrate = <birate>;            //Integr Value in bps
rendition.width = <width>;               //Integr Value
rendition.height = <height>;             //Integer Value
rendition.frameRate = <frame_rate>;      //Integr Value in fps
rendition.aCodec = "AUDIO_CODEC";
rendition.vCodec = "VIDEO_CODEC";

mmJSPlugin.reportRendition(renditionInfo);

Step 4.6: Update DRM Type:

mmJSPlugin.updateDRMType("NEW_DRM_TYPE");

Step 4.7: Report Network Information:

var networkInfo = {
    "cdn": "CDN",
    "asn": asn,                 //Integer Value
    "hostName": "SOURCE_HOST_NAME",
    "networkType": "NETWORK_TYPE",
    "networkOperator": "NETWORK_OPERATOR"
}
mmJSPlugin.reportNetworkInfo(networkInfo);

Step 5: Chunk/Segment Information

Step 5.1: Report Download Rate:

Report the latest chunk download rate using this method. Trigger this method for every chunk.

mmJSPlugin.reportDownloadRate(downloadRate);    //Integer Value in bps (bits per second

Step 6: Player Events

Step 6.1: Report Player State

mmJSPlugin.reportPlayerState(MMPlayerState.PLAYING);

Enum: MMPlayerState
- PLAYING
- PAUSED
- STOPPED

Step 6.2: Report Buffering

mmJSPlugin.reportBufferingStarted();
mmJSPlugin.reportBufferingCompleted();

Step 6.3: Report Seek

mmJSPlugin.reportPlayerSeekStarted(); 
mmJSPlugin.reportPlayerSeekCompleted(seekEndPositionInMS); //Integer Value in Milli Seconds

Step 6.4: Report Error

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

Step 6.5: Report Warning

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

Step 6.6: Report Playback Position

Call this every 0.5 sec or 1 sec to report the playback position from the player

mmJSPlugin.reportPlaybackPosition(playback_position); //Integer Value in Milli Seconds

Step 6.7: Report Player Resolution

mmJSPlugin.reportPlayerResolution(width, height);

Step 7: Fallback & Request Status

Step 7.1: Report Fallback Event

mmJSPlugin.reportFallbackEvent("FALLBACK_MANIFEST_URL", "DESCRIPTION");

Step 7.2: Report Request Status

var requestInfo = {
    id: "ID",
    error: "ERROR",
    text: "TEXT",
    hostname: "HOSTNAME",
    url: "URL",
    ...
}

mmJSPlugin.reportRequestStatus(RequestStatus.FAILED, "REQUEST_TYPE", requestInfo);

Enum: RequestStatus
- FAILED
- CANCELLED

Step 8: Ad Data & Ad Events

Step 8.1: Report Ad Break Start & End:

mmJSPlugin.reportAdBreakStart();
mmJSPlugin.reportAdBreakEnd();

Step 8.2: Report Ad Data, Ad Start & End:

var adInfo = {
    "adTitle": "AD_TITLE",
    "adId": "AD_ID",
    "adCreativeId": "AD_CREATIVE_ID",
    "adCreativeType": "AD_CREATIVE_TYPE",
    "adClient": "AD_CLIENT",
    "adPosition": "AD_POSITION",               //pre, mid, post
    "adServer": "AD_SERVER",
    "adResolution": "AD_RESOLUTION",
    "adUrl": "AD_URL",
    "adDuration": ad_duration,              //Double Value
    "adPodIndex": pod_index,                //Integer Value
    "adPositionInPod": ad_position_in_pod,  //Integer Value
    "isBumper": is_bumper                   //Boolean Value
}

mmJSPlugin.reportAdStart(adInfo);
mmJSPlugin.reportAdEnd();

adInfo.adTitle	The title or name of the ad, usually provided in the VAST metadata or by the ad server.
adInfo.adId	A unique identifier for the ad creative, often defined by the ad server or DSP.
adInfo.adCreativeId	The creative ID associated with the specific ad asset (video, image, etc.). Helps in tracking and reporting creative-level performance.
adInfo.adCreativeType	The format or type of the ad creative. For example, video/mp4, image/jpeg, etc., or linear, non-linear.
adInfo.adClient	The SDK or client library responsible for requesting and playing the ad. Example: Google IMA, Freewheel, SpotX.
adInfo.adPosition	The timing of the ad in relation to the main content: "pre" (before), "mid" (during), or "post" (after).
adInfo.adServer	The ad server or source that delivered the ad. Example: Google Ad Manager, Freewheel, etc.
adInfo.adResolution	The resolution of the ad video (e.g., 1920x1080), useful for reporting and quality monitoring.
adInfo.adUrl	The URL from which the ad video is fetched. Typically a media file or stream URL.
adInfo.adDuration	The total duration of the ad, in milliseconds. Example: 30000 = 30 seconds.
adInfo.adPodIndex	The index of the ad pod within the stream. Ad pods are groups of ads played together (like a commercial break).
adInfo.adPositionInPod	The position of the ad within its pod (e.g., 1st ad, 2nd ad in the group).
adInfo.adPodLendth	The total number of ads in the current pod. Useful for showing “Ad 2 of 5” type of UI.
adInfo.isBumper	A boolean (true/false) indicating whether the ad is a bumper ad (short ad, usually <6s, played at the start or end of ad breaks).