mParticle Android Media SDK

Hello! This is the public repo of the mParticle Android Media SDK. We've built the mParticle platform to take a new approach to web and mobile app data and the platform has grown to support 50+ services and SDKs, including developer tools, analytics, attribution, messaging, and advertising services. mParticle is designed to serve as the connector between all of these services - check out our site, or hit us at developers@mparticle.com to learn more.

Documentation

Fully detailed documentation and other information about mParticle Android SDK can be found at our doc site

Getting Started

Please be aware that this SDK is built as an extension of and requires the use of the mParticle Android SDK.

Include and Initialize the SDK

Below summarizes the major steps to get the Android Media SDK up and running. In addition to the below, we have built a sample app that provides a more in depth look at how to send MediaEvents to Adobe's Heartbeat Kit. See that sample app here

You can grab the Core SDK via Maven Central. Please see the badge above and follow the releases page to stay up to date with the latest version.

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

Code Samples

Starting a MediaSession and logging events. The MediaSession fields title, mediaContentId, duration, streamType, and contentType are all required fields. We reccomend you use the constants defined in StreamType and ContentType for the streamType and contentType fields respectively, but free formed Strings are accepted if these constants don't accurately describe your Media

    //initialize the core SDK
    val options = MParticleOptions.builder(context)
        .credentials("key", "secret")
        .build()
    MParticle.start(options)
    
    //initialize a MediaSession
    val mediaSession = MediaSession.builder {
        title = "Media Title"
        mediaContentId = "123"
        duration = 1000
        streamType = StreamType.LIVE_STEAM
        contentType = ContentType.VIDEO
        // Optional custom media session attributes
        mediaSession.mediaSessionAttributes = mutableMapOf(
            "my_session_attribute" to "My Session Attribute"
        )
    }
    
    //start the MediaSession
    mediaSession.logMediaSessionStart()
    
    //log events
    mediaSession.logPlay()
    mediaSession.logPause()

Updating playhead position while logging an event

    mediaSession.logPlay(
        Options(currentPlayheadPosition = 120000)
    )

Including customAttributes in an event. Common customAttribute keys are available as constants in OptionsAttributeKeys, but they may also be free formed Strings

    val options = Options(
            customAttributes = mapOf(
                "isFullScreen" to "true",
                CONTENT_EPISODE to "episode1",
                PLAYER_NAME to "JWPlayer"
            )
        )
    mediaSession.logPlay(options)

Custom media session attributes

You can create custom media session attributes when initializing a new media session by including the custom media session attributes object directly in MediaSession.builder:

mediaSession.mediaSessionAttributes = mutableMapOf(
    "my_session_attribute" to "My Session Attribute"
)

Custom media session attributes are automatically propagated to all media events logged during the session in addition to the media session summary event. Since custom session attributes are propagated to any event (a media event, advertising event, or a custom events) that is logged during the session, you don’t need to set these attributes again when you trigger the start of a media session. Following are the limitations for custom media session attributes:

100 key/value pairs per media session
Keys must be strings and cannot exceed 255 characters
Values may be strings, numbers, booleans, or dates, and cannot exceed 4096 characters

Logging `MediaEvent`s as Custom Events (`MPEvent`) to the MParticle Server

Automatically Log all MediaEvents created by the MediaSession, as MPEvents

note: "UpdatePlayheadPosition" MediaEvents will never be automatically logged to the MParticle Server

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

Create a Custom Event(MPEvent) within the context of a MediaSession.

val mpEvent = mediaSession.buildMPEvent("Milestone", mapOf(
    "type" to "95%"
  ))
MParticle.getInstance()?.logEvent(mpEvent)

Log select MediaEvents as Custom Events(MPEvents). The example flattens and logs MediaEvent created by MediaSession.logPlay() calls

mediaSession.mediaEventListener = { mediaEvent ->
    if (mediaEvent.eventName == MediaEventName.PLAY) {
        val mpEvent = mediaEvent.toMPEvent()
        MParticle.getInstance()?.logEvent(mpEvent)
    }
}

Logging Media Errors

The MediaSession#logError(String, Map) method is similar to the generic MParticle#logError(String, Map) method, but should be used for logging events specific to an individual MediaSession.

Like all other Media events, "Error" events will not be sent to the MParticle Server by default, but will be consumed by local kits. To log this event to the MParticle Server, follow the previously outlined instructions

example:

//log a MediaSession-specific error as a MediaEvent
mediaSession.logError("Player Crashed", mapOf("foo", "bar"))

//log a general error as an core event
MParticle.getInstance()?.logError("Request timed out", mapOf("foo", "bar"))

Contibution Guidelines

At mParticle, we are proud of our code and like to keep things open source. If you'd like to contribute, simply fork this repo, push any code changes to your fork, and submit a Pull Request against the development branch of mParticle-android-media-sdk.

Support

support@mparticle.com

License

The mParticle Android SDK is available under the Apache License, Version 2.0. See the LICENSE file for more info.

mParticle/mparticle-android-media-sdk