Video Creative Ingest API

Mit der Video Creative Ingest API können Anzeigensysteme von Drittanbietern Creatives proaktiv in YouTube- und dynamische Inventar-Produkte einspeisen. So wird sichergestellt, dass die zurückgegebenen Creatives bereit und verfügbar sind, um in einem YouTube- oder dynamischen Anzeigenbereitstellungs-Videostream ausgeliefert zu werden, wenn eine Entscheidung für eine Anzeige von einem Ad-Server außerhalb von Google getroffen wird.

Der proaktive Import von Creatives aus Anzeigensystemen von Drittanbietern umfasst zwei Hauptschritte. Im ersten Teil kann das Anzeigensystem des Drittanbieters Creatives an Google bereitstellen und den Fortschritt der Creatives bei der Aufnahme in die Google-Videoinfrastruktur im Blick behalten. Sobald die Creatives erfolgreich aufgenommen wurden, werden die IDs an das Anzeigensystem zurückgegeben.

Im zweiten Schritt werden diese IDs vom Anzeigensystem in die VAST-Dokumente aufgenommen, die auf das eingereichte Creative verweisen. Dazu wird entweder die universelle Anzeigen-ID (VAST 4.0 und höher) oder eine Creative-Erweiterung vom Typ „UniversalAdId“ verwendet. Wenn bei der Entscheidungsfindung in der dynamischen Anzeigenbereitstellung (DAI) oder auf YouTube ein VAST-Dokument aus dem Anzeigensystem gefunden wird, extrahiert das Creative-System diese IDs aus dem VAST-Dokument und ruft das entsprechende Creative aus der Google-Videoinfrastruktur ab, um es für die Wiedergabe einzufügen.

Anforderungen an Medien

Creative-Medien, die an die API gesendet werden, müssen die folgenden Kriterien erfüllen, damit sie vom System erfolgreich verarbeitet werden können.

Medientypen

Die folgenden Medientypen werden von Google akzeptiert. Alle anderen Medientypen werden bei der Einreichung möglicherweise abgelehnt.

  • 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

Medieneigenschaften

Die eingereichten Medien müssen die folgenden Kriterien erfüllen:

  • Medien müssen mindestens einen Audio- oder Videotrack haben.
  • Die Medien müssen eine angemessene Dauer haben. Nichts, was länger als einige Minuten dauert.
  • Medien müssen Audio- oder Videoinhalte enthalten, die länger als eine Sekunde sind.
  • Wenn Medien Audio enthalten, muss eine Standardkonfiguration für Audiokanäle vorhanden sein, z. B. Mono, Stereo oder Surround-Sound.

Creatives zur Datenaufnahme einreichen

Flussdiagramm des Datenaufnahmeprozesses

  1. Ein Anzeigensystem von Drittanbietern sendet eine HTTP-Anfrage an die Video Creative Ingest API mit einer Liste der mit dem Creative verknüpften Mediadateien.
  2. Die Video Creative Ingest API wählt das Creative mit der höchsten Qualität aus der bereitgestellten Liste aus und lädt es aus dem CDN herunter.
  3. Die Video Creative Ingest API nimmt das heruntergeladene Creative in die Google-Videoinfrastruktur auf und stellt es sowohl für YouTube- als auch für dynamische Anzeigenbereitstellungsprodukte zur Verfügung.
  4. Eine Pub/Sub-Benachrichtigung wird mit dem Status des Creatives an das Anzeigensystem des Drittanbieters zurückgesendet. In der Benachrichtigung wird angezeigt, ob die Daten sowohl für YouTube als auch für dynamische Anzeigenbereitstellung (Dynamic Ad Serving, DAI) erfolgreich geladen wurden. Wenn das Laden des Creatives fehlgeschlagen ist, wird in der Benachrichtigung die Ursache für den Fehler angegeben.

Beachten Sie beim Einreichen von Creatives die folgenden Richtlinien.

Authentifizierung

Sie müssen mit einem Google Cloud-Dienstkonto auf die API zugreifen. Bei der Integration müssen Kontoinformationen an Google gesendet werden, um die entsprechende Autorisierung zu erhalten.

Sobald Google über creativeingestion@google.com Kontoinformationen zur Verfügung gestellt wurden, wird Zugriff auf die API-Endpunkte und die Cloud Pub/Sub-Themen gewährt, die zum Veröffentlichen von Benachrichtigungen verwendet werden.

So starten Sie den Authentifizierungsvorgang:

  1. Erstellen Sie ein Google Cloud-Konto.
  2. Richten Sie ein Projekt mit dem Konto ein, über das Anfragen an die DAI API gesendet werden sollen.
  3. Rufen Sie im Projekt links den Tab IAM und Verwaltung auf und erstellen Sie ein neues Dienstkonto. Anfragen werden über das Dienstkonto gesendet.

  4. Aktiviere die PubSub API und erstelle ein einzelnes eindeutiges Partnerbenachrichtigungsthema, an das die API alle Benachrichtigungen über erfolgreiche und fehlgeschlagene Datenaufnahmen veröffentlicht.

    Wenn Sie eine Organisationsrichtlinie für die Domaineinschränkung haben, müssen Sie die Google-Kundennummer der Zulassungsliste hinzufügen. Wenden Sie sich an creativeingestion@google.com, um die ID zu erhalten. Anschließend kannst du Hauptkonten (unser Roboterkonto) aus zulässigen Kundenlisten (Kundennummer der API) zu IAM-Richtlinien (PubSub-Publisher) hinzufügen.

    Füge dem Thema video-creative-library-discovery@system.gserviceaccount.com als Pub/Sub-Publisher hinzu.

  5. Geben Sie creativeingestion@google.com die E-Mail-Adresse des Dienstkontos und das Pub/Sub-Thema an, um diese Informationen bei der API zu registrieren.

  6. Aktiviere die DAI API, nachdem das Konto als Dienstverbraucher hinzugefügt wurde.

  7. So legen Sie Ihre Anmeldedaten für den Zugriff auf die API fest:

    • Anmeldedaten aus dem Dienstkonto herunterladen: Klicken Sie auf dem Tab IAM & Verwaltung im Bereich Dienstkonten auf das Dienstkonto, dann auf Schlüssel erstellen und speichern Sie die Anmeldedaten.

    • Authentifizieren Sie Ihren API-Caller. Legen Sie für GOOGLE_APPLICATION_CREDENTIALS den Pfad der JSON-Datei fest. Codebeispiele zur Authentifizierung von gRPC-Clients in gängigen Sprachen

Creative-Aufnahme

Jedes Mal, wenn im Anzeigensystem eines Partners ein neues Creative verfügbar ist, sollte es über das System des Partners an die Creative Ingest API gesendet werden.

Wenn neue Creatives an Google gesendet werden, um sie in die Videoinfrastruktur hochzuladen, sollten dieselben Creative-Daten angegeben werden, die im vom Anzeigensystem generierten VAST-Dokument enthalten sind. So wird sichergestellt, dass das Verhalten beim proaktiven Einfügen von Creatives in Google dem Laden von Creatives entspricht, wenn sie zum ersten Mal in einer Anzeigenantwort erkannt werden.

Für jedes eingereichte Creative wird ein lang andauernder Datenaufnahmevorgang auf dem Server erstellt, dessen Status abgefragt werden kann. Nach Abschluss des Vorgangs wird eine Creative-Ressource im System erstellt. Die Antwort auf das Einreichen eines Creatives enthält die ID des Vorgangs, der aus der Anfrage resultiert hat. Die resultierende Vorgangs-ID ist in den Cloud Pub/Sub-Benachrichtigungen enthalten, die nach Abschluss des Vorgangs gesendet werden, um dem ursprünglichen Creative zuzuordnen, das eingereicht wurde. Anhand der Vorgangs-ID können Sie den Fortschritt des Vorgangs jederzeit prüfen.

Creative-Anfragen

Daten werden als Protocol Buffers oder als JSON-Objekte an die API gesendet. Protokoll-Buffers, die mit gRPC gesendet werden, werden empfohlen, da sie für die Verwendung der Pub/Sub-Benachrichtigungen erforderlich sind. Das Unmarshaling der JSON-Daten ist aufgrund von google.protobuf.Any-Feldern in der Antwort zusätzlich kompliziert.

Kreative Antworten

Bei Erfolg gibt der Server je nach Anfragetyp eine Protocol Buffers-Antwort oder eine JSON-Antwort zurück. Die Antwort enthält den Namen des neu erstellten Datenaufnahmevorgangs und die Details des Vorgangs.

Beim ersten Einreichen sind einige der mit dem Vorgang verknüpften Metadaten möglicherweise leer und das Ergebnis ist möglicherweise nicht vorhanden. Sobald der Vorgang abgeschlossen ist, wird das Ergebnis mit der Creative-Ressource (oder einem Fehler) ausgefüllt und die Metadaten enthalten Informationen zum Aufnahmestatus.

Die Metadaten müssen aus einem Any-Prototyp in das CreateCreativeOperationMetadata-Prototyp unmarshaled werden und die Antwort (falls vorhanden) in das Creative-Prototyp.

Clientbibliothek für den Zugriff auf die API

So integrieren Sie die API:

  1. Laden Sie die Protokoll-Buffer-Abhängigkeiten herunter und verschieben Sie den gesamten Ordner google in das Verzeichnis src. Wenn Sie die Google Cloud App Engine verwenden, können Sie diesen Schritt überspringen.
  2. Verwenden Sie das protoc-Plug-in, um gRPC-Code aus der Protodatei zu generieren, und legen Sie den generierten Code im entsprechenden Verzeichnis ab.
  3. Erstellen Sie eine neue Protodatei für das Proto, das in der PubSub-Benachrichtigung zurückgegeben wurde. Wiederholen Sie den vorherigen Schritt, um Code aus dem Proto zu generieren.

  4. Verwenden Sie gRPC, um Anfragen an die API zu senden:

    1. Standardanmeldedaten mit den folgenden Bereichen abrufen:

    https://www.googleapis.com/auth/video-ads,

    https://www.googleapis.com/auth/pubsub

    1. Sende die Anfrage an Creative Ingest.
    • Stellen Sie mit den Standardanmeldedaten eine Verbindung zu dai.googleapis.com:443 her.
    • Erstelle mit dem gRPC-Proto-generierten Code einen Client-Stub für den Creative Ingest-Dienst.
    • Rufen Sie CreateCreative mit dem Client-Stub auf.

    Optional können Sie einen Stub für den Operations-Dienst mit gRPC-Code für Vorgänge mit langer Ausführungszeit erstellen. Dieser Code ist im in Schritt 2 heruntergeladenen Verzeichnis „googleapis“ enthalten und kann verwendet werden, um den Status eines bestimmten Vorgangs (GetOperation) abzurufen.

  5. So prüfen Sie Pub/Sub auf Benachrichtigungen:

    1. Verwenden Sie die PubSub-Clientbibliothek oder gRPC, um eine Verbindung zum PubSub-Dienst herzustellen und nach PubSub-Benachrichtigungen zu suchen, die für das angegebene Thema veröffentlicht wurden.

    2. Deserialisieren Sie die PubSub-Nachricht in das Proto aus Schritt 4.

    3. Wenn ein lang laufender Vorgang von Aufrufen von CreateCreative, GetOperation oder in einer PubSub-Benachrichtigung zurückgegeben wird, unmarshalle die Metadaten aus dem google.protobuf.Any-Prototyp in CreateCreativeOperationMetadata in discovery.proto und alle Antworten in Creative in discovery.proto.

Beispiel für Go-Clientcode

// 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)
}

Creative-Suche während der Wiedergabe

Flussdiagramm für den Creative-Suchprozess

  1. Der Nutzer möchte sich Inhalte entweder in YouTube oder in der dynamischen Anzeigenbereitstellung ansehen.
  2. YouTube / DAI erhält eine VAST-Antwort von einem Anzeigensystem eines Drittanbieters, um Anzeigen in den Content einzufügen.
  3. Die zurückgegebenen Anzeigen werden zuvor aufgenommenen Creatives zugeordnet. Diese Creatives sind zur Wiedergabe bereit. Sie werden aus der Google Videoinfrastruktur abgerufen und für den Nutzer wiedergegeben.

Vom Partner geänderte VAST-Dokumente

Wenn eine VAST-Antwort vom Anzeigensystem zurückgegeben wird, nachdem das Creative erfolgreich in die Google-Videoinfrastruktur geladen wurde, sollte das Dokument einen Verweis auf das verarbeitete Creative enthalten. Das VAST-Dokument sollte weiterhin die Mediadateien für ein bestimmtes Creative enthalten. Es kann jedoch nicht garantiert werden, dass diese Mediadateien vom System verwendet werden.

Es gibt zwei Möglichkeiten, auf ein verarbeitetes Creative in einem VAST-Dokument zu verweisen: Sie können dem VAST 4-Dokument ein neues UniversalAdId-Element oder eine benutzerdefinierte Erweiterung hinzufügen.

Universelle Anzeigen-ID

Die von der Video Creative Ingest API zurückgegebene gvRegistryID ist eine universelle, öffentlich zugängliche ID, mit der ein Video-Creative in mehreren Anzeigensystemen eindeutig identifiziert werden kann. Diese ID sollte den VAST 4+-Dokumenten des Anzeigensystems hinzugefügt werden. Wenn ein VAST-Dokument von YouTube oder vom dynamischen Anzeigenbereitstellungssystem empfangen wird, kann die ID verwendet werden, um es dem ursprünglich eingereichten Creative zuzuordnen.

Anzeigensysteme sollten ihren VAST 4-Dokumenten unter dem Creative-Knoten ein neues UniversalAdId-Element hinzufügen. Das Attribut „idRegistry“ sollte auf „googlevideo“ gesetzt sein und der Wert sollte dem Wert entsprechen, der im Status der erfolgreich verarbeiteten Creative-Benachrichtigung angegeben ist.

Im Folgenden finden Sie ein Beispiel für ein VAST 4-Dokument mit der neuen universellen Anzeigen-ID:

<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

Da das Element „Universal Ad ID“ erst in VAST 4.0 eingeführt wurde, benötigen dieselben Daten eine benutzerdefinierte Erweiterung, um in VAST-Dokumenten mit einer niedrigeren Version als 4.0 angezeigt zu werden. Dazu wird das CreativeExtension-Element unter dem Creative-Element der VAST-Spezifikation verwendet.

Die neue Erweiterung ist eine generische Erweiterung, mit der beliebige Werte für die Universal AD-ID angegeben werden können. In diesem Fall würde die universelle Anzeigen-ID zur Googlevideo-Registry gehören und die ID wäre die Google-Video-ID.

<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>

Der Ansatz mit CreativeExtension kann auch in VAST 4 und höher verwendet werden, wenn die UniversalAdId bereits mit einer ID für eine andere UniversalAdId-Registry ausgefüllt ist:

<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>