IFRAME Annotation API

HapYak supports custom annotations via our IFRAME API.

From within the IFRAME document, include the following script

<script src="//d2qrdklrsxowl2.cloudfront.net/js/hapyak-iframe.js"></script>

Player

hapyak.context.player.play()

Play video

hapyak.context.player.pause()

Pause video

hapyak.context.paused

Get whether video is paused or not

hapyak.context.player.currentTime

Get current video time (unit: seconds)

hapyak.context.player.currentTime = seconds

Jump to video time

hapyak.context.player.duration

Get video duration (unit: seconds)

hapyak.context.player.addClass(classNames, selector)

Set CSS classes on the IFRAME annotation where:
classNames can be a single class e.g myAwesomeClass or an array or classes ['class1', 'class2']
selector (optional) is used to target an existing class, id, or DOM element on the player element and add the class(es) to that element.

For example, hapyak.context.player.addClass('myClass', '#myId div ul > li .anotherClass') would add myClass to any elements matching #myId div ul > li .anotherClass.

hapyak.context.player.removeClass(classNames, selector)

Remove CSS classes on the IFRAME annotation where:
classNames can be a single class e.g myAwesomeClass or an array or classes ['class1', 'class2']
selector (optional) is used to target an existing class, id, or DOM element on the player element and add the class(es) to that element.

For example, hapyak.context.player.addClass('myClass', '#myId div ul > li .anotherClass') would add myClass to any elements matching #myId div ul > li .anotherClass.

hapyak.context.player.loadTrack(trackId)

Load track ID in player

Editor

hapyak.context.player.isEditMode

Returns true if the IFRAME is being displayed inside a HapYak editor

hapyak.context.isEditing

Returns true if the IFRAME is currently being edited

hapyak.context.startEditing()

Causes the HapYak edit to start editing this annotation. This method should only be called if hapyak.context.player.isEditMode is true.

hapyak.context.stopEditing()

Causes the HapYak edit to stop editing this annotation. This method should only be called if hapyak.context.player.isEditMode is true.

Annotation

hapyak.context.editButton.show()

Shows the iframe's edit button (Default behavior)

hapyak.context.editButton.hide()

Hides the iframe's edit button

hapyak.context.annotationData

Returns list of current annotation's properties

hapyak.context.width = pixels

Set IFRAME width

hapyak.context.height = pixels

Set IFRAME height

Notes

The iFrame must be visible before attempting to resize it. Here is an example of how to wait for the iframe to be shown before resizing.

hapyak.context.addEventListener('iframeshow', function () {
    hapyak.context.width = document.body.querySelector('.hapyak-iframe-container').offsetWidth;
});

Events

authchange

Emitted when the HapYak user authorization data changes

data

Emitted when the HapYak track environment data changes

loadedmetadata

Emitted when the HapYak metadata has finished loading

annotationload

Emitted when the current annotation loads. The annotation and project config are available in the data of this event.

timeupdate

Emitted when the current video time changes, and at a regular interval while the video is playing

resized

Emitted when the player is resized

play

Emitted when the video begins playing

pause

Emitted when the video becomes paused

iframeshow

Emitted when the IFRAME annotation enters its start time & is shown

iframehide

Emitted when the IFRAME annotation passes its end time & is hidden

editModeChange

Emitted when the edit mode is changed within the HapYak editor.

playerHover

Emitted when a hover event occurs over the player. This event as a returned value of true or false for hovering or not hovering respectively.

Authorization / User Data

hapyak.context.auth()

Returns current user authorization data

hapyak.context.auth(object)

Sets user authorization data

Supported keys: 'userId', 'username', 'userRole', 'userToken', 'groupId', 'groupToken', 'email'

Example

hapyak.context.auth({
    userId: 42,
    username: 'starbuck',
    userToken: '33317e9660a651183eb8b7492b55f650',
    email: 'user@domain.tld'
});

Analytics

hapyak.context.tracking.widgetAction(action, properties)

Allows partners to track custom analytics.

Example

hapyak.context.tracking.widgetAction('Follow', {
    User: 'grimlock'
});

hapyak.context.tracking.enableClickTracking()

Enable IFRAME click tracking in analytics (on by default)

hapyak.context.tracking.disableClickTracking()

Disable IFRAME click tracking in analytics

hapyak.context.tracking.widgetClick(event)

Track specific click event (passed from own listener)

Custom Data

hapyak.context.env.set(name, value, temp, scope)

Sets the value of the variable by name.

temp if true, the value will not be captured to the browser local storage. (default: false)

scope should be set to track to make the data available to other annotations. (default: annotation scope)

hapyak.context.env.get(name)

Returns the value of the variable by name.

set sets data asynchronously, so if you call get immediately after set and before the data event fires, the values may be different.

hapyak.context.env.clear(name)

Clears the value of a single variable by name.

Gates

hapyak.context.releaseGate()

If the IFRAME is set to be gated, calling this method will release that gate.

Asynchronous data access

Any variables set with env.set are changed asynchronously because they need time to be communicated to the parent window. The new value will not be returned by env.get until the next "data" event fires, which should occur within a few milliseconds.

//assume `myData` = 'foo'
console.log(hapyak.context.env.get('myData')); //foo
hapyak.context.env.set('myData', 'bar');
console.log(hapyak.context.env.get('myData')); //foo
hapyak.context.addEventListener('data', function () {
    console.log(hapyak.context.env.get('myData')); //bar
});