To discuss and provide feedback on our products, join the official Ad Manager Discord channel in the Google Advertising and Measurement Community server.

Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как настроить IMA SDK для динамической вставки объявлений

Выберите платформу: HTML5 Android iOS tvOS Cast Roku

Выберите решение для динамической вставки объявлений

Показ пакетов с динамической вставкой объявлений

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 Расширенный. Если у вас есть аккаунт Менеджера рекламы, обратитесь к менеджеру по работе с клиентами. Информацию о том, как зарегистрироваться в Менеджере рекламы, можно найти в Справочном центре Менеджера рекламы.

Информацию об интеграции с другими платформами или использовании клиентских IMA SDK можно найти в разделе Interactive Media Ads SDK.

Общие сведения о показе пакетов с динамической вставкой объявлений в IMA DAI

Чтобы реализовать показ пакетов с помощью IMA CAF DAI SDK, вам понадобятся два основных компонента, которые описаны в этом руководстве:

StreamRequest – объект, определяющий запрос трансляции к рекламным серверам Google. В запросах указываются код сети, ключ специального объекта и необязательный ключ API, а также другие необязательные параметры.
StreamManager: Объект, который обрабатывает связь между видеопотоком и IMA DAI SDK, например отправляет пинги отслеживания и пересылает события потока издателю.

Требования

Аккаунт Cast Developer Console с зарегистрированными тестовыми устройствами.
Размещенное веб-приложение приемника, зарегистрированное в Cast Developer Console, которое можно изменить, чтобы разместить код, приведенный в этом руководстве.
Отправляющее приложение, настроенное на использование вашего веб-приемника. В этом примере в качестве отправителя используется инструмент управления Cast.

Настройка объектов MediaInfo отправителя

Сначала настройте объект MediaInfo приложения отправителя, добавив в него следующие поля:

Поле Содержание

contentId

Уникальный идентификатор мультимедийного объекта.

CONTENT_ID

contentUrl

Необязательное поле. URL резервной трансляции, которая будет воспроизводиться, если не удастся загрузить трансляцию с динамической вставкой объявлений.

BACKUP_STREAM_URL

contentType

Необязательное поле. MIME-тип потоков резервных копий контента. Требуется только для потоков DASH.

CONTENT_STREAM_MIMETYPE

streamType Строковый литерал или константа, используемые для этого значения, зависят от платформы отправителя.

customData

Поле customData содержит хранилище пар "ключ-значение" для дополнительных обязательных полей. В этом примере он содержит параметры потока DAI. В рабочем приложении вы можете передать идентификатор, который приложение-получатель будет использовать для получения этих параметров с помощью запроса на стороне сервера.

Поле	Содержание
`daiStreamType`	Тип трансляции с динамической вставкой объявлений. Одно из двух значений: `"LIVE"` или `"VOD"`. `DAI_STREAM_TYPE`
`networkCode`	Код сети для вашего аккаунта Google Менеджера рекламы 360. `NETWORK_CODE`
`customAssetKey`	Это поле необходимо только для прямых трансляций. Специальный ключ ресурса, который идентифицирует событие показа пакета в Google Менеджере рекламы 360. `CUSTOM_ASSET_KEY`
`apiKey`	Необязательный ключ API для получения идентификатора потока из IMA DAI SDK. `API_KEY`

Вот несколько примеров кода, которые помогут вам начать работу:

Веб

Чтобы настроить эти значения в веб-отправителе 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, нажмите на вкладку Load Media (Загрузить медиаконтент) и задайте для типа запроса на загрузку значение LOAD. Затем замените данные JSON в текстовом поле на следующий код 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

Создайте собственный веб-приемник, как описано в руководстве по созданию собственного веб-приемника в SDK CAF.

Код получателя должен выглядеть следующим образом:

<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

Инициализируйте менеджер трансляций 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>

Как создать перехватчик загрузки 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;
    };

Как получить объединенный манифест из VTP

Если запрос потока выполнен успешно, используйте 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(), чтобы остановить воспроизведение потока, отслеживание рекламы и освободить все загруженные объекты потока.