Questa pagina è stata tradotta dall'API Cloud Translation.

API Video Creative Ingest

L'API Video Creative Ingest consente ai sistemi pubblicitari di terze parti di importare in modo proattivo le creatività nei prodotti YouTube e DAI. Questo processo garantisce che, quando viene presa una decisione su un annuncio da un ad server non Google, le creatività restituite siano pronte e disponibili per la pubblicazione in uno stream video di YouTube o DAI.

Il processo di importazione proattiva delle creatività dai sistemi pubblicitari di terze parti prevede due parti principali. La prima parte consente al sistema pubblicitario di terze parti di fornire le creatività a Google e di monitorare l'avanzamento delle creatività durante l'importazione nell'infrastruttura video di Google. Una volta importate correttamente le creatività, gli identificatori vengono ritrasmessi al sistema pubblicitario.

Il secondo passaggio prevede che il sistema pubblicitario acquisisca questi identificatori e li includa nei documenti VAST che fanno riferimento alla creatività inviata, utilizzando l'ID annuncio universale (VAST 4.0 e versioni successive) o un'estensione della creatività di tipo "UniversalAdId". Quando al momento della decisione in DAI o YouTube viene rilevato un documento VAST del sistema pubblicitario, il sistema delle creatività estrae questi identificatori dal VAST e recupera la creatività appropriata dall'infrastruttura video di Google da inserire per la riproduzione.

Requisiti dei contenuti multimediali

I contenuti multimediali delle creatività inviati all'API devono soddisfare i seguenti criteri per garantire che il sistema possa elaborarli correttamente.

Tipi di media

Google accetta i seguenti tipi di contenuti multimediali. Qualsiasi altro tipo di contenuti multimediali potrebbe essere rifiutato al momento dell'invio.

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

Proprietà multimediali

I contenuti multimediali inviati devono soddisfare i seguenti criteri:

I contenuti multimediali devono avere almeno una traccia audio o video.
I contenuti multimediali devono avere una durata ragionevole. Niente che superi diversi minuti.
I contenuti multimediali devono avere audio o video di durata superiore a 1 secondo.
Se i contenuti multimediali sono dotati di audio, devono avere una configurazione del canale audio standard, ad esempio mono, stereo o audio surround.

Inviare le creatività per l'importazione

Diagramma di flusso del processo di importazione

Un sistema pubblicitario di terze parti invia una richiesta HTTP all'API Video Creative Ingest con un elenco di file multimediali associati alla creatività.
L'API Video Creative Ingest seleziona la creatività di qualità più elevata dall'elenco fornito e la scarica dalla CDN.
L'API Video Creative Ingest importa la creatività scaricata nell'Infrastruttura video di Google, rendendola disponibile sia per i prodotti YouTube sia per i prodotti DAI.
Al sistema pubblicitario di terze parti viene inviata una notifica Pub/Sub con lo stato della creatività. La notifica indicherà se il caricamento è andato a buon fine sia per YouTube sia per DAI. Se il caricamento della creatività non è andato a buon fine, la notifica indicherà la causa dell'errore.

Segui queste linee guida quando invii le creatività.

Autenticazione

Devi accedere all'API utilizzando un account servizio Google Cloud. Al momento dell'integrazione, i dati dell'account devono essere forniti a Google per ottenere l'autorizzazione appropriata.

Una volta forniti a Google i dati dell'account tramite creativeingestion@google.com, verrà concesso l'accesso agli endpoint API e gli argomenti Cloud Pub/Sub utilizzati per pubblicare le notifiche.

Per avviare la procedura di autenticazione:

Crea un account Google Cloud.
Configura un progetto con l'account per l'invio di richieste all'API DAI.
All'interno del progetto, vai alla scheda IAM e amministrazione a sinistra e crea un nuovo account di servizio. Le richieste vengono inviate utilizzando l'account di servizio.
Attiva l'API Pub/Sub e crea un unico argomento di notifica del partner a cui l'API pubblica tutte le notifiche di successo e di errore di importazione.

Se hai implementato un criterio dell'organizzazione per le limitazioni del dominio, devi aggiungere l'ID cliente Google all'elenco dei clienti consentiti. Contatta creativeingestion@google.com per recuperare l'ID. Al termine, puoi aggiungere i principali (il nostro account robot) dagli elenchi dei clienti consentiti (l'ID cliente dell'API) ai criteri IAM (PubSub Editor).

Aggiungi video-creative-library-discovery@system.gserviceaccount.com come editore PubSub all'argomento.
Fornisci a creativeingestion@google.com l'indirizzo email dell'account di servizio e l'argomento Pub/Sub per registrare queste informazioni con l'API.
Attiva l'API DAI dopo aver aggiunto l'account come consumatore di servizi.
Per impostare le credenziali per accedere all'API:
- Scarica le credenziali dall'account di servizio: fai clic sull'account di servizio nella sezione Account di servizio della scheda IAM e amministrazione, fai clic su Crea chiave e memorizza le credenziali.
- Autenticare l'utente che chiama l'API. Imposta GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON. Consulta gli esempi di codice per l'autenticazione dei client gRPC nelle lingue più comuni.

Importazione delle creatività

Ogni volta che una nuova creatività è disponibile nel sistema pubblicitario di un partner, deve essere inviata dal sistema del partner all'API Creative Ingest.

Quando vengono inviate a Google nuove creatività da caricare nell'infrastruttura video, devono essere forniti gli stessi dati delle creatività inclusi nel documento VAST generato dal sistema pubblicitario. In questo modo, il comportamento dell'importazione proattiva delle creatività in Google è lo stesso del caricamento delle creatività quando vengono rilevate per la prima volta in una risposta all'annuncio.

Ogni creatività inviata crea un'operazione di importazione di lunga durata sul server sul cui stato è possibile eseguire query. Al termine dell'operazione, viene generata una risorsa creativa all'interno del sistema. La risposta all'invio di una creatività contiene l'ID dell'operazione risultante dalla richiesta. L'ID operazione risultante è incluso nelle notifiche Cloud Pub/Sub inviate al termine dell'operazione per eseguire la mappatura alla creatività originale inviata. L'ID operazione può essere utilizzato anche per controllare l'avanzamento dell'operazione in qualsiasi momento.

Richieste di creatività

I dati vengono inviati all'API come Protocol Buffers o come oggetti JSON. I buffer di protocollo, inviati utilizzando gRPC, sono consigliati in quanto necessari per utilizzare le notifiche PubSub e lo smarshalling del JSON comporta complicazioni aggiuntive a causa dei campi google.protobuf.Any nella risposta.

Risposte creative

In caso di esito positivo, il server restituisce una risposta Protocol Buffer o JSON, a seconda del tipo di richiesta. La risposta contiene il nome dell'operazione di importazione appena creata e i dettagli dell'operazione.

Al primo invio, alcuni dei metadati associati all'operazione potrebbero essere vuoti e il risultato potrebbe non essere presente. Al termine dell'operazione, il risultato viene compilato con la risorsa Creativa (o un errore) e i metadati contengono informazioni sullo stato dell'importazione.

Tieni presente che i metadati devono essere unmarshaled da un proto Any al proto CreateCreativeOperationMetadata e la risposta (se presente) deve essere unmarshaled nel proto Creative.

Libreria client per accedere all'API

Per eseguire l'integrazione con l'API:

Scarica le dipendenze del protocollo buffer e sposta l'intera cartella google nella directory src. Questo passaggio può essere saltato se utilizzi Google Cloud App Engine.
Utilizza il plug-in protoc per generare codice gRPC dal file proto e inserisci il codice generato nella directory pertinente.
Crea un nuovo file proto per il proto restituito nella notifica PubSub. Ripeti il passaggio precedente per generare il codice dal proto.
Utilizza gRPC per effettuare richieste all'API:
1. Ottieni le credenziali predefinite con i seguenti ambiti:
https://www.googleapis.com/auth/video-ads,

https://www.googleapis.com/auth/pubsub
1. Invia la richiesta a Creative Ingest.
- Connettiti a dai.googleapis.com:443 utilizzando le credenziali predefinite.
- Crea uno stub client per il servizio di importazione delle creatività utilizzando il codice proto-generato gRPC.
- Chiama CreateCreative utilizzando lo stub del client.
Facoltativamente, crea uno stub per il servizio Operations utilizzando il codice gRPC per le operazioni di lunga durata, incluso nella directory googleapis scaricata nel passaggio 2, che può essere utilizzato per ottenere lo stato di una determinata operazione (GetOperation).
Controlla Pub/Sub per le notifiche:
1. Utilizza la libreria client PubSub o gRPC per connetterti al servizio Pub/Sub e eseguire il polling per le notifiche Pub/Sub pubblicate nell'argomento fornito.
2. Esegui il unmarshalling del messaggio Pub/Sub nel proto del passaggio 4.
3. Ogni volta che viene restituita un'operazione a lunga esecuzione dalle chiamate a CreateCreative, GetOperation o in una notifica Pub/Sub, destruttura i metadati in CreateCreativeOperationMetadata in discovery.proto dal proto google.protobuf.Any e qualsiasi risposta in Creative in discovery.proto.

Esempio di codice client 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)
}

Ricerca delle creatività durante la riproduzione

Diagramma di flusso della procedura di ricerca delle creatività

L'utente richiede di visualizzare i contenuti su YouTube o DAI.
YouTube / DAI ottiene una risposta VAST da un sistema pubblicitario di terze parti per gli annunci da inserire nei contenuti.
Gli annunci restituiti vengono mappati alle creatività importate in precedenza. Queste creatività sono pronte per la riproduzione: vengono recuperate dall'Infrastruttura video di Google e riprodotte per l'utente.

Documenti VAST modificati dal partner

Quando il sistema pubblicitario restituisce una risposta VAST dopo che la creatività è stata caricata correttamente nell'infrastruttura video di Google, il documento deve contenere un riferimento alla creatività elaborata. Il documento VAST dovrebbe continuare a includere i file multimediali per una determinata creatività, ma non viene fornita alcuna garanzia che questi file multimediali verranno utilizzati dal sistema.

Esistono due modi per fare riferimento a una creatività elaborata in un documento VAST: aggiungendo un nuovo elemento UniversalAdId al documento VAST 4 o superiore o aggiungendo un'estensione personalizzata.

ID annuncio universale

gvRegistryID restituito dall'API Video Creative Ingest è un ID universale rivolto al pubblico utilizzato per identificare in modo univoco una creatività video in più sistemi pubblicitari. Questo ID deve essere aggiunto ai documenti VAST 4 e versioni successive del sistema pubblicitario in modo che, quando un documento VAST viene ricevuto da YouTube o DAI, l'ID possa essere utilizzato per eseguire la mappatura della creatività inviata inizialmente.

I sistemi pubblicitari devono aggiungere un nuovo elemento UniversalAdId ai propri documenti VAST 4 e versioni successive sotto il nodo Creative. L'attributo idRegistry deve essere impostato su "googlevideo" e il valore deve corrispondere a quello fornito nello stato della notifica della creatività elaborata correttamente.

Di seguito è riportato un documento VAST 4 di esempio con il nuovo ID annuncio universale aggiunto:

<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

Poiché l'elemento ID annuncio universale è stato introdotto solo in VAST 4.0, gli stessi dati richiedono un'estensione personalizzata per essere esposti nei documenti VAST con una versione precedente alla 4.0. A tale scopo viene utilizzato un elemento CreativeExtension nell'elemento Creative della specifica VAST.

La nuova estensione introdotta è un'estensione generica che consente di compilare qualsiasi valore ID annuncio universale. In questo caso specifico, l'ID annuncio universale appartiene al registry googlevideo e l'ID è l'ID video di Google.

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

L'approccio CreativeExtension può essere utilizzato anche in VAST 4 e versioni successive nel caso in cui UniversalAdId sia già compilato con un ID per un registry UniversalAdId diverso:

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

API Video Creative Ingest Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.