Rich Media

Foreword

Before starting implementation of the Rich Media plugin, please make sure you have initialised the AT Internet JavaScript Tracker and selected the plugin from within the Tag Composer interface.

Principle

The JavaScript Rich Media plugin offers the measurement of media on your site.

The different media present on the page is added to the Tracker, then user interaction information is sent.

Tagging

The tracker has a richMedia.add() method enabling the definition of media tag values. The method takes, as a parameter, an object whose properties are as follows:

• mediaType: Content type (“video”, “audio”, “vpre” for pre-roll video measurement, “vmid” for mid-roll video measurement or “vpost” for post-roll video measurement); mandatory.
• playerId: Player ID (to be added when using several players).
• mediaLevel2: Level 2 site in which the content is located.
• mediaLabel: Name/label of content (use “::” if needed) or of a post-roll ad (do not use “::”); mandatory.

• refreshDuration: Refresh duration period (optional). Two kinds of configuration available:
  • int: Number of seconds between each refresh
  • Object: Allow to define evolving refresh duration regarding the playback duration (minutes time interval) – view more

  >= 5.6.0
• duration: Total duration of content in seconds (leave empty if broadcastMode is equal to “Live”). The duration must be inferior to 86400; mandatory when using a “clip”-type broadcast.
• isEmbedded: On an external website ? (true or false)
• broadcastMode: Broadcast (“live” or “clip”) mandatory when using a “live”-type broadcast
• webdomain: URL in cases of external placements (isEmbedded at true)

The tracker has a richMedia.send() method enabling measurement of actions taken on a media. The method takes, as a parameter, an object whose properties are as follows:

• action: Text ID characterising an action (“play”, “pause”, “stop”, “info” or “move”); mandatory.
• playerId: Player ID (must take the value defined above).
• mediaLabel: Name/label of content or of a post-roll ad (must take the value defined above); mandatory.

• isBuffering: Buffering in progress (true start of buffering; false end of buffering); mandatory for “info”-type actions.

The “richMedia.add()” method must be executed first before using the “richMedia.send()” method, in order for a hit to be correctly measured.

The Tracker also has methods of media removal:

• richMedia.remove(): Deletes all media declared on a player (pass the player ID as a parameter in the method).
• richMedia.removeAll(): Deletes all media declared on all players.

It is necessary to call the “richMedia.add()” method to redefine a media after deletion. The call to a removal method leads to automatic generation of “stop” hits for all affected media.

Evolving refreshDuration

Since SmartTag JS version 5.6.0, it is possible to value the refreshDuration configuration with an object, which will allow you to have an evolving refresh duration throughout the playback.

For example, in order to have the following:

1. From the beginning of the playback to the 1st minute, 5 seconds interval
2. From the 1st to the 5th minute, 15 seconds interval
3. From the 5th to the 10th minute, 30 seconds interval
4. After the 10th minute, one minute interval

You should configure like that:

tag.richMedia.add({
    ...
    refreshDuration: {
        0: 5,
        1: 15,
        5: 30,
        10: 60
    },
    ...
});

Important rules:

• The key (minute to take into account) must be an integer
• The value is in seconds, and must be an integer
• If the value is set to 0, no hit will be sent on the interval, and no on the later ones neither

Tagging examples

1. Tagging live audio play without refresh:

   var tag = new ATInternet.Tracker.Tag();
   tag.richMedia.add({
       mediaType: 'audio',
       playerId: 123,
       mediaLevel2: 'mediaLevel2',
       mediaLabel: 'mediaAudio',
       mediaTheme1: 'mediaRock',
       isEmbedded: false,
       broadcastMode: 'live'
   });
   tag.richMedia.send({
       action: 'play',
       playerId: 123,
       mediaLabel: 'mediaAudio',
       mediaTheme1: 'mediaRock',
   });

2. Tagging video play with refresh (the refresh period cannot be less than 5 seconds):

   var tag = new ATInternet.Tracker.Tag();
   tag.richMedia.add({
       mediaType: 'video',
       playerId: 456,
       mediaLevel2: 'mediaLevel2',
       mediaLabel: 'mediaVideo',
       refreshDuration: {
           0: 5,
           1: 15,
           5: 30,
           10: 60
       },
       duration: '20',
       isEmbedded: false,
       broadcastMode: 'clip'
   });
   tag.richMedia.send({
       action: 'play',
       playerId: 456,
       mediaLabel: 'mediaVideo'
   });

3. Tagging a video pause:

   tag.richMedia.send({
       action: 'pause',
       playerId: 456,
       mediaLabel: 'mediaVideo'
   });

4. Tagging a video stop:

   tag.richMedia.send({
       action: 'stop',
       playerId: 456,
       mediaLabel: 'mediaVideo'
   });

5. Tagging a video move:

   tag.richMedia.send({
       action: 'move',
       playerId: 456,
       mediaLabel: 'mediaVideo'
   });

6. Tagging buffering in progress on a video:

   tag.richMedia.send({
       action: 'info',
       playerId: 456,
       mediaLabel: 'mediaVideo',
       isBuffering: true
   });

7. Tagging the end of buffering on a video:

   tag.richMedia.send({
       action: 'info',
       playerId: 456,
       mediaLabel: 'mediaVideo',
       isBuffering: false
   });

8. Removing declared media for the player “456”:

   tag.richMedia.remove(456);

9. Removing all declared media:

   tag.richMedia.removeAll();