AV Insights (audio video)

AV Insights allows the collection of events related to media consumption. You will be able to follow the different interactions on your players and measure the performance of your content. The AV Insight tracker is designed to give you options on the level of information you want to measure.

Media management

Media instantiation

In order to be able to manipulate a media and measure its events, it is necessary to declare an object:

Javascript

var myMedia = new pa.avInsights.Media([heartbeatDuration, bufferingHeartbeatDuration, sessionId]);

Parameter	Type	Description	Example
heartbeatDuration (optional)	int, object	Delay between two heartbeat during playback (minimum delay is 5sec). If the value is a int, this will be the delay for the whole playback. You can also set an object such as { 0:5, 1:10, 5:60 }, meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec	5 or { 0:5, 1:10, 5:60 }
bufferingHeartbeatDuration (optional)	int, object	Delay between two heartbeat during buffering (minimum delay is 1sec). If the value is a int, this will be the delay for the whole buffering. You can also set an object such as { 0:5, 1:10, 5:60 }, meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec	5 or { 0:5, 1:10, 5:60 }
sessionId (optional)	string	Session ID of the playback. This ID is automatically managed by the SDK, but you can override it if you know what you are doing. More details in the next section.	`

var myMedia = new pa.avInsights.Media(5, 5);
// or
var myMedia = new pa.avInsights.Media({ 0:5, 1:10, 5:60 }, 5);

note

Two parameters are available, in order to activate the heartbeats. The first one enables playback tracking heartbeats and the second one enables buffering tracking heartbeats.

Android (3.3.0+)

Declare your heartbeat delays and content ID thanks to MediaHelper class:

val heartbeat = SparseLongArray()
// first minute will be 5sec delay
heartbeat.put(0, 5)
// starting from minute 1, 10sec
heartbeat.put(1, 10)
// and after the 5th minute, the delay will be 60sec
heartbeat.put(5, 60)
val bufferHeartbeat = SparseLongArray()
bufferHeartbeat.put(0, 5)
val myMedia = PianoAnalytics.getInstance()
  .mediaHelper("fg456") // Content ID
  .setHeartbeat(heartbeat)
  .setBufferHeartbeat(bufferHeartbeat)

Android

var myMedia = AVMedia(pa: PianoAnalytics, sessionId: String? = nil)

Parameter	Type	Description	Example
pa	PianoAnalytics	Tracker instance	pa
sessionId (optional)	String?	Session ID of the playback. This ID is automatically managed by the SDK, but you can override it if you know what you are doing. More details in the next section.	`

var myMedia = AVMedia(pa: pa)

In order to setup automatic heartbeats management, you have to call the dedicated methods:

myMedia.setHeartbeat(heartbeat: [Int: Int]?)

Parameter	Type	Description	Example
heartbeat	[Int: Int]?	Delay between two heartbeat during playback (minimum delay is 5sec). You can set a map such as [0:5, 1:10, 5:60], meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec	[0:5, 1:10, 5:60]

myMedia.setHeartbeat(heartbeat: [
    0: 5,
    1: 10,
    5: 60
])

myMedia.setBufferHeartbeat(bufferHeartbeat: [Int: Int]?)

Parameter	Type	Description	Example
bufferHeartbeat	[Int: Int]?	Delay between two heartbeat during buffering (minimum delay is 1sec). You can set a map such as [0:5, 1:10, 5:60], meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec	[0:5, 1:10, 5:60]

myMedia.setBufferHeartbeat(bufferHeartbeat: [
    0: 5,
    1: 10,
    5: 60
])

Apple

Begin by importing io.piano.analytics.avinsights.Media into your file:

import io.piano.analytics.avinsights.Media;

In order to be able to manipulate a media and measure its events, it is necessary to declare an object of type Media :

Media myMedia = new Media(pa);
// or
Media myMedia = new Media(pa, sessionId);

Parameter	Type	Description	Example
pa	PianoAnalytics	Tracker instance	pa
sessionId (optional)	String	Session ID of the playback. This ID is automatically managed by the SDK, but you can override it if you know what you are doing. More details in the next section.	`

In order to setup automatic heartbeats management, you have to call the dedicated methods:

myMedia.setHeartbeat(heartbeat)

Parameter	Type	Description	Example
heartbeat	SparseIntArray	Delay between two heartbeat during playback (minimum delay is 5sec). You can set a map such as [0:5, 1:10, 5:60], meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec	[0:5, 1:10, 5:60]

myMedia.setHeartbeat(new SparseIntArray()
    .append(0, 5)
    .append(1, 10)
    .append(5, 60)
);

myMedia.setBufferHeartbeat(bufferHeartbeat)

Parameter	Type	Description	Example
bufferHeartbeat	SparseIntArray	Delay between two heartbeat during buffering (minimum delay is 1sec). You can set a map such as [0:5, 1:10, 5:60], meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec	[0:5, 1:10, 5:60]

myMedia.setBufferHeartbeat(new SparseIntArray()
    .append(0, 5)
    .append(1, 10)
    .append(5, 60)
);

Session ID management

warning

Please note that this setup should be used only in special cases, when you need to transfer sessions between different device for example.

Javascript

An optional third parameter sessionId is available to override the common standard property av_session_id present in each event generated by AV Insights tags.

The parameter is automatically managed by the SDK for all standard cases.

var myMedia = new pa.avInsights.Media(5, 5, 'custom_session_id');

A function getSessionID can be used to retrieve the value of the parameter:

getSessionID() ⇒ string | number

Retrieve the session ID.

Example

var sessionID = myMedia.getSessionID(); // 'custom_session_id' or 'xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxx'

Android (3.3.0+)

An optional second parameter mediaSessionId is available to override the common standard property av_session_id present in each event generated by AV Insights tags.

The parameter is automatically managed by the SDK for all standard cases.

val myMedia = PianoAnalytics.getInstance().mediaHelper("contentId", "custom-session-id")

Android

An optional second parameter sessionId is available to override the common standard property av_session_id present in each event generated by AV Insights tags.

The parameter is automatically managed by the SDK for all standard cases.

Media myMedia = new Media(pa, "custom-session-id");

Apple

An optional second parameter sessionId is available to override the common standard property av_session_id present in each event generated by AV Insights tags.

The parameter is automatically managed by the SDK for all standard cases.

var myMedia = new AVMedia(pa: pa, sessionId: "custom-session-id")

Media properties

Some rules must be observed regarding the format of the properties used for the configuration of a media :

• The av_content_id is a mandatory property that must be used for all media instances (see complete tagging example section).
• The duration of the media or the positions of the playback head must be expressed in milliseconds.

Javascript

The SDK provides useful functions for the management of Media properties:

set(propKey, propValue)

Declare a media property.

Parameter	Type	Description
propKey	string	Media property key
propValue	string, number	Media property value

Example

myMedia.set('av_content_id', 'fg456'); // mandatory
myMedia.set('av_content', 'my_video');

get(propKey) ⇒  string | number

Retrieve a media property.

Parameter	Type	Description
propKey	string	Media property key

Example

var content_id = myMedia.get('av_content_id'); // fg456

del(propKey)

Delete a media property.

Parameter	Type	Description
propKey	string	Media property key

Example

myMedia.del('av_content_id');

setProps(properties)

Declare multiple media properties.

Parameter	Type	Description
properties	Object	Media properties

Example

myMedia.setProps({'av_content_id': 'fg456', 'av_content': 'My Content'});

getProps() ⇒ Object

Retrieve all media properties.

Example

var props = myMedia.getProps(); // {'av_content_id': 'fg456', 'av_content': 'My Content'}

delProps()

Delete all media properties.

Example

myMedia.delProps();

Android (3.3.0+)

You need to manage your media properties to send them on every events, through the extraProps parameter of dedicated methods.

myMedia.setExtraProps(
  Property(PropertyName("av_content"), "my_video")
  Property(PropertyName("av_content_duration"), 2760000)
)

Android

You need to manage your media properties to send them on every events, through the extraProps parameter of dedicated methods.

Apple

You need to manage your media properties to send them on every events, through the extraProps parameter of dedicated methods.

myMedia.setExtraProps([
  "av_content": "my_video",
  "av_content_duration": 2760000
])

Events tracking

The SDK offers useful functions for measuring events related to your users’ interactions with your content:

Media events

play

Event name : av.play

Generate a play event (playback attempt).

Javascript

play(cursorPosition[, callback, extraProps])

Parameter	Type	Description
cursorPosition	number	Current cursor position (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.play(
  0,
  function() { console.log("Event av.play generated");},
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
properties vararg (optional)	Property	Custom properties

myMedia.play(
  0,
  Property(...),
  Property(...)
)

Android

func Media.play(cursorPosition, extraProps)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.play(
  0,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.play(cursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.play(
  cursorPosition: 0,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

bufferStart

Event name : av.buffer.start or av.rebuffer.start

Generate an event of buffering at the launch of a media or during the playing. The buffering.heartbeat is sent before the av.start while the rebuffering.heartbeat is sent after an av.start is recorded on the av_session_id.

Javascript

bufferStart(cursorPosition[, callback, extraProps])

A buffering flag will automatically generate buffering.heartbeat or rebuffering.heartbeat events depending on the context.

Parameter	Type	Description
cursorPosition	number	Current cursor position (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.bufferStart(
  0,
  function() { console.log("Event av.buffer.start or av.rebuffer.start generated depending on the playback launch"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
properties vararg (optional)	Property	Custom properties

myMedia.bufferStart(
  0,
  Property(...),
  Property(...)
)

Android

func Media.bufferStart(cursorPosition, extraProps)

A buffering flag will automatically generate buffering.heartbeat or rebuffering.heartbeat events depending on the context.

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.bufferStart(
  0,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.bufferStart(cursorPosition: Int, extraProps: [String: Any]?)

A buffering flag will automatically generate buffering.heartbeat or rebuffering.heartbeat events depending on the context.

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.bufferStart(
  cursorPosition: 0,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

playbackStart

Event name : av.start

Generate a playback start event (first media frame). This allows the automatic av.heartbeat events (designed to accurately track the playback time) to be sent. These av.heartbeat events follow the media instance configuration.

Javascript

playbackStart(cursorPosition[, callback, extraProps])

Parameter	Type	Description
cursorPosition	number	Current cursor position (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.playbackStart(
  0,
  function() { console.log("Event av.start generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
properties vararg (optional)	Property	Custom properties

myMedia.playbackStart(
  0,
  Property(...),
  Property(...)
)

Android

func Media.playbackStart(cursorPosition, extraProps)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.playbackStart(
  0,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.playbackStart(cursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.playbackStart(
  cursorPosition: 0,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

playbackPaused

Event name : av.pause

Generate a pause event.

Javascript

playbackPaused(cursorPosition[, callback, extraProps])

Parameter	Type	Description
cursorPosition	number	Current cursor position (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.playbackPaused(
  1000,
  function() { console.log("Event av.pause generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
properties vararg (optional)	Property	Custom properties

myMedia.playbackPaused(
  1000,
  Property(...),
  Property(...)
)

Android

func Media.playbackPaused(cursorPosition, extraProps)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.playbackPaused(
  1000,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.playbackPaused(cursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.playbackPaused(
  cursorPosition: 1000,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

playbackResumed

Event name : av.resume

Generate a resume event, following a pause event.

Javascript

playbackResumed(cursorPosition[, callback, extraProps])

Parameter	Type	Description
cursorPosition	number	Current cursor position (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.playbackResumed(
  1000,
  function() { console.log("Event av.resume generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
properties vararg (optional)	Property	Custom properties

myMedia.playbackResumed(
  1000,
  Property(...),
  Property(...)
)

Android

func Media.playbackResumed(cursorPosition, extraProps)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.playbackResumed(
  1000,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.playbackResumed(cursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.playbackResumed(
  cursorPosition: 1000,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

playbackStopped

Event name : av.stop

Generate a stop event. Automatically changes the av_session_id.

Javascript

playbackStopped(cursorPosition[, callback, extraProps])

Parameter	Type	Description
cursorPosition	number	Current cursor position (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.playbackStopped(
  1000,
  function() { console.log("Event av.stop generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
properties vararg (optional)	Property	Custom properties

myMedia.playbackStopped(
  1000,
  Property(...),
  Property(...)
)

Android

func Media.playbackStopped(cursorPosition, extraProps)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.playbackStopped(
  1000,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.playbackStopped(cursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
cursorPosition	Int	Current cursor position (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.playbackStopped(
  cursorPosition: 1000,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

seek

Event name : av.forward ou av.backward

Generate a seek event. av.backward is sent whenever the user goes back to an already seen cursorPosition. av.forward whenever the user goes past the current cursorPosition.

Javascript

seek(oldCursorPosition, newCursorPosition[, callback, extraProps])

Parameter	Type	Description
oldCursorPosition	number	Cursor position before seeking (ms)
newCursorPosition	number	Cursor position after seeking (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.seek(
  1000,
  2000,
  function() { console.log("Event av.forward generated"); },
  { customProp: "customValue" }
);

myMedia.seek(
  2000,
  1000,
  function() { console.log("Event av.backward generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
properties vararg (optional)	Property	Custom properties

myMedia.seek(
  1000,
  2000,
  Property(...),
  Property(...)
)

myMedia.seek(
  2000,
  1000,
  Property(...),
  Property(...)
)

Android

func Media.seek(oldCursorPosition, newCursorPosition, extraProps)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.seek(
  1000,
  2000,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

myMedia.seek(
  2000,
  1000,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.seek(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.seek(
  oldCursorPosition: 1000,
  newCursorPosition: 2000,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

myMedia.seek(
  oldCursorPosition: 2000,
  newCursorPosition: 1000,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

Contextual events

The following list of events is not taken into account in the calculation of media consumption times. They are one-time contextual events.

Playback speed

When changing the playback speed you have to use the dedicated method specifying the new speed factor as a decimal number.

Javascript

Method:

setPlaybackSpeed(playbackSpeed)

Declare a change in playback speed.

Parameter	Type	Description
playbackSpeed	number	Playback speed factor

Example

myMedia.setPlaybackSpeed(2); // Media playback speed increased by a factor of two

Android (3.3.0+)

Parameter	Type	Description
playbackSpeed	Double	Playback speed factor

myMedia.playbackSpeed = 2.0

Android

func Media.setPlaybackSpeed(playbackSpeed)

Declare a change in playback speed.

Parameter	Type	Description
playbackSpeed	Double	Playback speed factor

Example

myMedia.setPlaybackSpeed(2.0); // Media playback speed increased by a factor of two

Apple

myMedia.playbackSpeed: Double = playbackSpeed

Declare a change in playback speed.

Parameter	Type	Description
playbackSpeed	Double	Playback speed factor

Example

myMedia.playbackSpeed = 2.0 // Media playback speed increased by a factor of two

The new playback speed factor will be taken into account when calculating the cursor positions of automated heartbeats events during playback. If necessary, you can tag the event associated with this speed change by using the speed() method.

adClick

Event name : av.ad.click

Generate an ad click event.

Javascript

adClick([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.adClick(
  function() { console.log("Event av.ad.click generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.adClick(
  Property(...),
  Property(...)
)

Android

func Media.adClick(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.adClick(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.adClick(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.adClick(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

adSkip

Event name : av.ad.skip

Generate an ad skip event.

Javascript

adSkip([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.adSkip(
  function() { console.log("Event av.ad.skip generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.adSkip(
  Property(...),
  Property(...)
)

Android

func Media.adSkip(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.adSkip(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.adSkip(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.adSkip(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

close

Event name : av.close

Measure a closing.

Javascript

close([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.close(
  function() { console.log("Event av.close generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.close(
  Property(...),
  Property(...)
)

Android

func Media.close(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.close(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.close(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.close(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

display

Event name : av.display

Measure a display.

Javascript

display([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.display(
  function() { console.log("Event av.display generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.display(
  1000,
  Property(...),
  Property(...)
)

Android

func Media.display(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.display(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.display(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.display(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

error

Event name : av.error

Measure an error preventing playback.

Javascript

error(message[, callback, extraProps])

Parameter	Type	Description
message	string	Error message
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.error(
  "Error loading video",
  function() { console.log("Event av.error generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
message	String	Error message
properties vararg (optional)	Property	Custom properties

myMedia.playbackStopped(
  "Error loading video",
  Property(...),
  Property(...)
)

Android

func Media.error(message, extraProps)

Parameter	Type	Description
message	String	Error message
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.error(
  "Error loading video",
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.error(message: String, extraProps: [String: Any]?)

Parameter	Type	Description
message	String	Error message
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.error(
  "Error loading video",
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

fullscreenOff

Event name : av.fullscreen.off

Measure full screen deactivation.

Javascript

fullscreenOff([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.fullscreenOff(
  function() { console.log("Event av.fullscreen.off generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.fullscreenOff(
  Property(...),
  Property(...)
)

Android

func Media.fullscreenOff(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.fullscreenOff(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.fullscreenOff(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.fullscreenOff(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

fullscreenOn

Event name : av.fullscreen.on

Measure full screen activation.

Javascript

fullscreenOn([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.fullscreenOn(
  function() { console.log("Event av.fullscreen.on generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.fullscreenOn(
  1000,
  Property(...),
  Property(...)
)

Android

func Media.fullscreenOn(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.fullscreenOn(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.fullscreenOn(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.fullscreenOn(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

quality

Event name : av.quality

Measure a quality change.

Javascript

quality([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.quality(
  function() { console.log("Event av.quality generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.quality(
  Property(...),
  Property(...)
)

Android

func Media.quality(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.quality(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.quality(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.quality(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

share

Event name : av.share

Measure a sharing.

Javascript

share([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.share(
  function() { console.log("Event av.share generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.share(
  Property(...),
  Property(...)
)

Android

func Media.share(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.share(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.share(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.share(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

speed

Event name : av.speed

Measure a speed change.

Javascript

speed([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.speed(
  function() { console.log("Event av.speed generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.speed(
  Property(...),
  Property(...)
)

Android

func Media.speed(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.speed(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.speed(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.speed(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

subtitleOff

Event name : av.subtitle.off

Measure subtitles deactivation

Javascript

subtitleOff([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.subtitleOff(
  function() { console.log("Event av.subtitle.off generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.subtitleOff(
  Property(...),
  Property(...)
)

Android

func Media.subtitleOff(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.subtitleOff(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.subtitleOff(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.subtitleOff(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

subtitleOn

Event name : av.subtitle.on

Measure subtitles activation.

Javascript

subtitleOn([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.subtitleOn(
  function() { console.log("Event av.subtitle.on generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.subtitleOn(
  Property(...),
  Property(...)
)

Android

func Media.subtitleOn(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.subtitleOn(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.subtitleOn(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.subtitleOn(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

volume

Event name : av.volume

Measure sound volume change.

Javascript

volume([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.volume(
  function() { console.log("Event av.volume generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.volume(
  Property(...),
  Property(...)
)

Android

func Media.volume(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.volume(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.volume(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.volume(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

Technical events

The following events are automatically generated by the Tracker. You can, however, call up the associated public marking methods if you need spot marking. Should the implementation be done without the SDK (server-side), you would have to generate the following events manually.

bufferHeartbeat

Event name : av.buffer.heartbeat

Generate a buffering heartbeat before the playback starts event.

Javascript

bufferHeartbeat([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.bufferHeartbeat(
  function() { console.log("Event av.buffer.heartbeat generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.bufferHeartbeat(
  Property(...),
  Property(...)
)

Android

func Media.bufferHeartbeat(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.bufferHeartbeat(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.bufferHeartbeat(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.bufferHeartbeat(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

heartbeat

Event name: av.heartbeat

Generate an heartbeat event. Event used to accurately track the playback time preferably sent at regular intervals when the content is actively playing.

Javascript

heartbeat([cursorPosition, callback, extraProps])

Parameter	Type	Description
cursorPosition (optional)	number	Current cursor position (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.heartbeat(
  45,
  function() { console.log("Event av.heartbeat generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.heartbeat(
  Property(...),
  Property(...)
)

Android

func Media.heartbeat(cursorPosition, extraProps)

Parameter	Type	Description
cursorPosition (optional)	number	Current cursor position (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.heartbeat(
  45,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.heartbeat(cursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
cursorPosition (optional)	number	Current cursor position (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.heartbeat(
  cursorPosition: 45,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

note

The cursor position is not mandatory for tagging a heartbeat event. Without any value, it will be automatically calculated according to the context (playback speed factor, cursor position of the previous event).

rebufferHeartbeat

Event name : av.rebuffer.heartbeat

Generate a buffering heartbeat after the playback starts event.

Javascript

rebufferHeartbeat([callback, extraProps])

Parameter	Type	Description
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.rebufferHeartbeat(
  function() { console.log("Event av.rebuffer.heartbeat generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
properties vararg (optional)	Property	Custom properties

myMedia.rebufferHeartbeat(
  Property(...),
  Property(...)
)

Android

func Media.rebufferHeartbeat(extraProps)

Parameter	Type	Description
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.rebufferHeartbeat(
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.rebufferHeartbeat(extraProps: [String: Any]?)

Parameter	Type	Description
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.rebufferHeartbeat(
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

seekStart

Event name : av.seek.start

Generate a beginning of seeking event.

Javascript

seekStart(oldCursorPosition, [callback, extraProps])

note

This event is automatically raised when calling the seek(), seekBackward() or seekForward() methods.

Parameter	Type	Description
oldCursorPosition	number	Cursor position before seeking (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.seekStart(
  1000,
  function() { console.log("Event av.seek.start generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
oldCursorPosition	Int	Current cursor position (ms)
properties vararg (optional)	Property	Custom properties

myMedia.seekStart(
  1000,
  Property(...),
  Property(...)
)

Android

func Media.seekStart(oldCursorPosition, extraProps)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.seekStart(
  1000,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.seekStart(oldCursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.seekStart(
  oldCursorPosition: 1000,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

seekBackward

Event name : av.backward

Generate a backward seeking event.

Javascript

seekBackward(oldCursorPosition, newCursorPosition, [callback, extraProps])

Parameter	Type	Description
oldCursorPosition	number	Cursor position before seeking (ms)
newCursorPosition	number	Cursor position after seeking (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.seekBackward(
  2000,
  1000,
  function() { console.log("Event av.backward generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
properties vararg (optional)	Property	Custom properties

myMedia.seekBackward(
  2000,
  1000,
  Property(...),
  Property(...)
)

Android

func Media.seekBackward(oldCursorPosition, newCursorPosition, extraProps)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.seekBackward(
  2000,
  1000,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.seekBackward(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.seekBackward(
  oldCursorPosition: 2000,
  newCursorPosition: 1000,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

seekForward

Event name : av.forward

Generate a forward seeking event.

Javascript

seekForward(oldCursorPosition, newCursorPosition, [callback, extraProps])

Parameter	Type	Description
oldCursorPosition	number	Cursor position before seeking (ms)
newCursorPosition	number	Cursor position after seeking (ms)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

myMedia.seekForward(
  1000,
  2000,
  function() { console.log("Event av.forward generated"); },
  { customProp: "customValue" }
);

Android (3.3.0+)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
properties vararg (optional)	Property	Custom properties

myMedia.seekForward(
  1000,
  2000,
  Property(...),
  Property(...)
)

Android

func Media.seekForward(oldCursorPosition, newCursorPosition, extraProps)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
extraProps (optional)	Map<String, Object>?	Custom properties

Example

myMedia.seekForward(
  1000,
  2000,
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

Apple

myMedia.seekForward(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)

Parameter	Type	Description
oldCursorPosition	Int	Cursor position before seeking (ms)
newCursorPosition	Int	Cursor position after seeking (ms)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.seekForward(
  oldCursorPosition: 1000,
  newCursorPosition: 2000,
  extraProps: [
    "av_content": "Content title",
    ...
  ]
)

Complete tagging example

Javascript

var myMedia = new pa.avInsights.Media(5, 5); // Set heartbeats value (5 seconds)

var properties = {
  av_content_id: 'fge234', //mandatory
  av_content: 'myContent',
  av_content_type: 'Video',
  av_content_duration: 10000,
  av_content_genre: ['entertainment'],
  av_content_version: 'short',
  av_player: 'HTML5_V123',
  av_player_version: '1b',
  av_player_position: 'top',
  av_broadcasting_type: 'On Demand',
  av_publication_date: 1562055880,
  av_show: 'The gist of the game',
  av_show_season: 'Season 1',
  av_episode_id: '3134',
  av_channel: 'INFO',
  av_author: 'Piano',
  av_broadcaster: 'Direction 123',
  av_language: 'EN',
  av_subtitles: 'FR',
  av_launch_reason: 'Auto'
};

// Set media properties
myMedia.setProps(properties);

// Play attempt (cursor position 0 second)
myMedia.play(0);

// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(0);

// Playback start (cursor position 0 second)
myMedia.playbackStart(0);

// Buffering after 5 seconds of playback
myMedia.bufferStart(5000);

// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(5000, 3000);

// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(3000);

// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(9000);

// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(9000);

// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(15000);

Android (3.3.0+)

val heartbeat = SparseLongArray()
  // first minute will be 5sec delay
  heartbeat.put(0, 5)
  // starting from minute 1, 10sec
  heartbeat.put(1, 10)
  // and after the 5th minute, the delay will be 60sec
  heartbeat.put(5, 60)
  val bufferHeartbeat = SparseLongArray()
  bufferHeartbeat.put(0, 5)

val myMedia = PianoAnalytics.getInstance()
  .mediaHelper("fge234")
  .setHeartbeat(heartbeat)
  .setBufferHeartbeat(bufferHeartbeat)

val properties = arrayOf(
  Property(PropertyName("av_content"), "myContent"),
  Property(PropertyName("av_content_type"), "Video"),
  Property(PropertyName("av_content_duration"), 10000),
  Property(PropertyName("av_content_genre"), arrayOf("entertainment")),
  Property(PropertyName("av_content_version"), "short"),
  Property(PropertyName("av_player"), "HTML5_V123"),
  Property(PropertyName("av_player_version"), "1b"),
  Property(PropertyName("av_player_position"), "top"),
  Property(PropertyName("av_broadcasting_type"), "On Demand"),
  Property(PropertyName("av_publication_date"), 1562055880),
  Property(PropertyName("av_show"), "The gist of the game"),
  Property(PropertyName("av_show_season"), "Season 1"),
  Property(PropertyName("av_episode_id"), "3134"),
  Property(PropertyName("av_channel"), "INFO"),
  Property(PropertyName("av_author"), "Piano"),
  Property(PropertyName("av_broadcaster"), "Direction 123"),
  Property(PropertyName("av_language"), "EN"),
  Property(PropertyName("av_subtitles"), "FR"),
  Property(PropertyName("av_launch_reason"), "Auto"),
)

myMedia.setExtraProps(*properties)

// Play attempt (cursor position 0 second)
myMedia.play(0, *properties)

// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(0, *properties)

// Playback start (cursor position 0 second)
myMedia.playbackStart(0, *properties)

// Buffering after 5 seconds of playback
myMedia.bufferStart(5000, *properties)

// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(5000, 3000, *properties)

// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(3000, *properties)

// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(9000, *properties)

// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(9000, *properties)

// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(15000, *properties)

Android

Media myMedia = new Media(pa);

HashMap<String, Object> properties = new HashMap<String, Object>() {{
  put("av_content_id", "fge234"); //mandatory
  put("av_content", "myContent");
  put("av_content_type", "Video");
  put("av_content_duration", 10000);
  put("av_content_genre", new String[]{"entertainment"});
  put("av_content_version", "short");
  put("av_player", "HTML5_V123");
  put("av_player_version", "1b");
  put("av_player_position", "top");
  put("av_broadcasting_type", "On Demand");
  put("av_publication_date", 1562055880);
  put("av_show", "The gist of the game");
  put("av_show_season", "Season 1");
  put("av_episode_id", "3134");
  put("av_channel", "INFO");
  put("av_author", "Piano");
  put("av_broadcaster", "Direction 123");
  put("av_language", "EN");
  put("av_subtitles", "FR");
  put("av_launch_reason", "Auto");
}};

// Play attempt (cursor position 0 second)
myMedia.play(0, properties);

// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(0, properties);

// Playback start (cursor position 0 second)
myMedia.playbackStart(0, properties);

// Buffering after 5 seconds of playback
myMedia.bufferStart(5000, properties);

// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(5000, 3000, properties);

// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(3000, properties);

// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(9000, properties);

// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(9000, properties);

// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(15000, properties);

Apple

var myMedia = AVMedia(pa: pa)

myMedia.setHeartbeat(heartbeat: [
    0: 5,
    1: 10,
    5: 60
])

myMedia.setBufferHeartbeat(bufferingHeartbeat: [
    0: 5,
    1: 10,
    5: 60
])

var properties = [
  "av_content_id": "fge234", //mandatory
  "av_content": "myContent",
  "av_content_type": "Video",
  "av_content_duration": 10000,
  "av_content_genre": ["entertainment"],
  "av_content_version": "short",
  "av_player": "HTML5_V123",
  "av_player_version": "1b",
  "av_player_position": "top",
  "av_broadcasting_type": "On Demand",
  "av_publication_date": 1562055880,
  "av_show": "The gist of the game",
  "av_show_season": "Season 1",
  "av_episode_id": "3134",
  "av_channel": "INFO",
  "av_author": "Piano",
  "av_broadcaster": "Direction 123",
  "av_language": "EN",
  "av_subtitles": "FR",
  "av_launch_reason": "Auto"
]

myMedia.setExtraProps(properties)

// Play attempt (cursor position 0 second)
myMedia.play(cursorPosition: 0, extraProps: properties)

// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(cursorPosition: 0, extraProps: properties)

// Playback start (cursor position 0 second)
myMedia.playbackStart(cursorPosition: 0, extraProps: properties)

// Buffering after 5 seconds of playback
myMedia.bufferStart(cursorPosition: 5000, extraProps: properties)

// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(oldCursorPosition: 5000, newCursorPosition: 3000, extraProps: properties)

// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(cursorPosition: 3000, extraProps: properties)

// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(cursorPosition: 9000, extraProps: properties)

// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(cursorPosition: 9000, extraProps: properties)

// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(cursorPosition: 15000, extraProps: properties)

Annexes

Media sequence example

This represents the ideal sequence for a media playback. As this does not include ads, there will be adjustments needed to cover this scenario.

Seek sequence example

Media properties list

note

Please note that the Piano Analytics SDK automatically adds properties to your AV events. You will need to exempt these properties too for proper AV tracking.

Property	Description	Type	Mandatory	Example
av_content_id	Content ID	string	Yes	'bc35'
av_session_id	Session ID (generated by the SDK)	uuid*	Yes	'799d9f3b-7307-5113-a260-2e1371e35fe6'
av_duration	Inter-event duration (in milliseconds) (generated by the SDK)	int		5000
av_position	Cursor position (in milliseconds) (generated by the SDK for heartbeats)	int		5000
av_previous_event	Previous event (generated by the SDK)	string		'av.start'
av_previous_position	Previous cursor position (in milliseconds) (generated by the SDK)	int		2000
av_content	Content Label	string		'Broadchurch 3.5'
av_content_type	Content Type	string		'TV Show'
av_content_duration	Content Duration (in milliseconds)	int		2760000
av_content_linked	Linked Content Label	string		'myLinkedContent'
av_publication_date	Publication Date (timestamp)	date		1501065673
av_content_genre	Content genre(s)	array of string		["Crime","Drama","Mystery"]
av_show	Show Label	string		'Broadchurch'
av_show_season	Show Season Label	string		'3'
av_episode_id	Episode ID	string		'5'
av_episode	Episode Label	string		'Episode #3.5'
av_channel	Channel Label	string		'ITV'
av_author	Author Name	string		'Chris Chibnall'
av_content_version	Content Version (full length, …)	string		'Full
av_content_duration_range	Duration range	string		'0-10'
av_broadcasting_type	Broadcasting Type	string		'Live'
av_broadcaster	Broadcaster Name	string		'ITV'
av_ad_type	Ad Type	string		'Mid-roll'
av_player	Player Label	string		'Main'
av_player_version	Player Version	string		'1.55'
av_player_position	Player Position	string		'Homepage'
av_auto_mode	Auto play mode	boolean		true
av_language	Media language	string		'fr'
av_subtitles	Subtitles	string		'en'
av_launch_reason	Launch reason	string		'auto'

List of available options

Option	Description
av_position	Current cursor position (in milliseconds)
av_previous_position	Previous cursor position (in milliseconds)
av_player_error	Error preventing playback

List of standard events

Event	Type
av.play	Manual
av.buffer.start	Manual
av.buffer.heartbeat	Automatic
av.start	Manual
av.heartbeat	Automatic
av.pause	Manual
av.rebuffer.start	Manual
av.rebuffer.heartbeat	Automatic
av.resume	Manual
av.stop	Manual
av.seek.start	Manual
av.forward	Manual
av.backward	Manual
av.ad.click	Manual
av.ad.skip	Manual
av.error	Manual
av.display	Manual
av.close	Manual
av.volume	Manual
av.subtitle.on	Manual
av.subtitle.off	Manual
av.fullscreen.on	Manual
av.fullscreen.off	Manual
av.quality	Manual
av.speed	Manual
av.share	Manual

Custom events tracking method 

track

The AV Insights track() method allows standard or custom events to be tracked.

Event name : event value

Track standard or custom actions.

Javascript

track(event, [options, callback, extraProps])

Parameter	Type	Description
event	string	Event to be generated (see list of standard events at the bottom of the page)
options (optional)	Object	Options depending on the event (see list of available options at the bottom of the page)
callback (optional)	function	Callback function to execute after hit sent
extraProps (optional)	Object	Custom properties

Example

var myMedia = new pa.avInsights.Media(5, 5);

// Buffer tagging
myMedia.track('av.buffer.start', {av_position: 0}, function() {console.log('Event "av.buffer.start" generated');}, null);

// Re-buffer tagging
myMedia.track('av.rebuffer.start', {av_position: 10}, function() {console.log('Event "av.rebuffer.start" generated');}, null);

// Play tagging
myMedia.track('av.play', {av_position: 0}, function() {console.log('Event "av.play" generated');}, null);

// Playback start tagging
myMedia.track('av.start', {av_position: 0}, function() {console.log('Event "av.start" generated');}, null);

// Playback pause tagging
myMedia.track('av.pause', {av_position: 10}, function() {console.log('Event "av.pause" generated');}, null);

// Playback resume tagging
myMedia.track('av.resume', {av_position: 10}, function() {console.log('Event "av.resume" generated');}, null);

// Playback stop tagging
myMedia.track('av.stop', {av_position: 20}, function() {console.log('Event "av.stop" generated');}, null);

// Seek forward tagging
myMedia.track('av.forward', {av_previous_position: 10, av_position: 20}, function() {console.log('Event "av.forward" generated');}, null);

// Seek backward tagging
myMedia.track('av.backward', {av_previous_position: 20, av_position: 10}, function() {console.log('Event "av.backward" generated');}, null);

// Ad click tagging
myMedia.track('av.ad.click', null, function() {console.log('Event "av.ad.click" generated');}, null);

// Ad skip tagging
myMedia.track('av.ad.skip', null, function() {console.log('Event "av.ad.skip" generated');}, null);

// Error tagging
myMedia.track('av.error', {av_player_error: "Player error"}, function() {console.log('Event "av.error" generated');}, null);

// Display tagging
myMedia.track('av.display', null, function() {console.log('Event "av.display" generated');}, null);

// Close tagging
myMedia.track('av.close', null, function() {console.log('Event "av.close" generated');}, null);

// Volume tagging
myMedia.track('av.volume', null, function() {console.log('Event "av.volume" generated');}, null);

// Subtitle on tagging
myMedia.track('av.subtitle.on', null, function() {console.log('Event "av.subtitle.on" generated');}, null);

// Subtitle off tagging
myMedia.track('av.subtitle.off', null, function() {console.log('Event "av.subtitle.off" generated');}, null);

// Full screen on tagging
myMedia.track('av.fullscreen.on', null, function() {console.log('Event "av.fullscreen.on" generated');}, null);

// Full screen off tagging
myMedia.track('av.fullscreen.off', null, function() {console.log('Event "av.fullscreen.off" generated');}, null);

// Quality tagging
myMedia.track('av.quality', null, function() {console.log('Event "av.quality" generated');}, null);

// Speed tagging
myMedia.track('av.speed', null, function() {console.log('Event "av.speed" generated');}, null);

// Share tagging
myMedia.track('av.share', null, function() {console.log('Event "av.share" generated');}, null);

// Custom tagging
myMedia.track('custom', null, null, {'customParam': 'customValue'});

Android

func Media.track(event, options, extraProps)

Parameter	Type	Description
event	String	Event to be generated (see list of standard events at the bottom of the page)
options	Map<String, Object>?	Options depending on the event (see list of available options at the bottom of the page)
extraProps	Map<String, Object>?	Custom properties

Example

myMedia.setHeartbeat(new SparseIntArray()
  .append(0, 5)
  .append(1, 10)
  .append(5, 60)
);

myMedia.setBufferHeartbeat(new SparseIntArray()
  .append(0, 5)
  .append(1, 10)
  .append(5, 60)
);

// Buffer tagging
myMedia.track(
  "av.buffer.start",
  new HashMap<String, Object>() {{
    put("av_position", 0);
  }},
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

// Re-buffer tagging
myMedia.track(
  "av.rebuffer.start",
  new HashMap<String, Object>() {{
    put("av_position", 10);
  }},
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

// Play tagging
myMedia.track(
  "av.play",
  new HashMap<String, Object>() {{
    put("av_position", 0);
  }},
  new HashMap<String, Object>() {{
    put("av_content", "Content title");
    ...
  }}
);

...

// Custom tagging
myMedia.track(event: "av.custom", options: nil, extraProps: ["av_content": "Content title", ...]);

Apple

myMedia.track(event: String, options: [String: Any]?, extraProps: [String: Any]?)

Parameter	Type	Description
event	String	Event to be generated (see list of standard events at the bottom of the page)
options (optional)	[String: Any]?	Options depending on the event (see list of available options at the bottom of the page)
extraProps (optional)	[String: Any]?	Custom properties

Example

myMedia.setHeartbeat(heartbeat: [
    0: 5,
    1: 10,
    5: 60
])

myMedia.setBufferHeartbeat(bufferHeartbeat: [
    0: 5,
    1: 10,
    5: 60
])

// Buffer tagging
myMedia.track(event: "av.buffer.start", options: ["av_position": 0], extraProps: ["av_content": "Content title", ...])

// Re-buffer tagging
myMedia.track(event: "av.rebuffer.start", options: ["av_position": 10], extraProps: ["av_content": "Content title", ...])

// Play tagging
myMedia.track(event: "av.play", options: ["av_position": 0], extraProps: ["av_content": "Content title", ...])

...

// Custom tagging
myMedia.track(event: "av.custom", options: nil, extraProps: ["av_content": "Content title", ...])