Media Tracking

  • 3 minute(s) read
Prev Next

You can use our media tracking API to track user behavior on your media files.

Parameter Constants

The following parameters are mandatory and need to be configured (in Mapp Q3 > Configuration >…) when initializing the MIMediaParameters() object.

Parameter

Description

Where to analyze

name

The name of the video, as displayed in Intelligence

Navigation > Media > Media

action

The following actions are possible:

  • init/play: initialize media tracking / play video. This must be the first action in order to start a media session.

  • pause: must be sent with a click on the pause button in the media player. In "pause" mode, no other position actions should be sent.

  • stop: ends a media session and is sent with a click on the stop button in the media player, which sends the video back to the beginning. If a video is ended with the action "stop", the action "play" must be sent by the next click on the play button so that a new media session can start.

  • pos: should be sent every 30 seconds. It is used for tracking the viewed chapters of a video and the last position of the video, in case the user ends the video by closing the browser tab/window.

    This action should be sent when the media player is in "play" mode. Once the video is paused or stopped, the timer for sending these actions must be stopped.

  • seek: sends the current position when the Forward or Back button is clicked. This action controls the seeking function within a video.

    If the seek button is let go, further action is required to indicate the end of the Seek. This second action is dependent on the mode in which the media player is. If seek was clicked during the playing of a video, then "play" is sent as the second action. If seek was clicked while the player was in Pause mode, then the "pause" is sent as the second action.

    The current position is sent with the new play time of where the video is after the user has clicked on the second action ("play" or "pause").

  • eof: must be sent at the end of a video and serves to end the media session. The current time and the total play time are always identical with this action.

  • custom actions: It is possible to specify your own actions (e.g., "recommend")

Navigation > Media > Media Player Actions

position

Marks the current position of the video when sending the request.

Navigation > Media > Media Run Time

duration

Specifies the total length of the video.

-

The following parameters are optional and can be configured in the MIMediaParameters() object.

Parameter

Description

Where to configure (Mapp Q3 > Configuration > ...)

Where to analyze

customCategories

You can assign additional information to the media.

Categories > Media Categories > New Category

Datatype Text: Navigation > Media Categories > [Name of media category]

Datatype Figure: metric

soundVolume

Volume, number 0-255, 0 is minimal, 255 is maximal

-

Navigation > Media > Media Player Volume

soundIsMuted

(1=mute active, volume off, 0=mute not active, volume on)

-

Navigation > Media > Media Player Mute

bandwidth

Bandwidth bits/seconds

-

Navigation > Media > Media Bandwidth

Methods for Media Tracking

Method

Description

trackMedia()

Used track media events in Intelligence. It must contain the name of the file, action, position, and duration of the media.

Example iOS

Please note that custom parameters are optional in the request.

  1. Define all the information you want to track:

    let mediaProperties = MIMediaParameters("TestVideo", action: "play", position: 12, duration: 120)
mediaProperties.customCategories = [20:”customCategory”]
let mediaEvent = MIMediaEvent(pageName: "Test", parameters: mediaProperties)

  2. Call the trackMedia method

    MappIntelligence.shared()?.trackMedia(mediaEvent)

Full Code Example

@IBAction func trackMedia1(_ sender: Any) {
     let mediaProperties = MIMediaParameters("TestVideo", action: "play", position: 12, duration: 120)
     mediaProperties.customCategories = [20:”customCategory”]
     let mediaEvent = MIMediaEvent(pageName: "Test", parameters: mediaProperties)
     MappIntelligence.shared()?.trackMedia(mediaEvent)
}

  1. Define all the information you want to track:

    MIMediaParameters* mediaProperties = [[MIMediaParameters alloc] initWith:@"TestVideo" action:@"view" position: [NSNumber numberWithInt:12] duration:[NSNumber numberWithInt:120]];
[mediaProperties setCustomCategories:[NSDictionary dictionaryWithObject:@"customCategory" forKey:@20]];
MIMediaEvent* mediaEvent = [[MIMediaEvent alloc] initWithPageName:@"Test" parameters:mediaProperties];

  2. Call the trackMedia method

    [[MappIntelligence shared] trackMedia: mediaEvent];

Full Code Example

-(void)trackMedia {
    MIMediaParameters* mediaProperties = [[MIMediaParameters alloc] initWith:@"TestVideo" action:@"play" position: [NSNumber numberWithInt:12] duration:[NSNumber numberWithInt:120]];
    [mediaProperties setCustomCategories:[NSDictionary dictionaryWithObject:@"customCategory" forKey:@20]];
    MIMediaEvent* mediaEvent = [[MIMediaEvent alloc] initWithPageName:@"Test" parameters:mediaProperties];
     
    [[MappIntelligence shared] trackMedia: mediaEvent];
}

Demo app for iOS features tracking volume and mute state through AVAudioSession.sharedInstance().

Since AVAudioSession.sharedInstance() always returns the same volume level in tvOS, volume and mute tracking its not present in the tvOS example app. However, SDK API allows setting these for tracking with Media event, thus it's possible to implement it in your own app.