Integrating with Player Events

Introduction

The SundaySky player includes different events that may be tracked via web analytics solutions or used to alter the behavior of the browser in some way.  Events occur when the player loads, as the video plays (started, progress, completion), when the user interacts with buttons and many other times. To react to an event, you first listen for it to come from the player and supply a callback function which will be called by the browser when the event occurs.

 Here’s a simple example:

<script>
var myPlayer = document.getElementById('sskyplayer');
myPlayer.addEventListener('ctaClicked', function(event) {
console.log('Viewer clicked the CTA: ' + event.detail.name);
});
</script>

The player element is stored in a variable myPlayer and the addEventListener method is called on it. The first argument is a string - the name of the event to listen for. Here it’s ctaClicked - that’s a click of the mouse or a tap of the finger on a video call-to-action button. The second is the callback function - here it writes a log to the console about the event, including the button name.

Please note - the sample above gets the player element using the id sskyplayer which is defined when creating the player element. It is the same id value used in SundaySky's player integration code snippets, please modify the code accordingly if a different id was used.

Here’s an example of adding the event listeners to the player initialization code:

<script>

function createPlayer() {
var sskyplayer = document.createElement('sundaysky-video');
sskyplayer.setAttribute( 'id' , 'sskyplayer' );
sskyplayer.setAttribute( 'analytics-token' , 'accountID' );
sskyplayer.setAttribute('endpoint-url','https://accountID.web.sundaysky.com/create_video_session');
sskyplayer.setAttribute('session-parameters','{ "id" : "110006" }');
sskyplayer.setAttribute( 'poster','https://play.sundaysky.com/resources/invitation.png' );
sskyplayer.addEventListener('ctaClicked', function(event) {
console.log('Viewer clicked the CTA: ' + event.detail.name);
});
document.getElementById('sskydiv').appendChild(sskyplayer);
}
createPlayer();

</script>

Player Events

The list below contains commonly used events with a description of when they fire and additional event properties that may be available. 

 Event  Event Trigger
 load Emitted when all software components finished loading and the player component is initialized.
 playRequested

Emitted when the user clicks "play" for the first time. Will not be fired on videos that are set to autoplay.


Event properties:

  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
 playStart

Emitted when the video starts playing for the first time. Will not be triggered more than once per session.


Event properties:

  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
 progress

Emitted every 1% of the video duration when the video is in "playing" state, including 0% and 100%.


Event properties:

  • "detail.position" - number between 0 and 1 representing the playback position relative to the video duration e.g. 0.04 represents 4% progress.
  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
 scene

Emitted every time the video starts playing a new scene in the video.


Event properties:

  • "detail.position" - number between 0 and 1 representing the playback position relative to the video duration.
  • "detail.scene" - name of the scene
  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
 userAction

Emitted every time a user interaction (button or on-screen control click/tap/press) occurs.


Event properties:

  • "detail.action" - name of the user action performed; actions are: "play", "pause", "volumeChange" (if moved the volume bar), "mute", "seek", "toggleCC", "toggleFullScreen", "toggleTranscript", "downloadTranscript".
  • "detail.value" - value of the changed property (number in case of volume or progress, boolean in case of toggle button clicks).
  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
 survey

Emitted if a <sundaysky-survey> component is connected and the survey was presented for the first time.


Event properties:

  • "detail.target" - name of the <sundaysky-survey> component.
  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
 surveySubmit

Emitted if a <sundaysky-survey> component is connected and the survey was submitted.


Event properties:

  • "detail.target" - name of the <sundaysky-survey> component.
  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
 ctaShow  

Emitted when a CTA button should be displayed.

Event properties:

  • "detail.ids":  array of CTA buttons IDs
  • "detail.ctaSpec": array of CTA buttons to be displayed. For each button that should be displayed, the array contains an object with the following fields:

    • "detail.ctaSpec[0].id"
    • "detail.ctaSpec[0].label"
    • "detail.ctaSpec[0].action"
    • "detail.ctaSpec[0].actionRef"
    • "detail.ctaSpec[0].default"
    • "detail.ctaSpec[0].startTime": CTA's display time, in video time
    • "detail.ctaSpec[0].endTime": CTA's hide time, in video time
    • "detail.ctaSpec[0].hotspot"
      • "detail.ctaSpec[0].hotspot.width"
      • "detail.ctaSpec[0].hotspot.height"
      • "detail.ctaSpec[0].hotspot.x"
      • "detail.ctaSpec[0].hotspot.y"
    • "detail.ctaSpec[0].name": the scene name in which the CTA was configured to display (current scene)
    • "detail.ctaSpec[0].url"
    • "detail.ctaSpec[0].sceneName"
    • "detail.ctaSpec[0].shouldHighlight"
    • "detail.ctaSpec[0].type": specifies the CTA type, one of the following:
      • "URL"
      • "video"
      • "replay"
      • "share"
      • "javascript" (legacy)
      • "url" (legacy)
    • "detail.ctaSpec[0].url"
    • "detail.ctaSpec[0].videoSegmentId"
  • "detail.videoUrl": URL of the video media
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session
  • "detail.scene": the scene name in which the CTA was displayed (current scene
 ctaHide  

Emitted when a CTA menu should be hidden.


Event properties:

  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.

Note: this event is fired for each CTA separately. the structure remains the same to allow for backwards compatibility for legacy metadata structure, while new metadata structure allows configuring individual exact times for each CTA button to show. this event reflects the actual moment when an individual CTA is shown

 ctaClicked  Emitted when a CTA menu option was clicked. The "target" property of the Event will contain the instance of the clicked button element.

Event properties:

  • "detail.url" - URL associated with the clicked action.
  • "detail.name" - name of clicked action.
  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
"preventDefault()": if called, the default action that should result from the click (opening of a URL in a new browser tab) will not be invoked. Use the ctaClicked event and this method to implement any action that is not opening of a URL in a new window.
 error

Emitted whenever the player encounters an error.


Event properties:

  • "detail.target" - mostly, this is the player element which emitted the error, but it may be a connected element such as a <sundaysky-survey>.
  • "detail.errorCode" - integer identifying the error, or 0 if unknown
  • "detail.originalError" - (optional, opaque) if the first error is an error of a 3rd-party subcomponent, this property may contain the error object originally encountered, which may be an exception, another "error" event, or an error code.
  • "detail.errorMessage": message that is displayed to the user.
  • "detail.videoUrl": URL of the video media.
  • "detail.videoFormat": mime-type of the video stream
  • "detail.sessionId": a unique token identifying the current session.
 Time to First Frame  

Emitted when the video starts playing for the first time


Event properties:

  • "detail.value" - the actual time to first frame in milliseconds.
 Video Played

 

Emitted when the video starts playing for the first time

Event properties:

  • "detail.value" - the video duration
 ended Emitted whenever the video ends
 transcript

Emitted when the transcript data is made available (typically when the video starts playing).


Event properties:

  • "detail.transcript": URL of the transcript.
  • "detail.descriptivetranscript" : URL of the descriptive-transcript
 transcriptClicked 

Emitted when a Transcript control-bar button was clicked. The "target" property of the Event will contain the instance of the transcript element.

Event properties:

  • "detail.url" - URL of the transcript data.
  • "preventDefault()": if called, the default action that should result from the click (opening of a transcriptURL in a new browser tab) will not be invoked. Use the transcriptClicked event and this method to implement any action that is not the opening of the transcript in a new tab.

 

Code Samples

  • Override the default CTA URL with a custom one:
<script>

var myPlayer = document.getElementById('sskyplayer');
myPlayer.addEventListener('ctaClicked', function(event) {
event.preventDefault();
if (event.detail.label=="<CTA name to override>") 
{
window.open(“<URL To Open>”);
}
});

</script>
  • Send video viewing quartile events to a 3rd party web analytics system:
<script>

var myPlayer = document.getElementById('sskyplayer');
myPlayer.addEventListener('progress', function(event) {
if(event.detail.position=='0.25' || event.detail.position=='0.5' || event.detail.position=='0.75') { 
SendEventToWebAnalytics(event.detail.position); 
}
});

</script>
  • Make an on-page CTA visible once the video CTA appears:
<script>
var myPlayer = document.getElementById('sskyplayer');
myPlayer.addEventListener('ctaShow', function(event) {
if (detail.ctaSpec[0].label=="<Your CTA Label>") 
{
document.getElementById('<Page Element To Display>').style.visibility="visible";
}
});

</script>
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.