Early ad break notification v1

Korzystanie z interfejsu Early Ad Break Notification API

  • Identyfikator odpowiedniej transmisji na żywo, dla której tworzona jest przerwa na reklamę. Identyfikator może być jednym z tych:
  • „Klucz zasobu” transmisji na żywo.
  • „Niestandardowy klucz zasobu” transmisji na żywo, który umożliwia zarządzanie własnym obszarem klucza przez podanie własnego ciągu identyfikatora.
  • „Identyfikator źródła treści” i „Content ID” transmisji na żywo.

Uwaga: musisz mieć uprawnienia do używania tego typu identyfikatora. 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 rzeczywistego czasu trwania przerwy na reklamę.

Oprócz tych wymaganych pól możesz też wysyłać niestandardowe parametry kierowania, nazwę szablonu podgrupy reklam, który ma być zastosowany, lub dane SCTE35 Cue Out (jeśli są dostępne).

Wymagania wstępne

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

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, użyj modułu IAM, aby utworzyć konto usługi. 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 Google API:

  1. Utwórz nowy projekt lub wybierz już istniejący.
  2. Na stronie Dane logowania kliknij 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 klucz JSON tego konta, który służy do uwierzytelniania.

Dodawanie konta usługi do sieci Google Ad Managera

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

Włączanie interfejsu API

Po utworzeniu konta usługi przekaż swojemu menedżerowi konto, aby umożliwić włączenie interfejsu API:

  • adres e-mail konta Google Cloud,
  • Twoje konto usługi
  • Kod sieci Google Ad Managera.

Gdy Twój menedżer konta włączy interfejs API, wykonaj te czynności, aby go włączyć:

  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 potwierdzić, że na Twoim koncie włączono interfejs DAI API.

Korzystanie z interfejsu API

Interfejs EABN API możesz wywoływać za pomocą żądań JSON/REST.

Autoryzacja

Aby wykonywać autoryzowane wywołania interfejsu EABN API, musisz wygenerować dane logowania do konta usługi OAuth 2 przy użyciu klucza JSON z 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ędzyserwerowych.

Musisz uwzględnić uzyskany token autoryzacji jako nagłówek autoryzacji w przypadku każdego wywołania interfejsu EABN API.

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

Aby wysłać powiadomienie o przerwie na reklamę, wyślij żądanie POST do jednego z trzech prawidłowych adresów URL EABN, w zależności od tego, jak chcesz określić transmisję na żywo. W następnych sekcjach wyjaśniono różnice między tymi adresami URL i podano przykłady żądań i odpowiedzi.

Adresy URL

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

Aby użyć klucza zasobu transmisji na żywo:

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 zasobu 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 identyfikatora źródła treści i identyfikatora treści, 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

W przypadku wszystkich parametrów:

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

Uwaga: podany zestaw wartości content_source_id/content_id musi być powiązany z transmisją na żywo w Google Ad Managerze.

Treść żądania – służy tylko do tworzenia przerwy na reklamę (POST).

Obiekt

expectedDuration

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

customParams

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

=

i dołączyli

&

.
Przykład:

key=value&key2=value2,value3


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

podTemplateName

Opcjonalny Nazwa szablonu bloku reklamowego

scte35CueOut

Opcjonalny Dane zakodowane w formacie Base-64 z sygnału SCTE-35. Mogą obejmować:

splice_insert()

lub

time_signal()

polecenie.
Przykłady:

  • time_signal():

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

  • splice_insert():

    /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

Przykładowe żądania

Tworzenie przerwy 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 utworzonej przerwy na reklamę w 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ę przypisanych 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 reklamy z dodatkowym polem breakState dla każdej przerwy przypisanej 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"
}