Ta strona została przetłumaczona przez Cloud Translation API.

Interfejs API przetwarzania kreacji wideo

Interfejs API do przesyłania kreacji wideo umożliwia zewnętrznym systemom reklamowym proaktywne przesyłanie kreacji do usług YouTube i DAI. Dzięki temu, gdy reklama zostanie wyświetlona przez serwer reklamowy inny niż Google, zwrócone kreacje będą gotowe do wyświetlenia w strumieniu wideo w YouTube lub DAI.

Proces aktywnego przetwarzania kreacji z systemów reklamowych innych firm składa się z 2 głównych części. Pierwsza część umożliwia zewnętrznemu systemowi reklamowemu przesyłanie kreacji do Google i monitorowanie ich postępów w przetwarzaniu przez infrastrukturę wideo Google. Gdy kreacje zostaną pomyślnie przetworzone, identyfikatory są przekazywane z powrotem do systemu reklamowego.

Drugi krok polega na tym, że system reklamowy pobiera te identyfikatory i umieszcza je w dokumentach VAST, które odwołują się do przesłanej kreacji, korzystając z uniwersalnego identyfikatora reklamy (VAST 4.0+) lub rozszerzenia kreacji o typie „UniversalAdId”. Gdy w systemie reklamowym (DAI lub YouTube) zostanie znaleziony dokument VAST, system kreacji wyodrębnia z niego identyfikatory i pobiera odpowiednią kreację z infrastruktury wideo Google, aby wstawić ją do odtworzenia.

Wymagania dotyczące multimediów

Aby kreacje multimedialne przesłane do interfejsu API mogły być prawidłowo przetwarzane przez system, powinny spełniać te kryteria:

Typy multimediów

Google akceptuje te typy multimediów: Inne typy mediów mogą zostać odrzucone po przesłaniu.

video/mp4
video/webm
video/quicktime
video/avi
video/mpeg
video/x-flv
flv-application/octet-stream
application/octet-stream
video/3gpp
video/ogg
audio/mp4
audio/mpeg

Właściwości multimediów

Przesłane materiały muszą spełniać te kryteria:

Materiał musi zawierać co najmniej 1 ścieżkę audio lub wideo.
Materiały muszą mieć rozsądny czas trwania. Nie dłuższe niż kilka minut.
Materiały muszą zawierać dźwięk lub obraz trwający dłużej niż 1 sekunda.
Jeśli media zawierają dźwięk, muszą mieć standardową konfigurację kanałów dźwięku, taką jak mono, stereo lub dźwięk przestrzenny.

Przesyłanie kreacji do przetwarzania

Schemat blokowy procesu przetwarzania

System reklam zewnętrznych wysyła do interfejsu API przetwarzania kreacji wideo żądanie HTTP z listą plików multimedialnych powiązanych z kreacją.
Interfejs API przetwarzania kreacji wideo wybiera kreację o najwyższej jakości z podanej listy i pobiera ją z CDN.
Interfejs API przetwarzania kreacji wideo przetwarza pobrane kreacje do infrastruktury wideo Google, dzięki czemu są one dostępne zarówno dla usług YouTube, jak i DAI.
Powiadomienie Pub/Sub jest wysyłane z powrotem do zewnętrznego systemu reklamowego wraz ze stanem kreacji. Powiadomienie będzie wskazywać, czy udało się go przesłać zarówno do YouTube, jak i do DAI. Jeśli wczytywanie kreacji zakończyło się niepowodzeniem, powiadomienie będzie zawierać przyczynę błędu.

Przesyłając kreacje, postępuj zgodnie z tymi wskazówkami.

Uwierzytelnianie

Dostęp do interfejsu API musisz uzyskać za pomocą konta usługi Google Cloud. Aby uzyskać odpowiednie upoważnienie, w momencie integracji musisz podać Google informacje o koncie.

Gdy informacje o koncie zostaną przekazane do Google za pomocą adresu creativeingestion@google.com, przyznamy Ci dostęp do punktów końcowych interfejsu API oraz tematów Cloud PubSub używanych do publikowania powiadomień.

Aby rozpocząć proces uwierzytelniania:

Utwórz konto Google Cloud.
Skonfiguruj projekt z kontem, z którego będziesz wysyłać żądania do interfejsu DAI API.
W projekcie otwórz kartę Administracja po lewej stronie i utwórz nowe konto usługi. Prośby są wysyłane za pomocą tego konta.
Włącz interfejs PubSub API i utwórz jeden unikalny temat powiadomień partnera, do którego interfejs API będzie publikować wszystkie powiadomienia o powodzeniu i niepowodzeniu przetwarzania.

Jeśli masz zaimplementowaną politykę organizacji dotyczącą ograniczeń domen, musisz dodać identyfikator klienta Google do listy dozwolonych klientów. Aby uzyskać identyfikator, skontaktuj się z firmą creativeingestion@google.com. Gdy to zrobisz, możesz dodać podmioty zabezpieczeń (nasze konto robota) z dozwolonych list klientów (identyfikator klienta interfejsu API) do zasad uprawnień (PubSub Publisher).

Dodaj video-creative-library-discovery@system.gserviceaccount.com jako wydawcę PubSub do tematu.
Aby zarejestrować te informacje w interfejsie API, podaj creativeingestion@google.com adres e-mail konta usługi i temat Pub/Sub.
Włącz interfejs DAI API po dodaniu konta jako odbiorcy usługi.
Aby skonfigurować dane logowania do interfejsu API:
- Pobierz dane logowania z konta usługi: kliknij konto usługi w sekcji Konta usługi na karcie Administracja, kliknij Utwórz klucz i zapisz dane logowania.
- Uwierzytelnianie wywołującego interfejs API. Ustaw zmienną GOOGLE_APPLICATION_CREDENTIALS na ścieżkę do pliku JSON. Aby uzyskać przykłady kodu, które umożliwiają uwierzytelnianie klientów gRPC w popularnych językach, zapoznaj się z przykładami kodu.

Przetwarzanie kreacji

Za każdym razem, gdy nowa kreacja jest dostępna w systemie reklamowym partnera, system partnera powinien przesłać ją do interfejsu Creative Ingest API.

Gdy nowe kreacje są przesyłane do Google w celu załadowania ich do infrastruktury wideo, należy podać te same dane kreacji, które są zawarte w dokumentach VAST wygenerowanych przez system reklamowy. Dzięki temu przetwarzanie kreacji w Google będzie przebiegać w taki sam sposób, jak wczytywanie kreacji po ich pierwszym wykryciu w odpowiedzi na żądanie reklamy.

Każda przesłana kreacja powoduje na serwerze długotrwałą operację przetwarzania, której stan można sprawdzić. Po pomyślnym zakończeniu operacji w systemie powstaje zasób kreacji. Odpowiedź na przesłanie kreacji zawiera identyfikator operacji, która została wykonana na podstawie żądania. Wygenerowany identyfikator operacji jest uwzględniany w powiadomieniach Cloud Pub/Sub wysyłanych po zakończeniu operacji, aby można było ją przypisać do pierwotnej przesłanej kreacji. Identyfikator operacji możesz też użyć, aby w dowolnym momencie sprawdzić postęp operacji.

Prośby o kreację

Dane są wysyłane do interfejsu API jako metryki Protocol Buffers lub obiekty JSON. Zalecamy używanie protokołu Buffers, który jest wysyłany za pomocą gRPC, ponieważ jest on niezbędny do obsługi powiadomień Pub/Sub. Rozpakowywanie danych w formacie JSON stwarza dodatkowe komplikacje z powodu pól google.protobuf.Any w odpowiedzi.

Odpowiedzi na kreacje

W przypadku powodzenia serwer zwraca odpowiedź Protocol Buffer lub odpowiedź JSON w zależności od typu żądania. Odpowiedź zawiera nazwę nowo utworzonej operacji przetwarzania oraz szczegóły tej operacji.

Po pierwszym przesłaniu niektóre metadane powiązane z operacją mogą być puste, a wynik może nie być obecny. Po zakończeniu operacji wynik jest wypełniany zasobem kreacji (lub błędem), a metadane zawierają informacje o stanie przetwarzania.

Pamiętaj, że metadane muszą zostać wyodrębnione z prototypu Any i zapisane w formacie CreateCreativeOperationMetadata, a odpowiedź (jeśli występuje) musi zostać wyodrębniona i zapisana w formacie Creative.

Biblioteka klienta do uzyskiwania dostępu do interfejsu API

Aby przeprowadzić integrację z interfejsem API:

Pobierz zależność od bufora protokołu i przenieś cały folder google do katalogu src. Jeśli używasz Google Cloud App Engine, możesz pominąć ten krok.
Użyj wtyczki protoc, aby wygenerować kod gRPC z pliku proto, a potem umieść wygenerowany kod w odpowiednim katalogu.
Utwórz nowy plik proto dla prototypu zwróconego w powiadomieniu PubSub. Powtórz poprzedni krok, aby wygenerować kod z prototypu.
Wysyłanie żądań do interfejsu API za pomocą gRPC:
1. Uzyskaj domyślne dane logowania z tymi zakresami:
https://www.googleapis.com/auth/video-ads,

https://www.googleapis.com/auth/pubsub
1. Prześlij prośbę do zespołu Przetwarzanie kreacji.
- Połącz się z dai.googleapis.com:443 za pomocą domyślnych danych logowania.
- Utwórz z użyciem kodu generowanego przez protokół gRPC element stub klienta dla usługi przetwarzania kreacji.
- Wywołaj funkcję CreateCreative, używając szablonu klienta.
Opcjonalnie utwórz szablon usługi Operations, używając długotrwałego kodu gRPC operacji (znajdującego się w katalogu googleapis pobranym w kroku 2), który może służyć do uzyskiwania stanu danej operacji (GetOperation).
Sprawdź Pub/Sub pod kątem powiadomień:
1. Użyj biblioteki klienta PubSub lub gRPC, aby połączyć się z usługą PubSub i sprawdzać powiadomienia PubSub opublikowane w podanym temacie.
2. Przekształć wiadomość Pub/Sub w proto z kroku 4.
3. Gdy z wywołań do CreateCreative, GetOperation lub z powiadomienia PubSub zwracana jest długotrwała operacja, należy odszyfrować metadane do CreateCreativeOperationMetadata w discovery.proto z proto google.protobuf.Any i wszystkie odpowiedzi do Creative w discovery.proto.

Przykładowy kod klienta Go

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
  dai "google.golang.org/genproto/googleapis/ads/dai/v1"
  psnotif "protos/dai"
  "google.golang.org/genproto/googleapis/longrunning"
  "cloud.google.com/go/pubsub"
  "golang.org/x/net/context"
  "google.golang.org/grpc"
  "google.golang.org/grpc/credentials"
  "google.golang.org/grpc/credentials/oauth"
  "github.com/golang/protobuf/proto"
  anypb "github.com/golang/protobuf/ptypes/any"
)

var scopes = []string{"https://www.googleapis.com/auth/video-ads", "https://www.googleapis.com/auth/pubsub"}

const (
  subID = "sub-id" // The ID for the subscription to the topic you provided us (projects/<project ID>/subscriptions/<subscription ID>)
  project = "your-project-id" // Your Google Cloud Project ID
)

func main() {
  ctx := context.Background()
  crpc, err := oauth.NewApplicationDefault(ctx, scopes...)
  if err != nil {
    // TODO: Handle error
  }

  conn, err := grpc.Dial("dai.googleapis.com:443",
    grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
    grpc.WithPerRPCCredentials(crpc))
  if err != nil {
    // TODO: Handle error 
  }

  apiclient := dai.NewPartnerDiscoveryServiceClient(conn)
  opclient := longrunning.NewOperationsClient(conn)

  op, err := apiclient.CreateCreative(ctx, &dai.CreateCreativeRequest{
    // TODO: Add Creative with metadata and media files.
  })
  if err != nil {
    // TODO: Handle error
  }

  pubsubClient, err := pubsub.NewClient(ctx, project)
  if err != nil {
    // TODO: Handle error
  }
  sub := pubsubClient.Subscription(subID)

  // TODO: Pull from Pub/Sub subscription to receive messages, and acknowledge them
  var msg *pubsub.Message // Assume msg = a received Pub/Sub message

  // Unmarshal the Pub/Sub message into the proto created in step 9a of guide
  var n psnotif.CreateCreativeStatus
  if err := proto.Unmarshal(msg.Data, &n); err != nil {
    // TODO: Handle error
  }
  op = n.GetDetails()
  md, err = anyToMetadata(op.GetMetadata())
  if err != nil {
    // TODO: Handle error
  }
  // TODO: Check if ingest was successful and get Google Video ID from md.GetGvRegistryId()
  // TODO: Enable serving of creative using Google Video ID in VAST document

  // Optionally check the status of an ingest request using the status endpoint
  op, err = opclient.GetOperation(ctx, &longrunning.GetOperationRequest{Name:   op.Name})
  if err != nil {
    // TODO: Handle error
  }
}

// anyToMetadata converts the metadata Any field in an Operation message to
// CreateCreativeOperationMetadata.
func anyToMetadata(msg *anypb.Any) (*dai.CreateCreativeOperationMetadata, error) {
  var md dai.CreateCreativeOperationMetadata
  return &md, proto.Unmarshal(msg.Value, &md)
}

// anyToCreative converts the response Any field in an Operation message to
// Creative.
func anyToCreative(msg *anypb.Any) (*dai.Creative, error) {
  var cr dai.Creative
  return &cr, proto.Unmarshal(msg.Value, &cr)
}

wyszukiwanie kreacji podczas odtwarzania,

Schemat procesu wyszukiwania kreacji

prośby użytkowników o wyświetlenie treści w YouTube lub DAI;
YouTube / DAI uzyskuje odpowiedź VAST z zewnętrznego systemu reklamowego, aby wstawić reklamy do treści.
Zwrócone reklamy są mapowane na wcześniej przetworzone kreacje. Te kreacje są gotowe do odtworzenia – są pobierane z infrastruktury wideo Google i odtwarzane dla użytkownika.

Dokumenty VAST zostały zmodyfikowane przez partnera

Gdy odpowiedź VAST zostanie zwrócona przez system reklamowy po pomyślnym załadowaniu kreacji do infrastruktury wideo Google, dokument powinien zawierać odwołanie do przetworzonej kreacji. Dokument VAST powinien nadal zawierać pliki multimedialne danej kreacji, ale nie ma gwarancji, że system będzie ich używać.

Istnieją 2 sposoby odniesienia się do przetworzonej kreacji w dokumencie VAST: dodanie do dokumentu VAST 4+ nowego elementu UniversalAdId lub dodanie niestandardowego rozszerzenia.

Uniwersalny identyfikator reklamy

Identyfikator gvRegistryID zwracany przez interfejs Video Creative Ingest API to uniwersalny identyfikator publiczny służący do jednoznacznego identyfikowania kreacji wideo w różnych systemach reklamowych. Ten identyfikator należy dodać do dokumentów VAST 4+ systemu reklamowego, aby po otrzymaniu przez YouTube lub DAI dokumentu VAST można było użyć tego identyfikatora do odwzorowania pierwotnie przesłanej kreacji.

Systemy reklamowe powinny dodać nowy element UniversalAdId do swoich dokumentów VAST 4+ w węźle Kreacja. Atrybut idRegistry powinien być ustawiony na „googlevideo”, a jego wartość powinna być taka sama jak w przypadku powiadomienia o przetworzeniu kreacji.

Poniżej znajduje się przykładowy dokument VAST 4 z dodanym nowym uniwersalnym identyfikatorem reklamy:

<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="4.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>DCM</AdSystem>
      <AdTitle>In-Stream Video</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <Mezzanine>
                <![CDATA[https://cdn.com/media.mp4]]>
              </Mezzanine>
              <MediaFile delivery="progressive" width="640" height="360" type="video/mp4" bitrate="313">
                <![CDATA[https://cdn.com/low-res-media.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

CreativeExtension

Element uniwersalny identyfikator reklamy został wprowadzony dopiero w VAST 4.0, dlatego aby udostępnić te same dane w dokumentach VAST w wersji niższej niż 4.0, trzeba użyć rozszerzenia niestandardowego. Aby to zrobić, użyj elementu CreativeExtension w ramach elementu Creative specyfikacji VAST.

Nowe rozszerzenie to uniwersalne rozszerzenie, które umożliwia wypełnienie dowolnej wartości identyfikatora uniwersalnego reklamy. W tym konkretnym przypadku uniwersalny identyfikator reklamy należałby do rejestru googlevideo, a identyfikatorem byłby identyfikator google video.

<VAST version="3.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>My Ad Server</AdSystem>
      <AdTitle>Car Company</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <Linear>...</Linear>
          <CreativeExtensions>
            <CreativeExtension type="UniversalAdId">
              <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
            </CreativeExtension>
          </CreativeExtensions>
        </Creative>
      </Creative>
    </InLine>
  </Ad>
</VAST>

Metodę kreacji rozszerzonej można też stosować w pliku VAST 4+, jeśli identyfikator UniversalAdId jest już wypełniony identyfikatorem innego rejestru UniversalAdId:

<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="4.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>DCM</AdSystem>
      <AdTitle>In-Stream Video</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <UniversalAdId idRegistry="other-registry">other-id</UniversalAdId>
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <Mezzanine>
                <![CDATA[https://cdn.com/media.mp4]]>
              </Mezzanine>
              <MediaFile delivery="progressive" width="640" height="360" type="video/mp4" bitrate="313">
                <![CDATA[https://cdn.com/low-res-media.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
          <CreativeExtensions>
            <CreativeExtension type="UniversalAdId">
              <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
            </CreativeExtension>
          </CreativeExtensions>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Interfejs API przetwarzania kreacji wideo Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.