AMP Web - API

Document created by Herberth Alvarado Employee on Apr 4, 2016Last modified by Frank Paolino on May 22, 2017
Version 44Show Document
  • View in full screen mode

Mantainer: Maverick Chacon Garro

This document is part of Adaptive Media Player Web User Guide

  

 

Akamai Media Player Web / API Documentation

 

 

Overall

 

Akamai Media Player provides a turnkey media playback experience for online media consumption in a web page. With AMP, you can:

  • Improve video quality by enabling advanced video delivery and quality techniques, such as adaptive streaming technology, HTTP protocols, and secure streaming

  • Address desktop (Flash) and mobile (HTML5) for desktop, iOS, and Android* coverage

  • Easily integrate into your sites via parameterized configuration and JS API’s

  • Be "responsive" to layout and device

  • Report audience, content, and operational data for Akamai Media Analytics

  • Enforce content protection via Token Auth, Player Verification, Media Encryption

  • Provide readiness for current or new transcoding processes

  • Offer closed captioning

  • Enable live broadcasts and events, including "Event Management" for slate operations

  • Leverage both Akamai expertise to provide fast time-to-market

 

Akamai Media Player have a complete JavaScript API available.

 

Player Methods

 

The API methods handle directly the AMP player from the player instance, as follows example.

amp.pause(); /* the video player called player instance going to be paused */
amp.play();  /* the video is going to change the state from pause to play */

 

Method

Description

addEventListener

Add a JS event listener to respond to events (See event table in next section).

ads.setEnabledSets enabled state. [Boolean]
ads.getEnabledGets enabled state. [Boolean]
ads.getInProgressGets the in progress state. [Boolean].
ads.getPausedGets the in paused state. [Boolean].
ads.getStartedGets the in started state. [Boolean].
ads.requestAdDynamically requests an ad on player runtime.
ads.terminateAdStops the current ad.
ads.terminateAdsStops the current ad and all future ads.

captioning.getHidden

Gets current captioning state. [Boolean]

captioning.getTracks **

Returns available language tracks for a specific media object. [Object].

captioning.setHidden

Enable or disable captions from API i.e  akamai.captioning.setHidden(boolean); [Args] Boolean

captioning.selectTrackByIndex **

Set a specific caption track by index according to tracks position. [Args int]

captioning.selectTrackByLanguage

Set specific caption language by name. [Args String]

create

Create and initialize an AMP instance i.e akamai.amp.AMP.create("container", config, [opt]function(){});

destroy

Remove an specific amp instance and their components.

dispatchEvent

Dispatch a specific event from AMP instance.

end

End the current playback and show end slate. Similar to ideas of “stop.” For live media, must test with your specific media type.

enterFullScreen

Request fullscreen mode.

evaluateBinding

Evaluate metadata passed through external variables  i.e amp.evaluateBinding(“#{window.adTag}”)

exitFullScreen

Terminate fullscreen mode from API.

feed.getData

Retrieves current feed data. [Object]

feed.getURL

Returns current feed location. [String]

feed.setData

Set the current feed info from object or json; will load new media, may play if autoplay allows.

feed.setURL

Set the current feed from a specific location; will load new media, may play if autoplay allows.

getAutoplay

Returns autoplay status. [Boolean]

getConfig

Returns current AMP configuration. [Object]

getContainer/getViewComponent

Return HTML div container where AMP was initialized.

getCurrentTime

Returns current playhead position in seconds. [Number]

getDisplayState

Retrieves current playback display status. i.e "full-screen, normal, external". [String]

getDuration

Get duration of current media in seconds. [Number]

getEnded

If current media has ended. [Boolean]

getFlashVars

Return Flash player properties. [Object]

getFlashXML

Return Flash player definition, it includes view and plugins section. [Object]

getHidden

Get actual player visibility, can change using setHidden. [Boolean]

getLanguage

Get local language using in AMP. [String] 

getMedia

Returns current media object used in config override. [Object]

getMediaElement

Retrieves media element according to playback mode, for HTML it returns video tag, for Flash playback returns an iterator according to Flash application capabilities. [Function]

getMedium

Get media type.  [String]

getMuted

Get current status of mute button. [Boolean]

getParams

Returns custom params from the config, these values will be bind in order to be access by other modules. [Object]

getPaused

Returns play/pause status. [Boolean]

getPlaybackRateReturns the value representing the speed of the PlayBack Rate. 1 is the normal playback speed.

getPlayerType

Identify which playback mode is running. [String]

getQualityReturns the quality level index. [Number]
getQualityLevelsReturns an array of objects describing individual quality levels. These can be passed directly from hls.js and dash.js (hdcore - flash pending). Minimum properties required: width, height, bitrate. [Array]

getSeeking

If player is seeking or loading for media fragments will return true. [Boolean]

getSource

Return an array of media sources. [Array]

getSrc

Return current media source. [String]

getVersion

Get current instance AMP version. [String]

getVolume

Return volume level. [Number]

hidden

Player visibility property. [Boolean]

loadDefaults

Initialize the AMP elements and plugins configuration from external file. i.e akamai.amp.AMP.loadDefaults("config.json", function (){}); [Deprecated]

muteset the volume on mute.

pause

Pauses the content.

play

Starts or resumes the media content.

replay

Restarts media content.

setAutoPlay

Enable or disable auto play. [Args] Boolean

setCurrentTime

Seek to a specific timestamp. [Args] Number

setHidden

Show or hide AMP. [Args] Boolean

setLoop

Looping media content just for HTML5 mode. [Args] Boolean

setMedia

Add or set a new content to current player i.e amp.setMedia({src:'srcUrl',type:'contentType'}). [Args] Object.
To set more than one source via setMedia, it should set the whole media node as value i.e 

amp.setMedia(

{

    title: "title",

    poster: '../resources/images/hd_world.jpg',

    duration: 108,

    source: [{

        src: "http://...f4m",               //set your stream here

        type: "video/f4m"

    }, {

        src: "http://...m3u8",             //set your stream here

        type: "application/x-mpegURL"

    }]

}

).

setPlaybackRateSet the value representing the speed of the PlayBack Rate. 1 is the normal playback speed.
setPlayerPropertyIt changes or modify flash UI elements on runtime. [Args] Object
i.e amp.getMediaElement().setPlayerProperty('shareBtn',{visible:false});
setQualitySets the quality level by index. [Args] Number

setSrc

Set current media link (NOT recommended for enterprise use due to likely metadata interdependencies; use setFeed() instead).

setVolume

Indicates volume level i.e amp.setVolume(0.5); [Args] Number

unmute

Exit out from mute mode.

Note: ** Available just in HTML mode.

 

Utils

 

Utilities contained in the AMP API, you can access them using the following way. i.e

akamai.amp.utils.Utils.isIpad();

 

MethodDescrition

Utils.getDevice

Returns a String with the device that could be determined from the User Agent. At this moment these are the possible responses: "desktop", "iphone", "ipad", "android", "kindlefirehd", "kindlefire".

Utils.isIPhone

Returns a boolean depending if it is an IPhone device.

Utils.isIPad

Returns a boolean depending if it is an IPad device.

Utils.isAndroid

Returns a boolean depending if it is an Android device.

Utils.isHTMLFirst

Returns a boolean if browser has the capabilities to use HTML5 video tag instead of Flash.

Utils.isKindleFireHD

Returns a boolean depending if it is a KindleFireHD device.

Utils.isKindleFire

Returns a boolean depending if it is a KindleFire device.

Utils.isBlackBerry

Returns a boolean depending if it is a BlackBerry device.

Utils.isFirefoxOS

Returns a boolean depending if it is a FirefoxOS device.
Utils.isChromeReturns a boolean depending if it is on Chrome

Utils.isIOS

Returns a boolean depending if it is on iOS

Utils.isVolumeSettable

Return a boolean when AMP has the capabilities to set volume through the device. 

Utils.getDevice

Returns the current device where AMP is working. i.e "desktop"

Utils.getFFVersion

Returns the version of minus one (-1) in case it is not FireFox.

Utils.getSafariVersion

Returns the version of minus one (-1) in case it is not Safari.

Utils.getIEVersion

Returns the version of minus one (-1) in case it is not IE.

Utils.getPlaybackMode

Returns expected playback mode before creating AMP, "flash" or "html". Note: use this when you have "auto" mode in older AMP versions. For "html-auto" please use isHTMLFirst(). 

 

Player Events

 

The AMP single embed API Page script can listen to the AMP events with a call such as:

 

amp.addEventListener("durationchange", function(){});

 

The available events are

 

Event

Description

Payload

Valid values

activestatechange

Indicates that AMP’s active state has changed. Used primarily to manage the state of AMP’s controls.

previous: the previous active state

value: the current active state

active”: AMP’s active state is active

inactive”: AMP’s active state is inactive

canplay

Player has enough content to start playing.

 

 

canplaythrough

Player can play any section of media.

 

 

displaystatechange

Indicates that AMP’s screen display state has changed.

previous: the previous display state

value: the current display state

normal”: AMP is in normal screen mode

full-screen”: AMP is in full-screen mode

durationchange

The duration has changed.

 

 

ended

The media has ended.

 

 

error

An error has occurred even on playback.

 

 

initialized

The player can be interacted with via JS.

 

 

loadstart

Media load has begun.

 

 

loadedmeatadata

The video metadata has been loaded.

 

 

mediasequenceended

Very last content ended, media content and Postroll pod have finished.

type: "mediasequenceended

 

mediasequencestarted

Very first content start flag, It will be fired before preroll start, then started event is fired just when content starts. 

type: mediasequencestarted

 

mediaPlayerID3Updated

Flash only event, reads ID3 data from HLS using flashOSMF. 

data: Raw hexa-data.

mediaPlayeronTextData

Flash only event, reads text data injected on RTMP streams. 

data: Text data.

mediumchange

Indicates that AMP’s playback medium (audio, video) has changed.

previous: the previous playback medium

value: the current playback medium

audio”: the playback medium is audio-only

video”: the playback medium is video, which may include audio, caption and subtitle tracks

pause

When media or ad is paused.

 

 

play

When method play has being called.

 

 

playbacktargetchange

Indicates that AMP’s playback target (core playback management component) has changed. The underlying playback engine can range between Flash, HTML5, external and third party libraries. Used primarily to manage state for Chromecast-based playback workflows.

previous: the previous playback target state

value: the current playback target state

amp”: AMP itself, with or without underlying playback support, is responsible for playback

chromecast”: the Chromecast receiver is responsible for playback

playstatechange

Indicates that the media playback state has changed. These states are expressed in conjunction with the underlying playback component, which can range as described in relation to @playbacktargetchange.

previous: the previous media playback state

value: the current media playback state

ready”: indicates that AMP’s application level playback state has changed to a state of readiness. This occurs at different junctures between initialization and continuous playback scenarios

loading”: indicates that loading is underway. In the case of HTML5 based playback, this is after the loadstart event has fired, and progress events have completed

playing”: indicates that the media is currently playing

paused”: indicates that media is currently paused

seeking”: indicates that a seek is in progress

waiting”: indicates that video has stopped so that the next frame can be buttered

ended”: indicates that media has completed

error”: indicates that an error occurred in relation to media playback

playrequest

Initial play request, only occurs once. 

 

 

playing

When the player is playing.

 

 

progress

The player has buffered a section of media.

 

 

ready

When the player is ready to accept media.

 

 

seeked

The player has completed a seek operation.

 

 

seeking

The player is seeking the content.

 

 

started

Once playrequest has being fired and the contet started playing for first time.

 

 

timeupdate

The currentTime property has been updated.

 

 

timedmetadata

Reads ID3 tags from HLS streams

startTime: started time from id3 tag.

endTime: ended time.

key: ID3 info

info: id3 type.

 

volumechange

The volume has changed. this event now provides data in event.detail to get the new volume.

 

 

waiting

While player is buffering or seeking for media.

 

 

 

AIS Events

Those events should be implement using the following way, and just if you are using AIS authentication.

i.e amp.auth.addEventListener("authorizationfailed", function(){});

 

 

Event

Description

authenticated

Ok response from channel provider AIS.

authenticating

While AIS is processing auth credentials on AMP player.

authenticationcomplete

Event fired after authentication process.

authorizationfailed

When user does not have credentials for an specific channel, or bad credentials.

authenticationstarted

When auth process being started.

chooseprovider

Event fired before choose provider element appears in order to log in into.

 

Ad Events

 

Necessary events available for ads on AMP player. They can be handle by inner function or separate function. 

i.e amp.ads.addEventListener("breakend", sampleHandleFunction);

 

Event

Description

breakend

Fired when the ad content has finished by itself or skipped.

breakstart

Fired when ad container is ready to accept data.

companion

Companion ads has been detected.

containercreated

Ad overlay container has been created in the player.

durationchange

Fired when ad duration changes.

ended

The ad content has been completed.

error

Dispatched when an error occurs on ad request or during the ad.

firstquartile

Fired when the ad playhead crosses first quartile.

impression

Fired when impression url has been pinged.

loaded

When ad data is available.

midpoint

Fired when the ad playhead crosses mid point.

pause

When the pause button has been triggered.

play

Fired when the ad has been triggered.

request

Request ad has being fired.

resume

Resume ad content while is paused.

start

Player starts processing the ad response.

started

Fired when the ad starts playing.

skipped

The ad was skipped by the user.

 

 

Captioning Events

Necessary events available for captions on AMP player. They can be handle by inner function or separate function.

i.e amp.captioning.addEventListener("visibilitychange", sampleHandleFunction);

 

Name

Description

Mode

cuechange

Subtitle entry has been prompted.

HTML5

enabled

Fired when caption plugin has been registered.

HTML5

trackselected

Caption track has been selected by default.

HTML5

tracksloaded

Caption tracks has been loaded from external files.

HTML5

visibilitychange

Fired when caption has been turned on/off.

Flash/HTML5

 

Feed Events

Necessary events available for feed objects on AMP player. They can be handle by inner function or separate function.

i.e amp.feed.addEventListener("loaded", sampleHandleFunction);

 

Name

Description

Mode

changed

Fired when new feed data has been loaded.

HTML5

error

An error has occurred during feed request.

HTML5

loaded

Feed data or file has been loaded.

Flash/HTML5

request

Feed file has been requested.

HTML5

 

Other Events

Event available for other AMP features.

 

Feature

Name

Description

Mode

Share

share

When share functionality has been triggered. amp.share.addEventListener("share", function(){});

Flash/HTML5

Auto advance

startFired when countdown timer was started. amp.autoadvance.addEventListener("advance", function(){});HTML5
advanceFired when advance action was invoked automatically. Flash/HTML5
RecommendationsloadedEvent fired when this plugin has loaded media recommendations. amp.recommendations.addEventListener("loaded",function(){})Flash

Event management

eventStateChanged

Event fired when the state has been invoked. i.e  amp.eventmanagement.addEventListener("eventStateChanged",function(){})Flash/HTML5

 

 

Flash Vars

Custom flash vars, only for flash player configuration.

 

Var

Description

ads_auto_fit

Resizes advertising according to video area. [Args Boolean].

ad_server_timeout

This option will cause the player to timeout the ad request,

ad_media_server_timeout

This option will cause the IMA SDK to enforce the value as a timeout on media loading.

ad_control_enabled

Delegates ad control to AMP player. [Args Boolean].

branding_preload

To turn off Akamai logo while loading. i.e  branding_preload="none"

dvr_enabled

Legacy DVR control for flash. i.e dvr_enabled=1

fullscreen_enabled

Enables or disables fullscreen option for flash player.

hds_enable_ssl_transfer

enables or disables protocol downgrade in flash mode. [Args Boolean]. 

inpage_bitrate_index_limit

AMP can limit the maximum bitrate of the stream if it's not in fullscreen, this is helpful when high bitrate stream is available but is wasteful due to small size of the player. [Args Integer]

keyboard_control_modes

Disables flash player keyboard controls. (legacy).

mbr_start_index

Start bit rate index for HDS.  [Args Integer].

net_client_events

Enables specific events for custom metadata on RTMP or HDS. i.e net_client_events:"onTextData" enables event mediaPlayeronTextData

playback_clicktoggle_enabled

Enable playback by clicking into player area.

rewind_interval

Rewind interval in seconds.

share_mode

Share mode option for flash.

suppress_events

Suppress any flash player event. [Args String[ ]].

 

Token Authorization

 

In order to renew auth token in HTML5 playback we suggest to use authorize event and authorize public method in AMP. In a nutshell, authorize method will set and expiration time which is going to fire authorize event, here we need to request a new token. 

i.e 

 

amp.addEventListener("authorize",function(){amp.authorize()});

 

var config = {
  media: {
    src: "http://url-of-stream-without-token-appended"
  // https://your_stream.m3u8
    status: {
      // this tells the player the media needs to be authorized
      state: "blocked"
    }
  }
};

 

then you need to invoke authorize method from event listener. This is how event listener should look like. 

 

amp.addEventListener("authorize", function () {
  // do token generation / retrieval 
  amp.authorize({
    token: "TOKEN_STRING",
    // optional timestamp. If provided the player will fire the 
    // "authorize" event when expiration has occurred
    expiration: 1479319024356 
  });

 

 

This document is part of Adaptive Media Player Web User Guide

3 people found this helpful

Attachments

    Outcomes