Подготовка клиента к показу пакета с переадресацией

В этом руководстве рассказывается, как разработать клиентское приложение для загрузки прямой трансляции HLS или DASH с помощью Pod Serving API и вашего инструмента управления манифестом.

Требования

Прежде чем продолжить, необходимо:

Как отправить запрос на создание потока

Когда пользователь выбирает поток, выполните следующие действия:

  1. Отправьте запрос POST к методу сервиса трансляций. Подробную информацию можно найти в разделе Метод: stream.

  2. Передавайте параметры таргетинга объявлений в форматах application/x-www-form-urlencoded или application/json. Этот запрос регистрирует сеанс трансляции в Google DAI.

    В примере ниже показан запрос на трансляцию.

    Кодировка формы

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
          `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
    
    const params = new URLSearchParams({
            cust_params: 'section=sports&page=golf,tennis'
    }).toString();
    
    const response = await fetch(url, {
            method: 'POST',
            headers: {
              'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: params
    });
    
    console.log(await response.json());
    

    Кодировка JSON

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
          `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
    
    const response = await fetch(url, {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              cust_params: {
                section: 'sports',
                page: 'golf,tennis'
              }
            })
    });
    
    console.log(await response.json());
    

    Если все пройдет успешно, вы увидите примерно следующее:

    {
    "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
    "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
    "session_update_url": "https://dai.google.com/linear/.../session",
    "polling_frequency": 10
    }
    
  3. В ответе JSON найдите идентификатор сеанса трансляции и сохраните другие данные для последующих шагов.

Метаданные объявлений с опросами

Чтобы запросить метаданные объявления, выполните следующие действия:

  1. Прочитайте значение metadata_url из ответа на запрос регистрации потока.

  2. Отправьте начальный запрос GET конечной точке metadata_url.

    • Пропустите параметр запроса delta_token. Это позволяет серверу возвращать полные метаданные для интервала DVR трансляции. Интервал DVR – это период времени, в течение которого зритель может перематывать и воспроизводить трансляцию. Ответ содержит поле next_delta_token.
  3. Чтобы оптимизировать пропускную способность, сохраните значение next_delta_token из последнего ответа.

  4. В следующем запросе отправьте это значение в качестве параметра запроса delta_token. Сервер возвращает только те метаданные, которые изменились с момента создания токена. Всегда отправляйте последний полученный токен. Не пытайтесь анализировать, изменять или создавать токен. Подробную информацию можно найти в статье Метод: метаданные.

    В примере ниже показано, как получить метаданные объявления.

    // Initial request (returns full metadata and next_delta_token)
    let response = await fetch(metadata_url);
    let metadata = await response.json();
    let deltaToken = metadata.next_delta_token;
    
    // Subsequent request (returns only changes since deltaToken)
    if (deltaToken) {
      const url = new URL(metadata_url);
      url.searchParams.append('delta_token', deltaToken);
      response = await fetch(url.toString());
      const deltaMetadata = await response.json();
      // Merge deltaMetadata into your local cache
      mergeMetadata(metadata, deltaMetadata);
      deltaToken = deltaMetadata.next_delta_token;
    }
    

    Если запрос выполнен успешно, вы получите ответ PodMetadata. Если вы укажете параметр delta_token, ответ будет содержать только объявления, рекламные паузы и теги, которые сервер добавил или обновил с момента создания токена. Ответ также содержит новое значение next_delta_token. Если какие-либо рекламные паузы устарели, ответ также будет содержать список obsolete_ad_break_ids рекламных пауз, которые нужно удалить из кеша.

    {
      "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
      "obsolete_ad_break_ids": ["0003069407"],
      "tags":{
        "google_1022389921":{
          "ad":"0003069408_ad1",
          "ad_break_id":"0003069408",
          "type":"start"
        },
        ...
      },
      "ads":{
        "0003069408_ad1":{
          "ad_break_id":"0003069408",
          "position":1,
          "duration":10.01,
          "title":"External - Pod Midroll 1",
          "clickthrough_url":"https://.../",
          ...
        },
        ...
      },
      "ad_breaks":{
        "0003069408":{
          "type":"mid",
          "duration":30,
          "ads":3
        },
        ...
      }
    }
    
  5. Сохраните объект tags и объедините обновления в локальном кеше. Если параметр obsolete_ad_break_ids присутствует, удалите эти рекламные паузы и связанные с ними объявления и теги из кеша.

  6. Установите таймер, используя значение polling_frequency, чтобы регулярно запрашивать метаданные. В каждом опросе отправляйте значение next_delta_token, возвращенное в последнем ответе с метаданными, в качестве параметра запроса delta_token.

Загрузите поток в видеопроигрыватель

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

Инструкции по передаче идентификатора сеанса можно найти в документации к инструменту управления манифестом. Если вы разрабатываете инструмент управления манифестом, ознакомьтесь со статьей Инструмент управления манифестом для прямых трансляций.

Ниже приведен пример URL манифеста.

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

Когда проигрыватель будет готов, запустите воспроизведение.

Как отслеживать события объявлений

Проверьте формат контейнера трансляции для временных метаданных:

  • В потоках HLS с контейнерами Transport Stream (TS) для передачи временных метаданных используются временные теги ID3. Подробнее о формате CMAF с HLS…

  • В потоках DASH для указания событий в манифесте используются элементы EventStream.

  • В потоках DASH используются элементы InbandEventStream, если сегменты содержат поля Event Message (emsg) для данных полезной нагрузки, включая теги ID3. Подробную информацию вы найдете в разделе InbandEventStream.

  • В потоках CMAF, включая DASH и HLS, используются поля emsg, содержащие теги ID3.

Чтобы извлечь теги ID3 из потока, следуйте инструкциям в руководстве по видеопроигрывателю. Подробную информацию вы найдете в руководстве по работе с временными метаданными.

Чтобы получить идентификатор события объявления из тегов ID3, выполните следующие действия:

  1. Отфильтруйте события по scheme_id_uri с помощью urn:google:dai:2018 или https://aomedia.org/emsg/ID3.
  2. Извлеките массив байтов из поля message_data.

    В примере ниже данные emsg декодируются в JSON:

    {
      "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
      "presentation_time": 27554,
      "timescale": 1000,
      "message_data": "ID3TXXXgoogle_1022389921",
      ...
    }
    
  3. Отфильтруйте теги ID3 в формате TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921
    

Показать данные о событиях объявлений

Чтобы найти объект TagSegment, выполните следующие действия:

  1. Получите объект метаданных объявления tags из метаданных объявления для опроса. Объект tags – это массив объектов TagSegment.

  2. Используйте полный идентификатор события объявления, чтобы найти объект TagSegment с типом progress.

  3. Чтобы найти объект TagSegment другого типа, используйте первые 17 символов идентификатора события объявления.

    Поскольку клиентское приложение периодически запрашивает метаданные объявлений, между моментом, когда видеопроигрыватель обнаруживает тег ID3 в потоке, и моментом, когда становятся доступны связанные с ним метаданные, может возникнуть задержка. Если клиентское приложение не находит тег ID3 среди сохраненных тегов, оставьте его в очереди и обработайте повторно после следующего опроса метаданных. Тег остается в очереди до завершения обработки.

  4. Получив TagSegment, используйте свойство ad_break_id в качестве ключа, чтобы найти объект AdBreak в объекте метаданных объявления ad_breaks.

    В следующем примере выполняется поиск объекта AdBreak:

    {
      "type":"mid",
      "duration":15,
      "ads":1
    }
    
  5. Используйте данные TagSegment и AdBreak, чтобы показывать информацию о позиции объявления в рекламной паузе. Пример: Ad 1 of 3.

Отправка запросов для подтверждения событий

Для каждого события объявления, кроме типа progress, отправьте запрос для подтверждения события. Динамическая вставка объявлений Google отбрасывает события progress, и их частая отправка может повлиять на производительность приложения.

Чтобы создать полный URL подтверждения медиаконтента для события объявления, выполните следующие действия:

  1. Из ответа на запрос потока добавьте полный идентификатор события объявления к значению media_verification_url.

  2. Выполните запрос GET с полным URL:

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
    const completeUrl = `${media_verification_url}google_1022389921`;
    
    const response = await fetch(completeUrl);
    

    Если запрос выполнен успешно, вы получите ответ с кодом статуса 202. В противном случае вы получите код ошибки 404.

Монитор действий в потоке позволяет изучать журнал всех событий, связанных с объявлениями. Подробнее о том, как отслеживать трансляцию и устранять неполадки…