Media

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

dependencies {
    implementation 'com.mparticle:android-media:1.0'
}

Creating an instance of a Media Session

The Android Media SDK provides a MediaSession object. Each MediaSession 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.

val mediaSession = MediaSession.builder {
    title = "Media Title"
    mediaContentId = "123"
    duration = 1000
    streamType = StreamType.LIVE_STEAM
    contentType = ContentType.VIDEO
}

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
mediaSession.logMediaSessionStart()
  1. Log a play event
mediaSession.logPlay()
  1. (optional) Fire other events for user interaction, i.e. pause
mediaSession.logPause()
  1. End the Media Content once the content is complete
mediaSession.logMediaContentEnd()
  1. End the Media Session once the user interaction is over (such as after a post-roll or if the app is terminated)
mediaSession.logMediaSessionEnd()

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
mediaSession.logAdBreakStart {
        id = "123456"
        title = "pre-roll"
        duration = 6000
}
  1. Trigger an AdStart event
mediaSession.logAdStart {
        id = "4423210"
        advertiser= "Moms Friendly Robot Company"
        title= "What?! Nobody rips off my kids but me!"
        campaign= "MomCorp Galactic Domination Plot 3201"
        this.duration = 60000
        creative= "A Fishful of Dollars"
        siteId= "moms"
        placement= 0
}
  1. Fire AdEnd or AdSkip when appropriate
mediaSession.logAdEnd()
  1. Trigger an AdBreakEnd event when all ads have completed
mediaSession.logAdBreakEnd()

API Reference

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

Was this page helpful?