JarCasting
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 [email protected] 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.3.1'
}
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
}
//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)
Logging MediaEvents as Custom Events (MPEvent) to the MParticle Server
- Automatically Log all
MediaEvents created by theMediaSession, asMPEvents
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 logsMediaEventcreated byMediaSession.logPlay()calls
mediaSession.mediaEventListener = { mediaEvent ->
if (mediaEvent.eventName == MediaEventName.PLAY) {
val mpEvent = mediaEvent.toMPEvent()
MParticle.getInstance()?.logEvent(mpEvent)
}
}
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
License
The mParticle Android SDK is available under the Apache License, Version 2.0. See the LICENSE file for more info.
