MediaSession

Class

constructor

Create a new media session and define a unique name of the media you want to track.

/**
 * @param {string} name
 *
 * @constructor
 */
wtSmart.extension.media.MediaSession(name);

setTotalTime

Define the total play duration of this media. Entered as a whole number, in terms of seconds.

/**
 * @param {number} total
 */
mediaSession.setTotalTime(total);

setBandwidth

Define the bandwidth in bits/second. Entered as a whole number. Only the last value sent in a medias session is saved.

/**
 * @param {number} bandwidth
 */
mediaSession.setBandwidth(bandwidth);

setVolume

Define the values between 0 and 255 are accepted. It is recommended to use 0 to 100 in order to analyze the volume in terms of percent in the tool. The spectrum from 0 to 255 is accepted here due to compatibility reasons. Only the last value sent in a Medias session is saved.

/**
 * @param {number} volume
 */
mediaSession.setVolume(volume);

setCategory

In the same way that pages are grouped into categories as content groups, media can be grouped into media categories. Media categories are used to group several videos.

Media categories must be configured in the Mapp Q3 tool so that they can be tracked. This is completed under "Configuration > Categories > Media Categories".

/**
 * @param {{[number]: string}} category
 */
mediaSession.setCategory(category);

getPositionInterval

Get the time interval for this media (in ms) to be send a position request.

/**
 * @returns {number}
 */
mediaSession.getPositionInterval();

mute

Set the mute status to mute.

mediaSession.mute();

unMute

Set the mute status to unmute.

mediaSession.unMute();

Media actions

The metrics for the media streams are calculated based on the media actions and the sent position. Thus, you must ensure that the requests are sent in the correct sequence. For example, no actions will be tracked as long as no "play" event has occurred for the video.

With parameters, you can track additional information about the current media.

init

The action "init" is used for the initialization of a video and start the media session.

Ensure that with this action the entire playtime and media categories must be sent before.

/**
 * @param {number} current
 * @param {{[number]: string}} [parameter]
 */
mediaSession.init(current, parameter);

play

The action "play" is used for the playback of a video and start the media session.

Ensure that with this action the entire playtime and media categories must be sent before.

/**
 * @param {number} current
 * @param {{[number]: string}} [parameter]
 */
mediaSession.play(current, parameter);

pause

The action "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.

/**
 * @param {number} current
 * @param {{[number]: string}} [parameter]
 */
mediaSession.pause(current, parameter);

stop

The action "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.

/**
 * @param {number} current
 * @param {{[number]: string}} [parameter]
 */
mediaSession.stop(current, parameter);

seek

The action "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, a 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 the Seek was clicked during the playing of a video, then the "play" is sent as the second action. If the 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").

/**
 * @param {number} current
 * @param {{[number]: string}} [parameter]
 */
mediaSession.seek(current, parameter);

position

The action "position" should be sent every 30 seconds or use the method "getPositionInterval" to gets the time interval (in ms) to sends a position action. 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.

Please note that the tracking of the current position of a media file without transferring total time, e.g. live streams, is only possible every 60 seconds.

/**
 * @param {number} current
 * @param {{[number]: string}} [parameter]
 */
mediaSession.position(current, parameter);

end

The action "end" 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.

/**
 * @param {number} current
 * @param {{[number]: string}} [parameter]
 */
mediaSession.end(current, parameter);

custom

In addition to the standard actions, any other action can be tracked using media actions. For example, advertisement pre-roll starts and pre-roll ends can be tracked.

/**
 * @param {string} action
 * @param {number} current
 * @param {{[number]: string}} [parameter]
 */
mediaSession.custom(action, current, parameter);

Example

// get new media session
var mediaSession = new wtSmart.extension.media.MediaSession('foo.bar');

// set total time
mediaSession.setTotalTime(6000);
// set bandwidth
mediaSession.setBandwidth(512);
// set volume
mediaSession.setVolume(95);
// set media categories
mediaSession.setCategory({
	5: 'category 5',
	12: 'category 12'
});

// the media is muted
mediaSession.mute();
// the media is unmuted
mediaSession.unMute();

// send media start
mediaSession.play(0, {
	2: 'action parameter 2',
	6: 'action parameter 6'
});
// send current position from the media 
mediaSession.position(200);
// send media pause 
mediaSession.pause(200);
// send media play
mediaSession.play(200);
// send current position from the media 
mediaSession.position(500);
// send start of the media seek
mediaSession.seek(600);
// send end of the media seek with the current status (play / pause)
mediaSession.play(1000);
// send media ad start
mediaSession.custom('ad start', 2000);
// send media ad end
mediaSession.custom('ad end', 2050);
// send media stop
mediaSession.stop(4000);
// send media start
mediaSession.play(0);
// send media end
mediaSession.end(6000);