MediaMelon iOS Custom Multi-Player SDK Integration Document

This guide is for integrating the MediaMelon Custom Multi-Player SDK for the iOS, tvOS & visionOS - based Players

Step 1: Add MediaMelon SDK

SPM:

.package(
      url: "https://github.com/MediamelonSDK/mm-ios-qoe-sdk",
      .upToNextMajor(from: "3.3.1")
 ),

Step 2: Instantiate and Register SDK

Step 2.1: SDK Instance Creation:

let mmCustomAdapter = MMCustomAdapter()

Step 2.2: Report Registration Information:

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

let registrationInfo = MMRegistrationInformation(customerID: "CUSTOMER_ID", playerName: "PLAYER_NAME")
registrationInfo.setDomain("DOMAIN_NAME")
registrationInfo.setSubscriberInformation(subscriberID: "SUBSCRIBER", subscriberType: "SUBSCRIBER_TYPE", subscriberTag: "SUBSCRIBER_TAG", hashSubscriberID: false)
registrationInfo.setPlayerId(playerId: "PLAYER_ID")
registrationInfo.setPlayerInformation(brand: "PLAYER_BRAND", model: "PLAYER_MODEL", version: "PLAYER_VERSION")
registrationInfo.setBasePlayerInformation(basePlayerName: "BASE_PLAYER_NAME", basePlayerVersion: "BASE_PLAYER_VERSION")

mmCustomAdapter.reportRegistrationInformation(registrationInfo)

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

Step 2.3: Report Device Information:

let deviceInfo = MMDeviceInformation()
deviceInfo.setDeviceTpe(type: "DEVICE_TYPE")
deviceInfo.setBrandName(brandName: "BRAND_NAME")    // Device Brand or Manufacturer
deviceInfo.setDeviceModel(deviceModel: "DEVICE_MODEL")
deviceInfo.setOSName(osName: "OS_NAME")
deviceInfo.setOSVersion(osVersion: "OS_VERSION")
deviceInfo.setTelecomOperator(telecomOperator: "TELECOM_OPERATOR")
deviceInfo.setScreenResolution(width: <screen_width>, height: <screen_height>)  //Integer Value
deviceInfo.setDeviceCapabilities(deviceCapabilities: "DEVICE_CAPABILITIES")

mmCustomAdapter.reportDeviceInformation(deviceInfo)

Step 2.4: Report Application Information:

mmCustomAdapter.reportAppData(appName: "APP_NAME", appVersion: "APP_VERSION")
mmCustomAdapter.reportAppSessionID(appSessionId: "APP_SESSION_ID")

Step 2.5: Report Sub Property ID:

mmCustomAdapter.reportSubPropertyID(subPropertyId: "SUBPROPERTY_ID")

Step 3: Initialize Playback Session

initializeAssetForPlayer( assetInfo:, registrationInfo:, deviceInfo:) is deprecated. Use separate APIs to report registrationInfo and deviceInfo as given in Step 2.2 and Step 2.3.

Step 3.1: Initialize Session with Content Metadata:

let assetInfo = MMAssetInformation(assetURL: "STREAM_URL", assetID: "ASSET_ID", assetName: "ASSET_NAME", videoId: "VIDEO_ID")
assetInfo.setEpisodeNumber("EPISODE_NUMBER")
assetInfo.setContentType("CONTENT_TYPE")
assetInfo.setSeriesTitle("SERIES_TITLE")
assetInfo.setGenre("GENRE")
assetInfo.setSeason("SEASON")
assetInfo.setDrmProtection("DRM_PROTECTION")
assetInfo.setDrmLevel("DRM_LEVEL")
assetInfo.addCustomKVP("CUSTOM_1", "VALUE_1")
assetInfo.addCustomKVP("CUSTOM_2", "VALUE_2")

mmCustomAdapter.initializeAssetForPlayer(assetInfo: assetInfo)

All metadata fields set from Step 3 will be reset when initializeAssetForPlayer is called. Therefore, ensure that all session-specific metadata, such as view session ID, preload, and similar fields, are reported after initializeAssetForPlayer is called for every playback session.

Step 3.2: Report View Session ID:

mmCustomAdapter.reportViewSessionID(viewSessionId: "VIEW_SESSION_ID")

Step 3.3: Report Experiment Name:

mmCustomAdapter.reportExperimentName(experimentName: "EXPERIMENT_NAME")

Step 3.4: Report Preload:

mmCustomAdapter.reportPreload(<boolean>)

Step 3.5: Report Player Resolution:

mmCustomAdapter.reportPlayerResolution(width: <width>, height: <height>)

Step 3.6: Report User-Initiated Playback:

This function indicates the intent for playback and must be invoked after initializeAssetForPlayer. Any metadata fields reported before this API call will be included in the first payload sent to the dashboard. To avoid Null values in metadata fields, it is recommended to report all available metadata before calling this API.

mmCustomAdapter.reportUserInitiatedPlayback()

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

mmCustomAdapter.reportCustomMetadata(key: "CUSTOM_3", value: "VALUE_3")

Step 5: Network and Stream Information

Step 5.1: Report Network Information:

mmCustomAdapter.reportNetworkInfo(cdn: "CDN", 
                                  asn: <asn>,                     // Integer Value
                                  hostName: "SOURCE_HOST_NAME", 
                                  networkType: "NETWORK_TYPE",    // Network Connection Type
                                  networkOperator: "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 5.2: Report CDN Information:

mmCustomAdapter.reportCDN(cdn: "CDN")

Step 5.3: Report Stream Information:

mmCustomAdapter.reportStreamInfo(streamURL: "STREAM_URL", 
                                 streamFormat: "STREAM_FORMAT", 
                                 mediaType: "MEDIA_TYPE", 
                                 sourceType: "SOURCE_TYPE")

Step 5.4: Report Encoding Service:

mmCustomAdapter.reportEncodingService(encodingService: "ENCODING_SERVICE");

Step 5.5: Report Video Presentation Information:

mmCustomAdapter.reportPresentationInfo(isLive: <is_live>, videoDurationInMS: <video_duration>)

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

Step 5.6: 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 or disables subtitles or changes the audio track.

mmCustomAdapter.reportMediaTrackInfo(isSubtitleActive: <is_subtitle_active>, subtitleTrack: "SUBTITLE_TRACK", audioTrack: "AUDIO_TRACK", isVDSActive: <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 5.7: 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 = MMRenditionInformation()

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.aCodec = "AUDIO_CODEC"
renditionInfo.vCodec = "VIDEO_CODEC"

mmCustomAdapter.reportRendition(renditionInfo: renditionInfo)

Step 5.8: Update DRM:

updateDrmType(drmType:) is deprecated. A new API called updateDRM(drmProtection:, drmLevel:) is introduced.

mmCustomAdapter.updateDRM(drmProtection: "DRM_PROTECTION", drmLevel: "DRM_LEVEL");

Step 6: Chunk/Segment Information

Step 6.1: Report Download Rate:

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

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

Step 7: Player Events

Step 7.1: Report Player State:

mmCustomAdapter.reportPlayerState(playerState: .PLAYING)

Enum: MMPlayerState
- PLAYING
- PAUSED
- STOPPED

Step 7.2: Report Buffering:

mmCustomAdapter.reportBufferingStarted()
mmCustomAdapter.reportBufferingCompleted()

Step 7.3: Report Seek:

mmCustomAdapter.reportPlayerSeekStarted() 
mmCustomAdapter.reportPlayerSeekCompleted(seekEndPositionInMS: <seek_end_position>) //Integer Value in Milli Seconds

Step 7.4: Report Error:

mmCustomAdapter.reportError(errorCode: "ERROR_CODE",
                            errorMessage: "ERROR_MESSAGE",
                            errorDetails: "ERROR_DETAILS")

Step 7.5: Report Warning:

mmCustomAdapter.reportWarning(warningCode: "WARNING_CODE",
                              warningMessage: "WARNING_MESSAGE",
                              warningDetails: "WARNING_DETAILS")

Step 7.6: Report Playback Position:

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

mmCustomAdapter.reportPlaybackPosition(currentPlayerPosInMS: <playback_position>) //Integer Value in Milli Seconds

Step 8: Fallback & Request Status

Step 8.1: Report Fallback Event:

mmCustomAdapter.reportFallbackEvent(fallbackManifestURL: "NEW_STREAM_URL", description: "DESCRIPTION")

Step 8.2: Report Request Status:

Report FAILED or CANCELLED requests for the following request types:

PIR
MANIFEST
AUDIO_CHUNK
VIDEO_CHUNK
DRM
SUBTITLE

var requestInfo : [String: Any] = [
    "id": "ID",
    "url": "URL",
    "error": "ERROR",
    "text": "TEXT",
    "hostname": "HOSTNAME",
    "url": "URL",
    ...
]

mmCustomAdapter.reportRequestStatus(status: .CANCELLED, type: "REQUEST_TYPE", requestInfo: requestInfo)

Enum: RequestStatus
- FAILED
- CANCELLED

Step 9: Ad Data & Ad Events

Step 9.1: Report Ad Break Start & End:

mmCustomAdapter.reportAdBreakStart()
mmCustomAdapter.reportAdBreakEnd()

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

let adInfo = MMAdInformation()

adInfo.setAdTitle("AD_TITLE")
adInfo.setAdId("AD_ID")
adInfo.setAdUniversalId("AD_UNIVERSAL_ID")
adInfo.setAdCreativeId("AD_CREATIVE_ID")
adInfo.setAdCreativeType("AD_CREATIVE_TYPE")
adInfo.setAdClient("AD_CLIENT")
adInfo.setAdPosition("AD_POSITION")
adInfo.setAdServer("AD_SERVER")
adInfo.setAdResolution("AD_RESOLUTION")
adInfo.setAdUrl("AD_URL")
adInfo.setAdDuration(<ad_duration>)                    //Integer Value in Milli Seconds
adInfo.setAdPodIndex(<pod_index>)                      //Integer Value
adInfo.setAdPositionInPod(<ad_position_in_pod>)        //Integer Value
adInfo.setAdPodLendth(<pod_length>)                    //Integer Value
adInfo.setIsBumper(<is_bumper>)                        //Boolean Value

mmCustomAdapter.reportAdStart(adInfo: adInfo)
mmCustomAdapter.reportAdEnd()

Ad Info Fields & Description

adTitle

String

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

adId

String

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

adUniversalId

String

A globally consistent identifier for an ad creative that remains the same across all platforms and systems, enabling unified tracking and reporting.

adCreativeId

String

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

adCreativeType

String

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

adClient

String

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

adPosition

String

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

adServer

String

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

adResolution

String

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

adUrl

String

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

adDuration

Integer

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

adPodIndex

Integer

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

adPositionInPod

Integer

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

adPodLendth

Integer

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

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

mmCustomAdapter.reportAdBufferingStrated();
mmCustomAdapter.reportAdBufferingCompleted();

Step 9.4: Report Ad Events:

Use the reportAdEvent function to report all Ad events.

reportAdStart and reportAdEnd are kept as it is for backward compatibility, but going forward, all the new Integrations should use the reportAdEvent API for all ad states.

mmCustomAdapter.reportAdEvent(adEvent: MMAdEvent, adInfo: adInfo);

MMAdEvent (Enum)

Ad Event

Description

AD_START

Report on ad start.

AD_FIRST_QUARTILE

Report on ad reached first quartile.

AD_MID_POINT

Report on ad reached midpoint.

AD_THIRD_QUARTILE

Report on ad reached third quartile.

AD_SKIP

Report on ad skipped.

AD_END

Report on ad ended.

AD_COMPLETE

Report on ad ended and ad play time greater than 95%.

AD_CLICK

Report on ad clicked.

Step 9.5: Report Ad Request and Response:

Report Ad Request and Ad Response using the following API:

Both APIs accept a dictionary of type [String: Any] containing the relevant ad request or ad response metadata.

mmCustomAdapter.reportAdRequest(requestInfo: [String: Any]);
mmCustomAdapter.reportAdResponse(responseInfo: [String: Any]);

Step 9.6: Report Ad Errors and Warnings:

Ad Errors:

mmCustomAdapter.reportAdError(errorCode: "ERROR_CODE", errorMessage: "ERROR_MESSAGE", errorDetails: "ERROR_DETAILS");

Ad Warnings:

mmCustomAdapter.reportAdWarning(warningCode: "WARNING_CODE", warningMessage: "MARNING_MESSAGE", warningDetails: "WARNING_DETAILS");

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

mmCustomAdapter.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 30 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.

Release Notes

Current Release

v3.4.1 `^{_{July 19, 2026}}`

Added v3.3.1 crash fix on top v3.4.0.
Added a new public shutdown() API to gracefully terminate the SDK. Invoking this API destructs all initialized SDK objects and releases associated resources.

Previous Releases

v3.3.1 `^{_{July 17, 2026}}`

Fixed an EXC_BAD_ACCESS memory crash on the SDK registration callback.

v3.4.0 `^{_{July 15, 2026}}`

Enhanced Internal SDK data reporting
- Added batch-based data reporting with configurable reporting intervals.
- Improved reliability with exponential backoff retries, jitter, request timeouts, and Dead Letter Queue (DLQ) support.
- Enabled remote configuration for batch size, reporting interval, retry settings, and the batching feature flag.
Added new APIs for reporting ad events, including quartiles, request/response, errors, warnings, skip, and click events.
Added support for reporting device capabilities through DeviceInfo.

v3.3.0 `^{_{Jun 02, 2026}}`

Added x86_64 simulator support for the VisionOS platform. (Missed in v3.2.0)

v3.2.0 `^{_{May 29, 2026}}`

Added x86_64 simulator support

v3.1.1 `^{_{May 04, 2026}}`

Fixed the MMPlayerState missing issue.

v3.1.0 `^{_{Apr 21, 2026}}`

Added support for multiple player instances within a single application.
Added the following new metadata fields:
- Player ID - report it using setPlayerId as part of Registration Information.
- DRM Level - report it using setDrmLevel as part of the Asset Information.
- Ad Universal ID - report it using setAduniversalId as part of the Ad Information.
Added new APIs to report Registration Information and Device Information before initialization (refer to Step 2).
MMAdInfo replaced with AdInformation class (refer to Step 9.2).
Deprecations:
- updateDRMType(drmType) → Deprecated
  - Use updateDRM(drmProtection, drmLevel) (refer to Step 5.8)
- initializeAssetForPlayer(assetInfo:, registrationInfo:, deviceInfo:) → Deprecated
  - Use initializeAssetForPlayer(assetInfo:) (refer to Step 3.1)
  - Report RegistrationInfo and DeviceInfo separately before initialization.
Buffering events exceeding the stats interval are now included in the stats payload.
Updated metadata lifecycle handling:
- Step 2 metadata fields persist across the SDK instance lifecycle.
- All Metadata fields from Step 3 are reset for every playback session.

Non-Multiplayer Releases

PreviousMediaMelon iOS Custom SDK Integration Document

NextMediaMelon iOS AVPlayer SDK Integration Document

Last updated 30 minutes ago

Step 1: Add MediaMelon SDK

Step 2: Instantiate and Register SDK

Step 2.1: SDK Instance Creation:

Step 2.2: Report Registration Information:

Step 2.3: Report Device Information:

Step 2.4: Report Application Information:

Step 2.5: Report Sub Property ID:

Step 3: Initialize Playback Session

Step 3.1: Initialize Session with Content Metadata:

Step 3.2: Report View Session ID:

Step 3.3: Report Experiment Name:

Step 3.4: Report Preload:

Step 3.5: Report Player Resolution:

Step 3.6: Report User-Initiated Playback:

Step 4: Additional Custom Metadata

Step 5: Network and Stream Information

Step 5.1: Report Network Information:

Step 5.2: Report CDN Information:

Step 5.3: Report Stream Information:

Step 5.4: Report Encoding Service:

Step 5.5: Report Video Presentation Information:

Step 5.6: Report Track Information:

Step 5.7: Report Rendition:

Step 5.8: Update DRM:

Step 6: Chunk/Segment Information

Step 6.1: Report Download Rate:

Step 7: Player Events

Step 7.1: Report Player State:

Step 7.2: Report Buffering:

Step 7.3: Report Seek:

Step 7.4: Report Error:

Step 7.5: Report Warning:

Step 7.6: Report Playback Position:

Step 8: Fallback & Request Status

Step 8.1: Report Fallback Event:

Step 8.2: Report Request Status:

Step 9: Ad Data & Ad Events

Step 9.1: Report Ad Break Start & End:

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

Step 9.3: Report Ad Buffering:

Step 9.4: Report Ad Events:

Step 9.5: Report Ad Request and Response:

Step 9.6: Report Ad Errors and Warnings:

Step 10: Custom Events

Release Notes

v3.4.1 July 19, 2026

v3.3.1 July 17, 2026

v3.4.0 July 15, 2026

v3.3.0 Jun 02, 2026

v3.2.0 May 29, 2026

v3.1.1 May 04, 2026

v3.1.0 Apr 21, 2026

Non-Multiplayer Releases

v3.4.1 `^{_{July 19, 2026}}`

v3.3.1 `^{_{July 17, 2026}}`

v3.4.0 `^{_{July 15, 2026}}`

v3.3.0 `^{_{Jun 02, 2026}}`

v3.2.0 `^{_{May 29, 2026}}`

v3.1.1 `^{_{May 04, 2026}}`

v3.1.0 `^{_{Apr 21, 2026}}`