MediaMelon iOS AVPlayer SDK Integration Document

This guide provides detailed instructions on integrating the MediaMelon AVPlayer SDK into an iOS/tvOS Media Player Application.

Step 1: Setup The SDK

Step 2: Import Frameworks

Step 3: Register and Initialize MediaMelon SDK

Step 4: Additional Custom Metadata

Step 5: Errors and Warnings

Step 6: Report Additional Metadata Fields

Step 7: Cleaning up the SDK Session

Step 8: Update Asset Information

Step 9: Additional Configurations

Release Notes

Step 1: Set up MediaMelon SDK

SPM

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

Cocoapods

target 'SwiftDemo' do
  .
  .
  pod 'MediaMelon-AVPlayer-SDK', '~> 2.5.0'
end

The MediaMelon-AVPlayer-SDK pod includes a dependency on the MediaMelon-QoE-SDK framework pod. This dependency framework supports both iOS and tvOS platforms.

Check the latest available version of MediaMelon-QoE-SDK here.

Step 2: Import Frameworks

import MediaMelonQoE
import MediaMelon_AVPlayer_SDK

Step 3: Register and Initialize MediaMelon SDK

Step 3.1: Set SDK Registration Information:

let registrationInfo = MMRegistrationInformation(customerID: "CUSTOMER_ID", playerName: "PLAYER_NAME")
registrationInfo.setPlayerInformation(brand: "PLAYER_BRAND", model: "PLAYER_MODEL", version: "PLAYER_VERSION")
registrationInfo.setBasePlayerInformation(basePlayerName: "BASE_PLAYER_NAME", basePlayerVersion: "BASE_PLAYER_VERSION")
registrationInfo.setSubscriberInformation(subscriberID: "SUBSCRIBER_ID", subscriberType: "SUBSCRIBER_TYPE", subscriberTag: "SUBSCRIBER_TAG", hashSubscriberID: <Bool>)
registrationInfo.setDomain("DOMAIN_NAME")

CUSTOMER_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID, contact MediaMelon at [e-mail].

Step 3.2: Report Application Information:

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

Step 3.3: Report Experiment Name & Sub Property ID:

AVPlayerIntegrationWrapper.shared.reportExperimentName(experimentName: "EXPERIMENT_NAME")
AVPlayerIntegrationWrapper.shared.reportSubPropertyID(subPropertyId: "SUB_PROPERTY_ID") 

Step 3.4: Set Content Metadata and Initialize Session:

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.addCustomKVP("CUSTOM_1", "VALUE_1")
assetInfo.addCustomKVP("CUSTOM_2", "VALUE_2")

AVPlayerIntegrationWrapper.shared.reportViewSessionID(viewSessionId: "VIEW_SESSION_ID")
AVPlayerIntegrationWrapper.initializeAssetForPlayer(assetInfo: assetInfo, registrationInformation: registrationInfo, player: player, isLive: <Bool>)

For Custom Metadata, first, provide the mapping in the SmartSight dashboard under the settings section and send the values to the SDK accordingly. Refer to Custom Metadata Configuration Guide.

Step 4: Additional Custom Metadata

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

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.

AVPlayerIntegrationWrapper.shared.reportCustomMetadata(key: "KEY", value: "VALUE")

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

⚠️ 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.

🚫 Disabling Auto Error Capture:

If you prefer to handle error reporting manually, you can disable this automatic behavior by calling:

AVPlayerIntegrationWrapper.shared.disableAutoErrorCapture()

⚠️ 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.

🛠️ 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.

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

🟠 Report Warning (Non-Fatal):

All warnings reported via reportWarning are treated as non-fatal and will be tracked accordingly.

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

Step 6: Report Additional Metadata Fields

Step 6.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.

AVPlayerIntegrationWrapper.shared.reportCDN(cdn: "CDN")

Step 6.2: Stream Information:

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

AVPlayerIntegrationWrapper.shared.reportStreamInfo(streamFormat: "STREAM_FORMAT", mediaType: "MEDIA_TYPE", sourceType: "SOURCE_TYPE")

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

AVPlayerIntegrationWrapper.shared.reportPlayerResolution(width: <player_width>, height: <player_height>)

Step 6.4: Report Stream Fallback Event

Report fallback event in case the primary manifest URL fails and falls back on the secondary manifest.

AVPlayerIntegrationWrapper.shared.reportFallbackEvent(fallbackManifestURL: "FALLBACK_URL", description: "DESCRIPTION")

Step 7: Cleaning up the SDK Session

We need to clean up the SDK session once the playback completes. The SDK internally manages the cleanup for most of the cases. For example - when playback finishes, or some error is notified.

However, in some error cases, like network reachability issues, the error notification is delayed. And before this error notification is available, the user may trigger another session. Therefore, it is advised to clean up the session once the playback finishes.

We recommend cleaning up the SDK session after playback completes or when the player lifecycle is complete. Missing to clean up the SDK session, might playtime, and session end time.

AVPlayerIntegrationWrapper.cleanUp()

Step 8: Update Asset Information

To update the asset information during a content change or a live session, use the changeAssetForPlayer method as shown below. Whenever the asset information is updated, a new SDK session will be initialised. Please note either changeAssetForPlayer or initializeAssetForPlayer should be called not both.

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

The new Asset Info Object will override the previous values. Hence, set all the necessary fields every time this API is called, including all Custom Tags.

// Create a new assetInfo object with the values that need to be updated
let newAssetInfo = MMAssetInformation(assetURL: "STREAM_URL", assetID: "ASSET_ID", assetName: "ASSET_NAME", videoId: "VIDEO_ID")
newAssetInfo.setContentType("CONTENT_TYPE")
newAssetInfo.setDrmProtection("DRM_PROTECTION")
newAssetInfo.setEpisodeNumber("EPISODE_NUMBER")
newAssetInfo.setSeriesTitle("SERIES_TITLE")
newAssetInfo.setSeason("SEASON")
newAssetInfo.setGenre("GENRE")

AVPlayerIntegrationWrapper.changeAssetForPlayer(assetInfo: newAssetInfo, player: player)

Step 9: Additional Configurations

Step 9.1: Disable manifest fetch by the SDK (Optional)

If your workflow limits access to the manifest from both the player and the MediaMelon Player SDK at the same time, you have the option to prevent manifest fetching by using the disableManifestsFetch method calling it before initialization.

AVPlayerIntegrationWrapper.disableManifestsFetch(disable: true)

Step 9.2: Enable or Disable SDK Log Trace

To enable the SDK log trace, use the following API call: enableLogTrace.

AVPlayerIntegrationWrapper.shared.enableLogTrace(logStTrace: true)

Release Notes

Current Release

v2.6.1 ^{_{Sep 08, 2026}}

• Initial SDK release via SPM

Dependency Framework Releases: MediaMelon-QoE-SDK

---

Previous Releases

v2.5.0 ^{_{Mar 09, 2026}}

• Added App Session ID metadata fields.

• Updated Base Player Information reporting.

• Added CDN_CHANGE event.

v2.4.0 ^{_{Nov 06, 2025}}

• Combined iOS and tvOS frameworks into a single xcframework.

• Fixed the DRM protection reset issue.

• Added Stream Information API.