Mit IMA SDKs können Sie Multimedia-Anzeigen einfacher in Ihre Websites und Apps einbinden.
IMA SDKs können Anzeigen von jedem VAST-konformen Ad-Server anfordern und die Anzeigenwiedergabe in Ihren Apps verwalten.
Mit IMA DAI SDKs senden Apps eine Streamanfrage für Anzeigen- und Contentvideos für VOD- oder Live-Inhalte. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie in Ihrer App nicht zwischen Anzeigen- und Inhaltsvideo wechseln müssen.
In diesem Leitfaden wird gezeigt, wie Sie einen DAI-Pod-Bereitstellungsstream mit dem IMA DAI SDK für CAF abspielen.
Bevor Sie diesen Leitfaden verwenden, sollten Sie sich mit dem Web Receiver-Protokoll des Chromecast Application Framework vertraut machen. In diesem Leitfaden werden grundlegende Kenntnisse der CAF-Empfängerkonzepte wie Nachrichten-Interceptors und mediaInformation-Objekte sowie die Verwendung des Cast Command and Control-Tools zur Emulation eines CAF-Senders vorausgesetzt.
Wenn Sie die Pod-Auslieferung mit IMA DAI verwenden möchten, müssen Sie mit einem Pod-Auslieferungspartner zusammenarbeiten und ein Ad Manager 360 Advanced-Konto haben. Wenn Sie ein Ad Manager-Konto haben, wenden Sie sich an Ihren Account Manager, um weitere Informationen zu erhalten. Informationen zur Registrierung für Ad Manager finden Sie in der Ad Manager-Hilfe.
Informationen zur Integration mit anderen Plattformen oder zur Verwendung der clientseitigen IMA SDKs finden Sie unter Interactive Media Ads SDKs.
IMA DAI Pod-Auslieferung – Übersicht
Die Implementierung der Pod-Bereitstellung mit dem IMA CAF DAI SDK umfasst zwei Hauptkomponenten, die in diesem Leitfaden beschrieben werden:
StreamRequest: Ein Objekt, das eine Streamanfrage an die Werbeserver von Google definiert. In Anfragen werden ein Netzwerkcode, ein benutzerdefinierter Asset-Schlüssel und ein optionaler API-Schlüssel sowie weitere optionale Parameter angegeben.StreamManager: Ein Objekt, das die Kommunikation zwischen dem Videostream und dem IMA DAI SDK verarbeitet, z. B. das Auslösen von Tracking-Pings und das Weiterleiten von Stream-Ereignissen an den Publisher.
Vorbereitung
- Ein Cast Developer Console-Konto mit registrierten Testgeräten.
- Eine gehostete Web-Empfänger-App, die in deiner Cast Developer Console registriert ist und so geändert werden kann, dass sie den in diesem Leitfaden bereitgestellten Code hostet.
- Eine Sender-App, die für die Verwendung deiner Web-Receiver-App konfiguriert ist. Verwende für dieses Beispiel das Cast Command and Control-Tool als Sender.
MediaInfo-Objekte des Senders konfigurieren
Konfiguriere zuerst das MediaInfo-Objekt deiner Sender-App so, dass es die folgenden Felder enthält:
| Feld | Inhalt | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
contentId
|
Eine eindeutige Kennung für diese Mediendatei.
CONTENT_ID |
||||||||||
contentUrl
|
Optional. URL des Back-up-Streams, der abgespielt werden soll, wenn der Stream für die dynamische Anzeigenbereitstellung nicht geladen werden kann.
BACKUP_STREAM_URL |
||||||||||
contentType
|
Optional. MIME-Typ der Content-Sicherungsstreams. Nur für DASH-Streams erforderlich.
CONTENT_STREAM_MIMETYPE |
||||||||||
streamType
|
Das Stringliteral oder die Konstante, die für diesen Wert verwendet wird, variiert je nach Absenderplattform. | ||||||||||
customData
|
Das Feld customData enthält einen Schlüssel/Wert-Speicher mit zusätzlichen erforderlichen Feldern. In diesem Beispiel enthält es die Parameter für den DAI-Stream. In einer Produktions-App kannst du stattdessen eine Kennung übergeben, mit der deine Cast-Empfänger-App diese Parameter mit einer serverseitigen Anfrage abruft.
|
Hier sind einige Codebeispiele für den Einstieg:
Web
Wenn du diese Werte in einem Cast-Websender konfigurieren möchtest, erstelle zuerst ein MediaInfo-Objekt mit den erforderlichen Daten und sende dann eine Ladeanfrage an den Web-Receiver.
// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "CONTENT_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
daiStreamType: "DAI_STREAM_TYPE",
networkCode: "NETWORK-CODE",
customAssetKey: "CUSTOM_ASSET_KEY",
apiKey: "API_KEY"
};
// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
() => { console.log('Load succeed'); },
(errorCode) => { console.log('Error code: ' + errorCode); });
Android
Wenn du diese Werte in einem Cast-Websender konfigurieren möchtest, erstelle zuerst ein MediaInfo-Objekt mit den erforderlichen Daten und sende dann eine Ladeanfrage an den Web-Empfänger.
JSONObject customData = new JSONObject()?
.put("daiStreamType", "DAI_STREAM_TYPE")
.put("networkCode", "NETWORK-CODE")
.put("customAssetKey", "CUSTOM_ASSET_KEY")
.put("apiKey", "API_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
.setContentUrl("BACKUP_STREAM_URL")
.setContentType("CONTENT_STREAM_MIMETYPE")
.setStreamType(MediaInfo.STREAM_TYPE_LIVE)
.setCustomData(customData)
.build();
RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());
iOS (Obj-C)
Wenn du diese Werte in einem Cast-Websender konfigurieren möchtest, erstelle zuerst ein GCKMediaInformation-Objekt mit den erforderlichen Daten und sende dann eine Ladeanfrage an den Web-Receiver.
NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
@"daiStreamType": @"DAI_STREAM_TYPE",
@"networkCode": @"NETWORK-CODE",
@"customAssetKey": @"CUSTOM_ASSET_KEY",
@"apiKey": @"API_KEY"};
mediaInfoBuilder.customData = customData;
GCKMediaInformationBuilder *mediaInfoBuilder =
[[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];
GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
request.delegate = self;
}
iOS (Swift)
Wenn du diese Werte in einem Cast-Websender konfigurieren möchtest, erstelle zuerst ein GCKMediaInformation-Objekt mit den erforderlichen Daten und sende dann eine Ladeanfrage an den Web-Receiver.
let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
print("invalid mediaURL")
return
}
let customData = [
"daiStreamType": "DAI_STREAM_TYPE",
"networkCode": "NETWORK-CODE",
"customAssetKey": "CUSTOM_ASSET_KEY",
"region": "API_KEY"
]
let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()
guard let mediaInfo = mediaInformation else {
print("invalid mediaInformation")
return
}
if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia
(mediaInfo) {
request.delegate = self
}
CAC-Tool
Wenn du diese Werte im Cast Command and Control-Tool konfigurieren möchtest, klicke auf den Tab „Load Media“ und lege den benutzerdefinierten Ladeanfragetyp auf „LOAD“ fest. Ersetzen Sie dann die JSON-Daten im Textbereich durch diese JSON-Daten:
{
"media": {
"contentId": "CONTENT_ID",
"contentUrl": "BACKUP_STREAM_URL",
"contentType": ""CONTENT_STREAM_MIMETYPE"",
"streamType": "LIVE",
"customData": {
"daiStreamType": "DAI_STREAM_TYPE",
"networkCode": "NETWORK-CODE",
"customAssetKey": "CUSTOM_ASSET_KEY",
"oAuthToken": "API_KEY"
}
}
}
Diese benutzerdefinierte Ladeanfrage kann an den Empfänger gesendet werden, um die restlichen Schritte zu testen.
Einfachen CAF-Empfänger erstellen
Erstelle einen benutzerdefinierten Web-Empfänger, wie im CAF SDK Custom Web Receiver Guide beschrieben.
Der Code des Empfängers sollte so aussehen:
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
</script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
// ...
</script>
</body>
</html>
IMA DAI SDK importieren und Player Manager abrufen
Fügen Sie ein Script-Tag hinzu, um das IMA DAI SDK für CAF in Ihren Web-Empfänger zu importieren, und zwar direkt nach dem Script, das CAF lädt. Speichere im Script-Tag den Empfängerkontext und den Player-Manager als Konstanten, bevor du den Empfänger startest.
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
castContext.start();
</script>
</body>
</html>
IMA Stream Manager initialisieren
Initialisieren Sie den IMA Stream Manager.
<html>
<head>
<script type="text/javascript"
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
castContext.start();
</script>
</body>
</html>
Stream Manager Load Interceptor erstellen
Bevor deine Mediendateien an das CAF übergeben werden, musst du deine Streamanfrage in einem LOAD-Nachrichten-Interceptor erstellen.
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
/**
* Creates a livestream request object for a Pod Serving stream.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => { /* ... */};
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithPodStreamData) => {
console.log('Successfully made DAI stream request.');
// ...
return castRequestWithPodStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, createDAICastRequest);
castContext.start();
Streamanfrage erstellen
Führen Sie die Funktion createStreamRequest aus, um einen Pod-Bereitstellungsstream basierend auf der CAF-Ladeanfrage zu erstellen.
/**
* Creates a livestream request object for a Pod Serving stream.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => {
const customData = castRequest.media.customData;
let streamRequest;
if (customData.daiStreamType == "LIVE") {
streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
streamRequest.customAssetKey = customData.customAssetKey;
streamRequest.networkCode = customData.networkCode;
streamRequest.apiKey = customData.apiKey;
} else if (customData.daiStreamType == "VOD") {
streamRequest = new google.ima.cast.dai.api.PodVodStreamRequest();
streamRequest.networkCode = customData.networkCode;
streamRequest.apiKey = customData.apiKey;
}
return streamRequest;
};
Zusammengefügtes Manifest von Ihrem VTP abrufen
Wenn Ihre Streamanfrage erfolgreich ist, rufen Sie mit streamManager.getStreamId() die ID des Streams ab. Dein Video Technical Partner (VTP) oder benutzerdefinierter Manifestmanipulator stellt eine Anleitung zum Abrufen einer Manifest-URL mithilfe dieser Stream-ID bereit.
Nachdem Sie die Manifest-URL abgerufen haben, ersetzen Sie die vorhandene contentUrl durch die neue manifestUrl.
Bevor Sie das geänderte Streammanifest zurückgeben, rufen Sie die Methode loadStreamMetadata für streamManager auf, um das IMA SDK darüber zu informieren, dass es Streammetadaten sicher anfordern kann. Dieser Aufruf ist nur für VOD-Streams erforderlich.
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithPodStreamData) => {
console.log('Successfully made DAI stream request.');
// This is a sample VTP integration. Consult your VTP documentation
// for how to retrieve an ad-stitched stream manifest URL.
const manifestTemplate = "https://.../manifest.m3u8?gam_stream_id=[[STREAMID]]";
const streamId = streamManager.getStreamId();
const manifestUrl = manifestTemplate.replace('[[STREAMID]]', streamId)
// Assign your manifestUrl to the request's content URL.
castRequestWithPodStreamData.media.contentUrl = manifestUrl;
// After generating the manifest URL, VOD streams must notify the
// IMA SDK that it is safe to request ad pod metadata.
// This is only necessary for VOD streams. It is a no-op for
// livestreams, so no conditional is needed.
streamManager.loadStreamMetadata();
return castRequestWithPodStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
IMA-DAI-Assets bereinigen
Wenn Sie Anzeigen in einem Pod-Bereitstellungsstream mit dem IMA DAI SDK angefordert und angezeigt haben, sollten Sie alle Ressourcen nach Abschluss der Pod-Bereitstellungssitzung bereinigen. Rufen Sie StreamManager.destroy() auf, um die Streamwiedergabe zu beenden, das Anzeigen-Tracking zu stoppen und alle geladenen Stream-Assets freizugeben.