MediaMelon C++ Custom SDK Integration Document with Offline Storage Support

This guide is for integrating the MediaMelon Custom SDK for the STB-based Players with Offline Storage Support.

Step 6: Player Events

Step 7: Fallback & Request Status

Step 8: Ad Data & Ad Events

Step 9: Custom Events

Step 10: Offline Storage Support

Release Notes

Step 1: Add MediaMelon SDK

Add the provided static (.a) library to the project. (v3.4.0-OFS)

Step 2: Register and Initialize MediaMelon SDK

CUSTOMER_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID, contact MediaMelon at customer-support@mediamelon.com.

Step 2.1: Instantiate and Set SDK Registration Information:

#include "cpp_mmsmartstreaming.h"

using namespace MMSmartStreamingSDK;

MMSmartStreaming &mmSmartStreaming = MMSmartStreaming::getInstance();

MMSmartStreaming::registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_CPP", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", hashSubscriberID);
MMSmartStreaming::reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
MMSmartStreaming::reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");

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

Step 2.3: Report Application Information:

MMSmartStreaming::reportAppData("APP_NAME", "APP_VERSION");

Step 2.4: Report Application Session ID:

MMSmartStreaming::reportAppSessionID("APP_SESSION_ID");

Step 2.5: Set Device Information:

MMDeviceInformation deviceInfo;
deviceInfo.setDeviceType("DEVICE_TYPE");
deviceInfo.setDeviceBrand("DEVICE_BRAND");      //Device Brand or Manufacturer
deviceInfo.setDeviceModel("DEVICE_MODEL");
deviceInfo.setDeviceOSInfo("DEVICE_OS", "DEVICE_OS_VERSION");  
deviceInfo.setScreenResolution(<screen_width>, <screen_height>);
  
MMSmartStreaming::reportDeviceInfo(deviceInfo);

Step 2.6: Report Experiment Name & Sub Property ID:

MMSmartStreaming::reportExperimentName("EXPERIMENT_NAME");
MMSmartStreaming::reportSubPropertyID("SUB_PROPERTY_ID");

Step 2.7: Set Content Metadata:

MMContentMetadata contentMetadata;
contentMetadata.setAssetInfo("ASSET_ID", "ASSET_NAME", "VIDEO_ID");
contentMetadata.setContentType("CONTENT_TYPE");
contentMetadata.setDrmProtection("DRM_PROTECTION");
contentMetadata.setEpisodeNumber("EPISODE_NUMBER");
contentMetadata.setGenre("GENRE");
contentMetadata.setSeason("SEASON");
contentMetadata.setSeriesTitle("SERIES_TITLE");

mmSmartStreaming.reportViewSessionID("VIEW_SESSIOND_ID");

Step 2.8: Initialize Session with Content Metadata:

mmSmartStreaming.initializeSession("STREAM_URL", contentMetadata)
mmSmartStreaming.reportPreload(<bool>);
mmSmartStreaming.reportUserInitiatedPlayback();

Preload: Report the preload attribute after initializeSession and before reportUserInitiatedPlayback. The preload value is reset inside initializeSession, so reporting it before this method will be ignored. If you report it after reportUserInitiatedPlayback, the first event will not contain the preload field.

Step 3: Additional 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.

mmSmartStreaming.reportCustomMetadata("KEY1", "VALUE1");
mmSmartStreaming.reportCustomMetadata("KEY2", "VALUE2");

Step 4: Network and Stream Information

Step 4.1: Report Network Information:

mmSmartStreaming.reportNetworkInfo("CDN",
                                   <asn>,                 //Integer Value
                                   "SOURCE_HOST_NAME", 
                                   "NETWORK_TYPE",        // Network Connection Type
                                   "NETWORK_OPERATOR");

Use the reportNetworkInfo API to report the CDN along with other network information. If additional network information is not available, use reportCDN instead.

Step 4.2: Report CDN Information:

mmSmartStreaming.reportCDN("CDN");

Step 4.2: Report Stream Information:

mmSmartStreaming.reportStreamInfo("STREAM_FORMAT", "MEDIA_TYPE", "SORUCE_TYPE");

Step 4.3: Update Stream URL:

mmSmartStreaming.updateStreamURL("NEW_STREAM_URL");

Step 4.4: Report Video Presentation Information:

MMPresentationInfo presentationInfo;
presentationInfo.isLive = false;
presentationInfo.duration = 100*1000; 

mmSmartStreaming.setPresentationInformation(presentationInfo);

isLive: Set to true for live video stream and to false for the VOD stream.
duration: Video duration in milliseconds.

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

mmSmartStreaming.reportMediaTrackInfo(<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.6: 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.

MMRenditionInfo renditionInfo;
renditionInfo.bitrate = <bitrate>            //Integr Value in bps
renditionInfo.width = <width>                //Integer Value
renditionInfo.height = <height>              //Integer Value
renditionInfo.frameRate = <frame_rate>       //Double Value in fps
renditionInfo.setAudioCodec("ACODEC");
renditionInfo.setVideoCodec("VCODEC");

mmSmartStreaming.reportRenditionInformation(renditionInfo);

Step 4.7: Update DRM Type:

mmSmartStreaming.updateDRMType("NEW_DRM_TYPE");

Step 4.8: Report Encoding Service:

mmSmartStreaming.reportEncodingService("ENCODING_SERVICE");

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.

mmSmartStreaming.reportDownloadRate(<downloadRate>)  //Integer Value in bps

Step 6: Player Events

Step 6.1: Report Player State:

mmSmartStreaming.reportPlayerState(MMPlayerState::PLAYING);

Enum: MMPlayerState
- PLAYING
- PAUSED
- STOPPED

Step 6.2: Report Buffering:

mmSmartStreaming.reportBufferingStarted();
mmSmartStreaming.reportBufferingCompleted();

Step 6.3: Report Seek:

mmSmartStreaming.reportPlayerSeekStarted();
mmSmartStreaming.reportPlayerSeekCompleted(<seek_end_position>); //Integer Value in Milli Seconds

Step 6.4: Report Error:

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

Step 6.5: Report Warning:

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

Step 6.5: Report Playback Position:

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

mmSmartStreaming.reportPlaybackPosition(<playback_position>) //Integer Value in Milli Seconds

Step 6.6: Report Player Resolution:

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

Step 7: Fallback & Request Status

Step 7.1: Report Fallback Event:

mmSmartStreaming.reportFallbackEvent("NEW_FALLBACK_STREAM_URL", "FALLBACK_DESCRIPTION");

Step 7.2: Report Request Status:

Report FAILED or CANCELLED requests for the following request types:

PIR
MANIFEST
AUDIO_CHUNK
VIDEO_CHUNK
DRM
SUBTITLE

map<string, string> requestInfoMap;
requestInfoMap["ID"] = "ID";
requestInfoMap["URL"] = "URL";
requestInfoMap["ERROR"] = "ERROR";
requestInfoMap["DESC"] = "DESC";

mmSmartStreaming.reportRequestStatus(RequestStatus::CANCELLED, "REQUEST_TYPE", requestInfoMap);

Enum: RequestStatus
- FAILED
- CANCELLED

Step 8: Ad Data & Ad Events

Step 8.1: Report Ad Break Start & End:

mmSmartStreaming.reportAdBreakStart();
mmSmartStreaming.reportAdBreakEnd();

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

MMAdInfo adInfo;
adInfo.adTitle = "AD_TITLE";
adInfo.adId = "AD_ID";
adInfo.adCreativeId = "AD_CREATIVE_ID";
adInfo.adCreativeType = "AD_CREATIVE_TYPE";
adInfo.adClient = "AD_CLIENT"
adInfo.adPosition = "AD_POSITION";                    //pre, mid, post
adInfo.adServer = "AD_SERVER";
adInfo.adResolution = "AD_RESOLUTION";
adInfo.adUrl = "AD_URL";
adInfo.adDuration = <ad_duration>;                    //Integer Value in Milli Seconds
adInfo.adPodIndex = <pod_index>;                      //Integer Value
adInfo.adPositionInPod = <ad_position_in_pod>;        //Integer Value
adInfo.adPodLendth = <pod_length>;                    //Integer Value
adInfo.isBumper = <is_bumper>;                        //Boolean Value

mmSmartStreaming.reportAdInfo(mmadInfo);

mmSmartStreaming.reportAdStart();
mmSmartStreaming.reportAdEnd();

Ad Info Fields & Description

adInfo.adTitle

String

The title or name of the ad, usually provided in the VAST metadata or by the ad server.

adInfo.adId

String

A unique identifier for the ad creative, often defined by the ad server or DSP.

adInfo.adCreativeId

String

The creative ID associated with the specific ad asset (video, image, etc.). Helps in tracking and reporting creative-level performance.

adInfo.adCreativeType

String

The format or type of the ad creative. For example, video/mp4, image/jpeg, etc., or linear, non-linear.

adInfo.adClient

String

The SDK or client library responsible for requesting and playing the ad. Example: Google IMA, Freewheel, SpotX.

adInfo.adPosition

String

The timing of the ad in relation to the main content: "pre" (before), "mid" (during), or "post" (after).

adInfo.adServer

String

The ad server or source that delivered the ad. Example: Google Ad Manager, Freewheel, etc.

adInfo.adResolution

String

The resolution of the ad video (e.g., 1920x1080), useful for reporting and quality monitoring.

adInfo.adUrl

String

The URL from which the ad video is fetched. Typically a media file or stream URL.

adInfo.adDuration

Integer

The total duration of the ad, in milliseconds. Example: 30000 = 30 seconds.

adInfo.adPodIndex

Integer

The index of the ad pod within the stream. Ad pods are groups of ads played together (like a commercial break).

adInfo.adPositionInPod

Integer

The position of the ad within its pod (e.g., 1st ad, 2nd ad in the group).

adInfo.adPodLendth

Integer

The total number of ads in the current pod. Useful for showing “Ad 2 of 5” type of UI.

adInfo.isBumper

Boolean

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

Step 8.3: Report Ad Buffering:

Use Ad Buffering APIs to report any buffering that occurs during ad playback. For any buffering event, either content buffering or ad buffering should be reported, but not both.

mmSmartStreaming.reportAdBufferingStrated();
mmSmartStreaming.reportAdBufferingCompleted();

Step 9: Custom Events

The Custom Events API can be used to report events that are not covered by the default MediaMelon-supported events. Custom events must be reported within the SDK activity lifecycle. Events reported before SDK initialization or after session end will be ignored. Please refer to the guidelines and constraints below.

mmSmartStreaming.reportCustomEvent("EVENT_NAME", "EVENT_VALUE");

Guidelines & Constraints

Event Name
- Maximum length: 35 characters
- Allowed characters: Alphanumeric and underscore (_) only
- Special characters are not supported
- Recommended format: UPPERCASE with underscores (e.g., DRM_CHANGE)
Event Limits
- A maximum of 35 custom events per session is allowed.

Custom events that violate these constraints (invalid event name or exceeding the per-session limit) will be dropped. Event values exceeding 1000 characters will be truncated to 1000 characters.

Step 10: Offline Storage Support

The SDK can persist analytics payloads to local storage when they cannot be delivered to the backend. Payloads are stored when network calls are disabled, when SDK registration fails (e.g., no internet), or when a payload fails to send. Stored payloads are appended as one JSON object per line to:

<OFFLINE_STORAGE_PATH>/mediamelon-offline-data.txt

Step 10.1: Set Offline Storage Path:

Folder where the offline data file is created. The SDK creates the folder if it does not exist.

MMSmartStreaming::setOfflineStoragePath("OFFLINE_STORAGE_PATH");

Step 10.2: Set Offline Storage Maximum Size:

Maximum size of the offline data file. Default is 50 MB. Once the limit is reached, new payloads are dropped. MMSmartStreaming::setOfflineStorageMaxSizeBytes(<max_size_bytes>); //50 MB Default

Step 10.3: Enable/Disable Network Calls:

Set it to true (default) to send payloads over the network, and to false to disable all SDK network activity and write payloads to the offline file instead. MMSmartStreaming::setNetworkCallsEnabled(<network_calls_enabled>);

Release Notes

Current Release

v3.4.0-OFS ^{_{Jul 08, 2026}}

Added offline storage support - analytics payloads that cannot be delivered are now persisted to a local file.
Introduced setNetworkCallsEnabled to disable all SDK network activity and route payloads directly to offline storage.
Sessions now continue when SDK registration fails - payloads are captured to offline storage.

Previous Releases

Last updated 1 day ago