Advanced features

This tutorial will help customers to use advanced features by using AMP CAST player API

This tutorial shows:

Player properties and methods.
Player event targeting.
Player Transforms.

1. Player properties and methods

The Player offers public properties and methods accessible through a valid cast instance.

amp.currentTime // Playback currentTime in seconds.
> 234
amp.currentTime = 1
amp.currentTime
> 1

amp.getSystemVolume() // method to access current cast device volume

2. Player events targeting

You can subscribe to any runtime player events when using AMP Cast Receiver.

Anonymous function

amp = new akamai.amp.cast.AMP(config, event => {
    console.log("AMP CAST READY")
})

Function callback

amp = new akamai.amp.cast.AMP(config, onready)

function onready(event) {
    console.log("AMP CAST READY")
}

Subscribing other player events

amp.addEventListener('canplaythrough', event => {
    // do something...
})

Alternatively, the Player can subscribe to one specific event at once, and then it can be removed.

amp.once('seeking', event => {
    // do something once
})

Finally, If you need to unsubscribe for an event, you can use removeEventListener, which only works for subscribed events using a callback function.

amp.removeEventListener('play', onplay)

3. Transform API

The player default behavior can be modified in runtime synchronously using the available transform types.

For instance, to skip ad breaks Player, you can use the following transform.

amp.addTransform(akamai.amp.TransformType.AD_BREAK, adbreak => {
     adbreak.ignore = true // will order player to ignore the given ad clip

     return adbreak
})

Sometimes a transform callback must be called before another transform with the same type.

For instance, if you need to validate the credentials for a given video using a third-party service, then you can use akamai.amp.TransformType.LOAD_REQUEST_DATA, which will sort the interceptors for cast.framework.messages.MessageType.LOAD.

amp.addTransform(akamai.amp.TransformType.LOAD_REQUEST_DATA, {
      transform: async loadRequestData => {
        const asset = await fetchAsset(loadRequestData.credentials)
        if (asset == null) return Error('')

        return loadRequestData
      }
      priority: 101 // the higher this number is the higher the priority will be
    }

4. Enabling CORS access-control

The AMP Cast Receiver allows for advanced configuration of network requests to support various authentication and data privacy needs.

One such configuration is the ability to include the withCredentials property for XMLHttpRequest objects used in both manifest and segment requests. This can be crucial for accessing resources that require credentials, such as cookies, HTTP authentication, client-side SSL certificates, or CORS.

4.a Set withCredentials via sender custom data.

The withCredentials property can be enabled through the MediaInformation object by specifying it in the customData object. This method allows for granular control at the media item level, enabling or disabling withCredentials for individual media items based on specific needs.

// Enable withCredentials via customData
mediaInfo.customData = {
    withCredentials: true
};

4.b Using AMP Cast Receiver Config Property

Alternatively, the withCredentials property can be set globally for all manifest and segment requests through the AMP Cast Receiver configuration. This is ideal for applications where all media items require credentials.

const config = {
        debug: true,
        plugins: {},
        withCredentials: true
}

amp = new akamai.amp.cast.AMP(config, (event) => {
          console.log("AMP Cast READY")
})

4.c Using AMP transform API

To modify playback request attributes, you can use the akamai.amp.cast.TransformType.PLAYBACK_CONFIG transform callback. This allows setting CORS access control via cookies or authorization headers.

amp.addTransform(akamai.amp.cast.TransformType.PLAYBACK_CONFIG, (playbackConfigData) => {
    const { loadRequest, playbackConfig } = playbackConfigData
    const requestHandler = (requestInfo) => {
          requestInfo.withCredentials = true
    }

    // enables cookies for CORS Access-Control manifest and segment requests
    playbackConfig.segmentRequestHandler = requestHandler
    playbackConfig.manifestRequestHandler = requestHandler

    return { loadRequest, playbackConfig }
})

5. Custom HTTP Request Headers

The AMP Cast receiver is a powerful provides the flexibility to modify request headers for various media components, including manifests, segments, and DRM license data. This capability is essential for customizing content delivery and ensuring compatibility with different streaming protocols and security requirements. See Cast Playback Config options.

amp.addTransform(akamai.amp.cast.TransformType.PLAYBACK_CONFIG, (playbackConfigData) => {
    const { loadRequest, playbackConfig } = playbackConfigData

    playbackConfig.segmentRequestHandler = (requestInfo) => {
          requestInfo.headers['CMCD-Session'] = "1234"
    }

    return { loadRequest, playbackConfig }
})

Last modified: 15/07/2024, AMP Support.