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, play, pause, milestones, and end, 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 Web 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

Before you can begin using the Media SDK, you need to have a working instance of the mParticle core SDK. At present, we offer support for our Media SDK in a self-hosting environment. For more information on this, please refer to the self-hosting documentation.

  1. Install relevant npm packages for your project. The below example uses our Adobe Client web integration. When adding Adobe as an output for Javascript in the mParticle web app, there is a setting for Media Tracking Server. When you fill this out, mParticle will load the Heartbeat SDK and send media events to it.
// command line
npm i @mparticle/web-sdk @mparticle/web-media-sdk @mparticle/web-adobe-client-kit
  1. In your main js file, import these modules, and add an mParticle configuration:
// Import each library
import mParticle from '@mparticle/web-sdk';
import MediaSession from '@mparticle/web-media-sdk';
import Adobe from '@mparticle/web-adobe-client-kit';

// Configure mParticle as needed for your project
const mParticleConfig = {
  // configuration items
};

// Register each kit to the configuration
Adobe.register(mParticleConfig);

// Initialize mParticle
mParticle.init('your-api-key', mParticleConfig);

Creating an instance of a Media Session

The Web 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.

const mediaSession = new MediaSession(
  mParticle, // Global mParticle SDK Instance
  '1234567', // Custom media ID
  'Funny Internet cat video', // Custom media Title
  120000, // Duration in milliseconds
  'Video', // Content Type (Video or Audio)
  '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
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.logMediaEnd();
  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: "Mom's Friendly Robot Company",
  title: 'What?! Nobody rips off my kids but me!',
  campaign: 'MomCorp Galactic Domination Plot 3201',
  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?