Early ad break notification

Korzystanie z interfejsu Early Ad Break Notification API

Uwaga: ten interfejs API jest nadal w wersji beta. Jeśli chcesz poprosić o dostęp do programu EABN, skontaktuj się ze swoim menedżerem konta.

Interfejs Early Ad Break Notification API (EABN) pozwala powiadomić Google Ad Managera o nadchodzącej przerwie na reklamę wraz z jej metadanymi jeszcze przed jej rozpoczęciem. Prośbę o powiadomienie możesz wysłać na godzinę przed przerwą na reklamę. Z tego przewodnika dowiesz się, jak włączyć i używać interfejsu EABN API, a także przykłady żądań i odpowiedzi.

Uwaga: żądań EABN nie można zmienić, więc po utworzeniu przerwy nie można jej zmienić. Kolejne żądania utworzenia przerw na reklamy dla tego samego zdarzenia będą odrzucane, dopóki przerwa nie pojawi się w pliku manifestu tego zdarzenia.

Wywołania interfejsu EABN API muszą zawierać te informacje:

  • Identyfikator odpowiedniej transmisji na żywo, w której tworzona przerwa na reklamę. Może to być jeden z tych identyfikatorów:
  • „Klucz pliku” transmisji na żywo.
  • „Niestandardowy klucz zasobu” transmisji na żywo, który umożliwia zarządzanie własną przestrzenią kluczy przez podanie własnego ciągu identyfikatora.
  • Identyfikator źródła treści oraz identyfikator treści transmisji na żywo.

Uwaga: aby używać tego typu identyfikatora, musisz włączyć tę funkcję. Aby dowiedzieć się więcej, skontaktuj się z menedżerem konta.

  • Przewidywany czas trwania następnej przerwy na reklamę. Czas trwania musi być jak najbardziej zbliżony do rzeczywistej długości przerwy na reklamę.

Oprócz tych wymaganych pól możesz też wysyłać parametry kierowania niestandardowego, nazwę szablonu bloku reklamowego lub dane SCTE35 sygnalizowanie końca (jeśli są dostępne).

Wymagania wstępne

Aby korzystać z interfejsu API EABN, musisz utworzyć konto usługi i dodać je do sieci Google Ad Managera.

Tworzę konto usługi

Aby utworzyć konto usługi do wywoływania interfejsu EABN API, wykonaj te czynności: – Jeśli masz konto Google Cloud, utwórz konto usługi za pomocą modułu uprawnień. Więcej informacji znajdziesz w artykule Tworzenie kont usługi i zarządzanie nimi. – Jeśli nie masz konta Google Cloud, wykonaj te czynności, aby je utworzyć w Konsoli interfejsów API Google:

  1. Utwórz nowy projekt lub wybierz istniejący.
  2. Na stronie Credentials (Dane logowania) kliknij Manage service accounts (Zarządzaj kontami usługi).
  3. Na stronie Konta usługi kliknij UTWÓRZ KONTO USŁUGI.
  4. Na stronie Utwórz konto usługi wpisz szczegóły konta. Następnie kliknij UTWÓRZ.

Po utworzeniu konta usługi skopiuj jego klucz JSON, który jest używany do uwierzytelniania.

Dodawanie konta usługi do sieci Google Ad Managera

Aby dodać konto usługi do sieci, wykonaj czynności opisane w artykule Dodawanie użytkownika konta usługi w celu uzyskania dostępu do interfejsu API.

Włączam interfejs API

Po utworzeniu konta usługi podaj menedżerowi konta te informacje, by włączyć na nim interfejs API:

  • Adres e-mail Twojego konta Google Cloud
  • Twoje konto usługi
  • Kod sieci w Twojej sieci Google Ad Managera.

Po włączeniu interfejsu API przez menedżera konta wykonaj te czynności:

  1. W bibliotece interfejsów API Google wyszukaj „Google Ad Manager Video API”.
  2. Kliknij WŁĄCZ.

Uwaga: jeśli interfejs API nie pojawia się w wynikach wyszukiwania, skontaktuj się z menedżerem konta, aby upewnić się, że na Twoim koncie włączono interfejs DAI API.

Korzystanie z interfejsu API

Możesz wywołać interfejs EABN API za pomocą żądań JSON/REST.

Autoryzacja

Aby wykonywać autoryzowane wywołania interfejsu EABN API, musisz wygenerować dane logowania do konta usługi OAuth2 za pomocą klucza JSON ze swojego konta usługi i zakresu https://www.googleapis.com/auth/video-ads. Więcej informacji znajdziesz w artykule Używanie protokołu OAuth 2.0 w aplikacjach między serwerami.

Przy każdym wywołaniu interfejsu EABN API musisz podawać uzyskany token autoryzacji jako nagłówek uwierzytelniania.

Wysyłanie wcześniejszego powiadomienia o przerwie na reklamę

Aby wysłać wcześniejsze powiadomienie o przerwie na reklamę, wyślij żądanie POST na jeden z 3 prawidłowych adresów URL EABN w zależności od tego, jak chcesz skonfigurować transmisję na żywo. W sekcjach poniżej wyjaśniamy różnice między adresami URL oraz podajemy przykłady żądań i odpowiedzi.

Adresy URL

Wcześniejsze powiadomienia o przerwie na reklamę mają 3 prawidłowe adresy URL. Możesz użyć wszystkich 3 typów, aby utworzyć przerwę na reklamę (POST) lub uzyskać listę przypisanych przerw na reklamę (GET).

Aby użyć klucza pliku transmisji na żywo, użyj:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

Aby użyć niestandardowego klucza pliku transmisji na żywo, użyj:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

Aby korzystać z Content Source ID i Content ID, użyj:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

Wszystkie parametry:

  • network_code to kod Twojej sieci Google Ad Managera.
  • asset_key reprezentuje klucz pliku widoczny na stronie z informacjami o transmisji na żywo.
  • custom_asset_key to klucz niestandardowego pliku Twojej transmisji na żywo.
  • content_source_id reprezentuje identyfikator źródła treści w usłudze Google Ad Manager.
  • content_id reprezentuje identyfikator treści w usłudze Google Ad Manager.

Uwaga: podana para content_source_id/content_id musi być powiązana z transmisją na żywo w usłudze Google Ad Manager.

Treść żądania – używana tylko do utworzenia przerwy na reklamę (POST)

Obiekt

expectedDuration

Wymagane Czas trwania tej przerwy na reklamę w standardowym formacie Google (xx.xxxs, gdzie xx.xxx to liczba sekund).

customParams

Opcjonalnie Pary klucz-wartość, które mają być uwzględniane w żądaniach reklamy w ramach tej przerwy na potrzeby kierowania według kryteriów niestandardowych w AM360, rozdzielone znakiem

=

oraz dołączają przez

&

.
Przykład:

key=value&key2=value2,value3


Więcej informacji o kierowaniu znajdziesz w artykule Dodawanie parametrów kierowania do strumienia.

podTemplateName

Opcjonalnie Nazwa szablonu bloku reklamowego

scte35CueOut

Opcjonalnie Dane zakodowane w standardzie Base-64 z sygnału SCTE35. Mogą obejmować

splice_insert()

lub

time_signal()

.
Przykłady:

  • time_signal():

    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==

  • splice_insert():

    /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

Przykładowe żądania

Utwórz przerwę na reklamę
POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}
Treść odpowiedzi

Treść odpowiedzi zawiera wszystkie parametry wysłane w obiekcie adBreak, a także dodatkowe pole name, które zawiera standardowy identyfikator utworzony we wszystkich usługach Google. To pole jest zwracane w tym formacie:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
Przykładowa odpowiedź
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}
Wyświetl listę przerw na reklamę
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
Treść odpowiedzi

Treść odpowiedzi zawiera przerwy na reklamę oraz dodatkowe pole breakState na każdą przerwę na reklamę przypisaną do strumienia. Pole breakState obsługuje te wartości:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
Przykładowa odpowiedź
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}