Collecting media data is critical for tracking user behavior when your customers consume video or audio content through Android and iOS mobile applications or on the web. mParticle provides a toolset for integrating media analytics into your customer experience.

The mParticle Media SDK provides a dedicated API for tracking common media events including session start/end, play, pause, and other milestones, as well as logging recurring advertising impressions and chapters for segmented content.

The mParticle Media SDK works hand in hand with the mParticle platform. Data logged from the Media SDK is forwarded to the Apple SDK and then forwarded to any included integrations.

The mParticle Media SDK is compatible with Adobe Analytics for Media, supporting the full range of media-related events including heartbeat events. This simplifies an otherwise complicated and error-prone process of setting up media session event tracking and Adobe Heartbeat yourself.

Getting Started

Add the SDK

Before you can begin using the Media SDK, you need to have a working instance of the mParticle core SDK. Please see the core SDK getting started section for more details.


To integrate the SDK using CocoaPods, specify it in your Podfile:


target '<Your Target>' do
    pod 'mParticle-Apple-SDK', '~> 7.12.0'
    pod 'mParticle-Apple-Media-SDK', '~> 1.0-beta.1'


To integrate the SDK using Carthage, specify it in your Cartfile:

github "mparticle/mparticle-apple-sdk" ~> 7.12
github "mparticle/mparticle-apple-media-sdk" ~> 1.0

Creating an instance of a Media Session

The Apple iOS Media SDK provides a MPMediaSession object. Each MPMediaSession object represents a single end to end media experience and relates one-to-one to a piece of content. For example, if a customer is watching a video, pausing, seeking and scrubbing, that is considered a single session. If they stop the video, and play another piece of content, that is a new session.

let mediaSession = MPMediaSession.init(
    coreSDK:  MParticle.sharedInstance(), // mParticle SDK Instance
    mediaContentId: '1234567',            // Custom media ID
    title: 'Funny internet cat video',    // Custom media Title
    duration: 120000,                     // Duration in milliseconds
    contentType: .video,                  // Content Type (Video or Audio)
    streamType: .onDemand)                // Stream Type (OnDemand, Live, etc.)

You can access the and contribute to the mParticle Media SDK Github repo here.

Logging media events

Once your session is instantiated, you will need to trigger a SessionStart. This should be done at the moment the user interacts with your content. For example, if the media is set to trigger on a user click, and your player fires a play event when the content starts, the session must begin before the play event.

  1. Start a session
  1. Log a play event
  1. (optional) Fire other events for user interaction, i.e. pause
  1. End the Media Content once the content is complete
  1. End the Media Session once the user interaction is over (such as after a post-roll or if the app is terminated)

Logging Advertising

In most cases, advertising comes in as a series of Ad Breaks each containing numerous Ads. The Media SDK provides both sets of functionality so that you can track this behavior.

  1. Fire an AdBreakStart event
let adBreak = MPMediaAdBreak.init(title: "pre-roll", id: "123456")
adBreak.duration = 6000
  1. Trigger an AdStart event
let adContent = MPMediaAdContent.init(title: "What?! Nobody rips off my kids but me!", id: "4423210")
adContent.advertiser = "Mom's Friendly Robot Company"
adContent.campaign = "MomCorp Galactic Domination Plot 3201"
adContent.duration = 60000
adContent.creative = "A Fishful of Dollars"
adContent.siteId = "moms"
adContent.placement = 0
mediaSession.logAdStart(adContent: adContent)
let adBreak = MPMediaAd.init(title: "pre-roll", id: "123456")
  1. Fire AdEnd or AdSkip when appropriate
  1. Trigger an AdBreakEnd event when all ads have completed

API Reference

Visit the complete API Reference for a deep dive into the Media SDK

Was this page helpful?