Os SDKs do IMA simplificam a integração de anúncios multimídia aos seus sites e apps.
Os SDKs do IMA podem solicitar anúncios de qualquer servidor de anúncios compatível com VAST e gerenciar a reprodução de anúncios nos seus apps.
Com os SDKs de DAI do IMA, os apps fazem uma solicitação de stream para anúncios e vídeos de conteúdo de VOD ou ao vivo. Em seguida, o SDK retorna um stream de vídeo combinado para que você não precise gerenciar a alternância entre o anúncio e o vídeo de conteúdo no seu app.
Este guia demonstra como reproduzir um stream de veiculação de conjunto de anúncios da DAI usando o SDK da DAI do IMA para CAF.
Antes de usar este guia, familiarize-se com o protocolo do receptor da Web do Chromecast Application Framework. Este guia pressupõe que você tenha uma compreensão básica dos conceitos do receptor do CAF, como objetos de interceptadores de mensagens e mediaInformation, e que esteja familiarizado com o uso da ferramenta de comando e controle do Cast para emular um remetente do CAF.
Para usar a Veiculação de Conjunto DAI do IMA, você precisa trabalhar com um parceiro de veiculação de conjunto e ter uma conta do Ad Manager 360 Advanced. Se você tiver uma conta do Ad Manager, entre em contato com o gerente de contas para mais detalhes. Para saber como se inscrever no Ad Manager, acesse a Central de Ajuda do Ad Manager.
Para informações sobre como integrar com outras plataformas ou usar os SDKs do IMA do lado do cliente, consulte SDKs do Interactive Media Ads.
Visão geral da veiculação de conjunto DAI do IMA
A implementação da veiculação de pods usando o SDK do IMA CAF DAI envolve dois componentes principais, que são demonstrados neste guia:
StreamRequest: um objeto que define uma solicitação de stream para os servidores de publicidade do Google. As solicitações especificam um código de rede, uma chave de recurso personalizada e uma chave de API opcional, além de outros parâmetros opcionais.StreamManager: um objeto que processa a comunicação entre o stream de vídeo e o SDK de DAI do IMA, como disparar pings de rastreamento e encaminhar eventos de stream para o editor.
Pré-requisitos
- Uma conta do Cast Developer Console com dispositivos de teste registrados.
- Um app receptor da Web hospedado que está registrado no Console para desenvolvedores do Google Cast e que pode ser modificado para hospedar o código fornecido por este guia.
- Um app de envio configurado para usar o app receptor da Web. Para este exemplo, use a ferramenta de comando e controle do Cast como remetente.
Configurar os objetos MediaInfo do remetente
Primeiro, configure o
objeto MediaInfo
do app remetente para incluir os seguintes campos:
| Campo | Conteúdo | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
contentId
|
Um identificador exclusivo do item de mídia.
CONTENT_ID |
||||||||||
contentUrl
|
Opcional. URL do stream de backup para reproduzir se o stream de DAI não for carregado.
BACKUP_STREAM_URL |
||||||||||
contentType
|
Opcional. Tipo MIME dos streams de backup de conteúdo. Necessário apenas para streams
DASH.
CONTENT_STREAM_MIMETYPE |
||||||||||
streamType
|
A string literal ou constante usada para esse valor varia de acordo com a plataforma do remetente. | ||||||||||
customData
|
O campo customData contém um armazenamento de chave-valor de outros campos obrigatórios. Neste exemplo, ele contém os parâmetros de stream de DAI. Em
um app de produção, você pode transmitir um identificador que o app receptor
do Google Cast usaria para recuperar esses parâmetros com uma solicitação do lado do
servidor.
|
Confira alguns exemplos de código para começar:
Web
Para configurar esses valores em um remetente da Web do Cast, primeiro crie um objeto
MediaInfo
com os dados necessários e, em seguida, faça uma solicitação de
carregamento para o receptor da Web.
// 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
Para configurar esses valores em um remetente da Web do Cast, primeiro crie um MediaInfo com os dados necessários e, em seguida, faça uma solicitação de carregamento para o receptor da Web.
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)
Para configurar esses valores em um remetente da Web do Cast, primeiro crie um objeto
GCKMediaInformation
com os dados necessários e, em seguida, faça uma solicitação de
carregamento para o receptor da Web.
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)
Para configurar esses valores em um remetente da Web do Cast, primeiro crie um objeto
GCKMediaInformation
com os dados necessários e, em seguida, faça uma solicitação de
carregamento para o receptor da Web.
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
}
Ferramenta CAC
Para configurar esses valores na ferramenta de comando e controle do Cast, clique na guia "Load Media" e defina o tipo de solicitação de carregamento personalizado como LOAD. Em seguida, substitua os dados JSON na área de texto por este JSON:
{
"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"
}
}
}
Essa solicitação de carregamento personalizada pode ser enviada ao receptor para testar o restante das etapas.
Criar um receptor básico do CAF
Crie um receptor da Web personalizado, conforme mostrado no Guia do receptor da Web personalizado do SDK do CAF.
O código do receptor ficará assim:
<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>
Importar o SDK de DAI do IMA e acessar o Player Manager
Adicione uma tag script para importar o SDK do DAI do IMA para CAF ao seu receptor da Web, logo após o script que carrega o CAF. Na tag script, armazene o contexto do receptor e o gerenciador do player como constantes antes de iniciar o receptor.
<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>
Inicializar o Gerenciador de streams do IMA
Inicialize o Gerenciador de streams do IMA.
<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>
Criar o interceptador de carga do Stream Manager
Antes de transmitir os itens de mídia para o CAF, crie sua solicitação de stream em um interceptador de mensagens LOAD.
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();
Criar a solicitação de stream
Conclua a função createStreamRequest para criar um stream de veiculação de pod com base
na solicitação de carregamento do CAF.
/**
* 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;
};
Recuperar o manifesto montado do seu VTP
Se a solicitação de stream for bem-sucedida, use streamManager.getStreamId() para
recuperar o ID do stream. Seu parceiro técnico de vídeo (VTP, na sigla em inglês) ou manipulador de manifesto personalizado vai fornecer instruções para recuperar um URL de manifesto usando esse ID de stream.
Depois de recuperar o URL do manifesto, substitua o contentUrl
pelo novo manifestUrl.
Por fim, antes de retornar o manifesto de stream modificado, chame o método
loadStreamMetadata
no seu
streamManager
para informar ao SDK do IMA que ele pode solicitar metadados de stream com segurança. Essa chamada é
necessária apenas para streams de VOD.
/**
* 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;
});
};
Limpar recursos de DAI do IMA
Quando você terminar de solicitar e mostrar anúncios de display em um stream de veiculação de pod com o SDK da DAI do IMA, sugerimos que limpe todos os recursos após o término da sessão de veiculação de pod. Chame StreamManager.destroy() para interromper a reprodução
do stream, interromper todo o rastreamento de anúncios e liberar todos os recursos de stream carregados.