The SDK provides API methods for client applications to accomplish the following:
The MediaTailor SDK can be built locally (with the command npm run build-prod) and imported by the
client application through a <script> tag or NPM installation. The build output of the SDK can be
found at dist/sdk.js.
The SDK is also redistributed with third-party libraries such as Datazoom's collector SDK.
To incorporate Google PAL SDK, add the following to the client application:
<script src="//imasdk.googleapis.com/pal/sdkloader/pal.js"></script>
If it's preferred to utilize a third-party player library for video playback handling, add it as a
dependency as well (the following is an example based on hls.js player):
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
In most common cases the client application initiates the initialization of MediaTailor playback sessions using a Session-Init URL (specific to a given content) procured through MediaTailor's services. The Session-Init URLs are in the following format:
HLS:
https://<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>.m3u8
MPEG-DASH:
https://<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>.mpd
Alternatively, the client application may utilize a third-party web service to handle the MediaTailor session initialization on its behalf. In such a case, the client application will receive both a Content-Playback URL and an Ad-Tracking URL from the web service. The former should be handed to a player to start playback, while the latter should be used in the step described in the next section.
If using Session-Init URL (common use cases), prepare a Session-Config Object as the following:
const sessionConfig = {
sessionInitUrl: sessionInitUrl
};
If using Ad-Tracking URL (use cases with third-party web services) instead:
const sessionConfig = {
trackingUrl: trackingUrl
};
Optionally, if incorporating Google PAL SDK is desired, perform the following on launch of a client application or a web page:
const allowStorage = true; // Note: the permission should be based on user consent
const palConsentSettings = {
allowStorage: allowStorage
};
mediatailor.initPal(null, palConsentSettings);
Then, add PAL configurations to the MediaTailor Session-Config Object as demonstrated in the example below:
sessionConfig.palNonceRequestParams = {
adWillAutoPlay: true,
adWillPlayMuted: true,
continuousPlayback: false,
descriptionUrl: "https://example.com",
iconsSupported: true,
playerType: "Sample Player Type",
playerVersion: "1.0",
ppid: "Sample PPID",
url: "https://developers.google.com/ad-manager/pal/html5",
videoHeight: 480,
videoWidth: 640
};
Please note that enabling Google PAL SDK and adding PAL configurations have no effects if the MediaTailor Session-Config Object was created from Ad-Tracking URL, since it's the third-party web service who actually performed the session initialization (where PAL related treatment is needed).
With the Session-Config Object prepared as described above, the next step is to create a MediaTailor Session Object which represents a MediaTailor playback session. The Session Object provides methods to interact with the session and observe session status.
The following call commences to create the Session Object and returns a Promise object:
const promise = mediatailor.createSession(sessionConfig)
The promise will be resolved once the session is successfully established, or rejected when something goes wrong. The following shows example handlers:
function onSessionCreationOK(session) {
// more to be added later ...
}
function onSessionCreationError(error) {
console.error("Session initialization error", error);
}
promise.then(onSessionCreationOK, onSessionCreationError);
Once the session is established, set up content playback with the URL retrieved from calling the
getPlaybackUrl() method of the Session Object. The following example demonstrates this based on
hls.js player:
const videoElement = document.getElementById("myVideoElementId");
const player = new Hls();
player.attachMedia(videoElement);
function onSessionCreationOK(session) {
player.loadSource(session.getPlaybackUrl());
// more to be added later ...
}
Please note that if a third-party web service is used to perform session initialization, the
getPlaybackUrl()method will returnnulland the application should set up content playback based on information from the third-party web service.
Continue from the example above (based on hls.js player), implement the periodic updates to inform
the SDK of the player's current play-head position:
function onSessionCreationOK(session) {
player.loadSource(session.getPlaybackUrl());
videoElement.addEventListener("timeupdate", () => {
// Get the regular play-head position relative to the beginning of presentation timeline
const playhead = videoElement.currentTime;
// Get the play-head position on the timeline established by the stream's "PROGRAM-DATE-TIME"
// markers who are normally available in live streams
const playingDate = player.playingDate;
const playheadInPDT = playingDate? playingDate.getTime() / 1000 : null;
session.onPlayheadUpdate(playhead, playheadInPDT);
});
// more to be added later ...
}
The SDK implements a few listener events from the Session Object which are useful for implementing
ad-related UI features. The following demonstrates the basic events that are fired when an ad
starts/progresses/ends. The detail property of each event object contains useful information
about the current ad's status and metadata.
function onSessionCreationOK(session) {
...
session.addEventListener(mediatailor.SessionUiEvent.AD_START, event => {
console.debug("AD_START", event.detail);
});
session.addEventListener(mediatailor.SessionUiEvent.AD_END, event => {
console.debug("AD_END", event.detail);
});
session.addEventListener(mediatailor.SessionUiEvent.AD_PROGRESS, event => {
console.debug("AD_PROGRESS: "+event.detail.adElapsedTime, event.detail);
});
}
Generated using TypeDoc