IMA SDK упрощает интеграцию мультимедийных объявлений на сайты и в приложения.
IMA SDK может запрашивать объявления с любого совместимого с VAST сервера объявлений и управлять воспроизведением рекламы в ваших приложениях.
При использовании IMA DAI SDK приложения отправляют запрос на показ видеорекламы и контента в видео по запросу или прямых трансляциях. Затем SDK возвращает комбинированный видеопоток, поэтому вам не нужно управлять переключением между рекламой и видеоконтентом в приложении.
В этом руководстве рассказывается, как воспроизвести поток с показом пакетов с динамической вставкой объявлений, используя IMA DAI SDK для CAF.
Прежде чем использовать это руководство, ознакомьтесь с протоколом веб-приемника Chromecast Application Framework. В этом руководстве предполагается, что вы знакомы с основными понятиями, связанными с приемником CAF, такими как перехватчики сообщений и объекты mediaInformation, а также умеете использовать инструмент Cast Command and Control для эмуляции отправителя CAF.
Чтобы использовать показ пакетов с динамической вставкой объявлений IMA DAI, вам необходимо сотрудничать с партнером по показу пакетов и иметь аккаунт Менеджера рекламы 360 Advanced. Если у вас есть аккаунт Менеджера рекламы, обратитесь к менеджеру по работе с клиентами. Информацию о регистрации в Менеджере рекламы можно найти в Справочном центре.
Информацию об интеграции с другими платформами или об использовании клиентских IMA SDK можно найти в статье Interactive Media Ads SDK.
Общие сведения о показе пакетов с динамической вставкой объявлений в IMA DAI
Реализация показа пакетов с помощью IMA CAF DAI SDK включает два основных компонента, которые описаны в этом руководстве:
StreamRequest– объект, определяющий запрос потока к рекламным серверам Google. В запросах указывается код сети, ключ специального объекта, ключ API (необязательно), а также другие необязательные параметры.StreamManager– объект, который управляет обменом данными между видеопотоком и IMA DAI SDK, например отправляет запросы ping для отслеживания и пересылает издателю события потока.
Требования
- Аккаунт Cast Developer Console с зарегистрированными тестовыми устройствами.
- Размещенное веб-приложение получателя, зарегистрированное в Cast Developer Console. Его можно изменить, чтобы разместить код, приведенный в этом руководстве.
- Приложение-отправитель, настроенное для использования вашего веб-приложения-получателя. В этом примере в качестве отправителя используется инструмент Cast Command and Control.
Настройка объектов MediaInfo отправителя
Сначала настройте объект MediaInfo приложения-отправителя, включив в него следующие поля:
| Поле | Содержание | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
contentId
|
Уникальный идентификатор этого мультимедийного объекта.
CONTENT_ID |
||||||||||
contentUrl
|
Необязательное поле. URL резервной трансляции, которая будет воспроизводиться, если не удастся загрузить трансляцию с динамической вставкой объявлений.
BACKUP_STREAM_URL |
||||||||||
contentType
|
Необязательное поле. MIME-тип резервных потоков контента. Требуется только для потоков DASH.
CONTENT_STREAM_MIMETYPE |
||||||||||
streamType
|
Строковый литерал или константа, используемые для этого значения, зависят от платформы отправителя. | ||||||||||
customData
|
Поле customData содержит хранилище пар "ключ-значение" для дополнительных обязательных полей. В этом примере он содержит параметры потока динамической вставки объявлений. В рабочем приложении вместо этого можно передавать идентификатор, который приложение-приемник Cast будет использовать для получения этих параметров с помощью запроса на стороне сервера.
|
Вот несколько примеров кода, которые помогут вам начать:
Веб
Чтобы настроить эти значения в веб-отправителе Cast, сначала создайте объект MediaInfo с необходимыми данными, а затем отправьте запрос на загрузку веб-получателю.
// 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
Чтобы настроить эти значения в веб-отправителе Cast, сначала создайте объект MediaInfo с необходимыми данными, а затем отправьте запрос на загрузку веб-получателю.
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)
Чтобы настроить эти значения в веб-отправителе Cast, сначала создайте объект GCKMediaInformation с необходимыми данными, а затем отправьте запрос на загрузку веб-получателю.
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)
Чтобы настроить эти значения в веб-отправителе Cast, сначала создайте объект GCKMediaInformation с необходимыми данными, а затем отправьте запрос на загрузку веб-получателю.
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
}
Инструмент для расчета стоимости привлечения клиента
Чтобы настроить эти значения в инструменте Cast Command and Control, перейдите на вкладку Load Media (Загрузка медиаконтента) и выберите тип запроса на загрузку LOAD. Затем замените данные 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"
}
}
}
Этот специальный запрос на загрузку можно отправить получателю, чтобы протестировать остальные шаги.
Создание базового приемника CAF
Создайте собственный веб-приемник, как описано в руководстве по CAF SDK.
Код приемника должен выглядеть следующим образом:
<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 и получите Player Manager
Добавьте тег script, чтобы импортировать IMA DAI SDK для CAF в веб-приемник, сразу после скрипта, загружающего CAF. В теге script сохраните контекст получателя и менеджер проигрывателя в виде констант перед запуском получателя.
<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
Инициализируйте 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
Прежде чем передавать мультимедийные объекты в CAF, создайте запрос потока в перехватчике сообщений 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();
Создайте запрос потока
Заполните функцию createStreamRequest, чтобы создать поток для пакетной передачи на основе запроса на загрузку 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;
};
Получите объединенный манифест от поставщика видеотехнологий
Если запрос потока выполнен успешно, используйте streamManager.getStreamId(), чтобы получить идентификатор потока. Ваш технический партнер по видеорекламе или пользовательский манипулятор манифеста предоставит инструкции по получению URL манифеста с помощью этого идентификатора потока.
Получив URL манифеста, замените существующий contentUrl на новый manifestUrl.
Наконец, перед возвратом измененного манифеста потока вызовите метод loadStreamMetadata для streamManager, чтобы сообщить IMA SDK, что он может безопасно запрашивать метаданные потока. Этот вызов необходим только для видео по запросу.
/**
* 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
После того как вы успешно запросите и покажете объявления в потоке с пакетной передачей, используя IMA DAI SDK, мы рекомендуем очистить все ресурсы. Вызовите StreamManager.destroy(), чтобы остановить воспроизведение потока, прекратить отслеживание рекламы и освободить все загруженные объекты потока.