Video Reklam Besleme API'si

Video Reklam Öğesi Besleme API'si, üçüncü taraf reklam sistemlerinin reklam öğelerini YouTube ve DAI ürünlerine proaktif olarak beslemesine olanak tanır. Bu işlem, bir reklam için Google dışı bir reklam sunucusundan karar verildiğinde, döndürülen reklam öğelerinin YouTube veya DAI video akışına yayınlanmaya hazır ve uygun olmasını sağlar.

Üçüncü taraf reklam sistemlerinden proaktif olarak reklam öğesi besleme süreci iki ana bölümden oluşur. İlk bölüm, üçüncü taraf reklam sisteminin Google'a reklam öğeleri sağlamasına ve Google video altyapısına aktarılan reklam öğelerinin ilerleme durumunu izlemesine olanak tanır. Reklam öğeleri başarıyla beslendikten sonra tanımlayıcıları reklam sistemine geri iletilir.

İkinci adımda reklam sistemi, bu tanımlayıcıları alır ve Evrensel Reklam Kimliği'ni (VAST 4.0+) veya "UniversalAdId" türündeki bir reklam öğesi uzantısını kullanarak gönderilen reklam öğesine atıfta bulunan VAST belgelerine ekler. DAI veya YouTube'da karar verme zamanında reklam sisteminden bir VAST belgesiyle karşılaşıldığında reklam öğesi sistemi bu tanımlayıcıları VAST'tan ayıklayıp oynatılmak üzere yerleştirilecek uygun reklam öğesini Google video altyapısından getirir.

Medya gereksinimleri

API'ye gönderilen reklam öğesi medyasının sistem tarafından başarıyla işlenmesi için aşağıdaki ölçütleri karşılaması gerekir.

Medya türleri

Aşağıdaki medya türleri Google tarafından kabul edilir. Diğer medya türleri gönderildikten sonra reddedilebilir.

  • 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

Medya mülkleri

Gönderilen medya öğelerinin aşağıdaki ölçütleri karşılaması gerekir:

  • Medyada en az bir ses veya video parçası olmalıdır.
  • Medya makul bir uzunlukta olmalıdır. Birkaç dakikayı aşmamalıdır.
  • Medyalarda 1 saniyeden uzun ses veya video olmalıdır.
  • Medyada ses varsa mono, stereo veya surround ses gibi standart bir ses kanalı yapılandırması olmalıdır.

Besleme için reklam öğeleri gönderme

Besleme sürecinin akış şeması

  1. Üçüncü taraf reklam sistemi, reklam öğesiyle ilişkili medya dosyalarının listesini içeren bir HTTP isteği gönderir.
  2. Video Reklam Öğesi Besleme API'si, sağlanan listeden en yüksek kaliteli reklam öğesini seçer ve CDN'den indirir.
  3. Video Reklam Öğesi Besleme API'si, indirilen reklam öğesini Google Video Altyapısı'na besler ve hem YouTube hem de DAI ürünlerinin kullanımına sunar.
  4. Reklam öğesinin durumunu içeren bir Pub/Sub bildirimi üçüncü taraf reklam sistemine geri gönderilir. Bildirimde, hem YouTube hem de DAI için başarıyla yüklenip yüklenmediği belirtilir. Reklam öğesinin yüklenmesi başarısız olursa bildirimde hatanın nedeni belirtilir.

Reklam öğeleri gönderirken bu yönergeleri uygulayın.

Kimlik doğrulama

API'ye Google Cloud hizmet hesabı kullanarak erişmeniz gerekir. Uygun yetkilendirmeyi almak için entegrasyon sırasında Google'a hesap bilgileri sağlanmalıdır.

Hesap bilgileri creativeingestion@google.com aracılığıyla Google'a sağlandıktan sonra, API uç noktalarına ve bildirimleri yayınlamak için kullanılan Cloud PubSub konularına erişim izni verilir.

Kimlik doğrulama sürecini başlatmak için aşağıdaki adımları uygulayın:

  1. Google Cloud hesabı oluşturun.
  2. DAI API'sine istek göndermek için hesapla bir proje oluşturun.
  3. Projede, sol taraftaki IAM ve Yönetici sekmesine gidin ve yeni bir hizmet hesabı oluşturun. İstekler, hizmet hesabı kullanılarak gönderilir.

  4. PubSub API'yi etkinleştirin ve API'nin tüm besleme başarı ve hata bildirimlerini yayınladığı tek bir benzersiz İş Ortağı Bildirimi konusu oluşturun.

    Alan kısıtlaması kuruluş politikanız varsa Google müşteri kimliğini izin verilen müşteri listesine eklemeniz gerekir. Kimlik için creativeingestion@google.com ile iletişime geçin. Bu işlem tamamlandıktan sonra, izin verilen müşteri listelerinden (API'nin müşteri kimliği) IAM politikalarına (PubSub yayıncısı) asıl kişileri (robot hesabımız) ekleyebilirsiniz.

    video-creative-library-discovery@system.gserviceaccount.com'ü konuya PubSub yayıncısı olarak ekleyin.

  5. Bu bilgileri API'ye kaydetmek için hizmet hesabı e-posta adresini ve Pub/Sub konusunu creativeingestion@google.com ile sağlayın.

  6. Hesap, hizmet tüketicisi olarak eklendikten sonra DAI API'yi etkinleştirin.

  7. API'ye erişmek için kimlik bilgilerinizi ayarlamak üzere:

    • Kimlik bilgilerini hizmet hesabından indirin: IAM ve Yönetici sekmesinin Hizmet hesapları bölümünde hizmet hesabını, ardından Anahtar oluştur'u tıklayın ve kimlik bilgilerini saklayın.

    • API çağıranın kimliğini doğrulayın. GOOGLE_APPLICATION_CREDENTIALS değerini JSON dosyasının yoluna ayarlayın. Yaygın dillerde gRPC istemcilerinin kimliğini doğrulamak için kod örneklerine bakın.

Reklam öğesi beslemesi

Bir iş ortağının reklam sisteminde her yeni reklam öğesi kullanıma sunulduğunda, reklam öğesi iş ortağının sistemi tarafından Creative Ingest API'ye gönderilmelidir.

Video altyapısına yüklenmek üzere Google'a yeni reklam öğeleri gönderildiğinde, reklam sistemi tarafından oluşturulan VAST belgesine dahil edilen reklam öğesi verileri sağlanmalıdır. Bu sayede, reklam öğelerinin Google'a proaktif olarak beslenmesiyle reklam öğelerinin bir reklam yanıtında ilk kez keşfedildiğinde yüklenmesiyle aynı davranış sağlanır.

Gönderilen her reklam öğesi, sunucuda uzun süren bir besleme işlemi oluşturur ve bu işlemin durumu sorgulanabilir. İşlem başarıyla tamamlandığında sistemde bir reklam öğesi kaynağı oluşturulur. Reklam öğesi gönderme yanıtı, istek sonucunda oluşan işlemin kimliğini içerir. Elde edilen işlem kimliği, işlem tamamlandığında gönderilen Cloud Pub/Sub bildirimlerine dahil edilir. Bu bildirimler, gönderilen orijinal reklam öğesiyle eşleştirilir. İşlem kimliği, işlemin ilerleme durumunu herhangi bir zamanda kontrol etmek için de kullanılabilir.

Reklam öğesi istekleri

Veriler, API'ye Protocol Buffers veya JSON nesneleri olarak gönderilir. PubSub bildirimlerini kullanmak için gerekli olduklarından ve yanıttaki google.protobuf.Any alanları nedeniyle JSON'un paketten çıkarılması daha karmaşık olduğundan gRPC kullanılarak gönderilen protokol arabellekleri önerilir.

Yaratıcı yanıtlar

İşlem başarılı olduğunda sunucu, istek türüne bağlı olarak bir Protocol Buffer yanıtı veya JSON yanıtı döndürür. Yanıt, yeni oluşturulan besleme işleminin adını ve işlemin ayrıntılarını içerir.

İlk gönderimde, işlemle ilişkili meta verilerin bazıları boş olabilir ve sonuç mevcut olmayabilir. İşlem tamamlandıktan sonra sonuç, reklam öğesi kaynağıyla (veya bir hatayla) doldurulur ve meta veriler, besleme durumuyla ilgili bilgileri içerir.

Meta verilerin bir Any proto'dan CreateCreativeOperationMetadata proto'ya, yanıtın (varsa) ise Creative proto'ya ayrıştırılması gerektiğini unutmayın.

API'ye erişmek için istemci kitaplığı

API ile entegrasyon için aşağıdaki adımları uygulayın:

  1. Protokol arabelleği bağımlılıkları'nı indirin ve google klasörünün tamamını src dizininize taşıyın. Google Cloud App Engine kullanılıyorsa bu adım atlanabilir.
  2. Proto dosyasından gRPC kodu oluşturmak ve oluşturulan kodu ilgili dizine yerleştirmek için protoc eklentisini kullanın.
  3. PubSub bildirimde döndürülen proto için yeni bir proto dosyası oluşturun; protodan kod oluşturmak için önceki adımı tekrarlayın.

  4. API'ye istek göndermek için gRPC'yi kullanın:

    1. Aşağıdaki kapsamlarla Varsayılan Kimlik Bilgileri alın:

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

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

    1. İsteği Reklam Öğesi Beslemesi'ne gönderin.
    • Varsayılan kimlik bilgilerini kullanarak dai.googleapis.com:443'e bağlanın.
    • gRPC proto-oluşturulan kodunu kullanarak reklam öğesi besleme hizmeti için istemci stub'ı oluşturun.
    • İstemci stub'ını kullanarak CreateCreative işlevini çağırın.

    İsteğe bağlı olarak, 2. adımda indirilen googleapis dizininde bulunan uzun süreli işlemler gRPC kodunu kullanarak Operations hizmetine bir stub oluşturun. Bu stub, belirli bir işlemin durumunu (GetOperation) almak için kullanılabilir.

  5. Bildirimler için Pub/Sub'ı kontrol edin:

    1. Pub/Sub hizmetine bağlanmak ve sağlanan konuya yayınlanan Pub/Sub bildirimlerini sorgulamak için Pub/Sub istemci kitaplığını veya gRPC'yi kullanın.

    2. PubSub mesajını 4. adımdaki protoya dönüştürün.

    3. CreateCreative, GetOperation çağrılarından veya bir PubSub bildiriminden uzun süren bir Operation döndürüldüğünde, meta verileri google.protobuf.Any proto'sundan discovery.proto'da CreateCreativeOperationMetadata içine ve tüm yanıtları discovery.proto'da Creative içine yerleştirin.

Örnek Go istemci kodu

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

Oynatma sırasında reklam öğesi arama

Reklam öğesi arama sürecinin akış şeması

  1. Kullanıcı, içeriği YouTube veya DAI'da görüntüleme isteğinde bulunur.
  2. YouTube / DAI, içeriğe eklenecek reklamlar için üçüncü taraf bir reklam sisteminden VAST yanıtı alır.
  3. Döndürülen reklamlar, daha önce beslenen reklam öğeleriyle eşlenir. Bu reklam öğeleri oynatılmaya hazırdır. Google Video Altyapısı'ndan alınır ve kullanıcı için oynatılır.

İş ortağı tarafından değiştirilen VAST dokümanları

Reklam öğesi Google video altyapısına başarıyla yüklendikten sonra reklam sisteminden bir VAST yanıtı döndürüldüğünde, doküman işlenen reklam öğesine referans içermelidir. VAST belgesi, belirli bir reklam öğesinin medya dosyalarını içermeye devam etmelidir ancak bu medya dosyalarının sistem tarafından kullanılacağı garanti edilmez.

İşlenen bir reklam öğesine VAST belgesinde referans vermenin iki yolu vardır: VAST 4 ve sonraki sürümlere sahip bir dokümana yeni bir UniversalAdId öğesi ekleme veya özel bir uzantı ekleme.

Evrensel Reklam Kimliği

Video Reklam Öğesi Besleme API'si tarafından döndürülen gvRegistryID, birden fazla reklam sisteminde bir video reklam öğesini benzersiz şekilde tanımlamak için kullanılan herkese açık bir evrensel kimliktir. Bu kimlik, reklam sisteminin VAST 4 ve sonraki sürümlere ait dokümanlarına eklenmelidir. Böylece, YouTube veya DAI tarafından bir VAST dokümanı alındığında, kimlik orijinal olarak gönderilen reklam öğesiyle eşleştirilebilir.

Reklam sistemleri, reklam öğesi düğümünün altına VAST 4 ve sonraki sürüm belgelerine yeni bir UniversalAdId öğesi eklemelidir. idRegistry özelliği "googlevideo" olarak ayarlanmalı ve değer, başarıyla işlenmiş reklam öğesi bildiriminin durumunda sağlanan değer olmalıdır.

Aşağıda, yeni Evrensel Reklam Kimliği'nin eklendiği örnek bir VAST 4 dokümanı verilmiştir:

<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

Evrensel reklam kimliği öğesi yalnızca VAST 4.0'ta kullanıma sunulduğundan, aynı verilerin 4.0'tan eski sürümlere sahip VAST belgelerinde gösterilmesi için özel bir uzantıya ihtiyacı vardır. Bu işlem, VAST spesifikasyonunun Reklam öğesi altında bir CreativeExtension öğesi kullanılarak yapılır.

Kullanıma sunulan yeni uzantı, herhangi bir Evrensel Reklam Kimliği değerinin doldurulmasına izin vermek için etkinleştirilen genel bir uzantıdır. Bu durumda evrensel reklam kimliği googlevideo kayıt otoritesine ait olur ve kimlik, google video kimliği olur.

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

UniversalAdId zaten farklı bir UniversalAdId sicil dairesi için bir kimlikle doldurulmuşsa CreativeExtension yaklaşımı VAST 4 ve sonraki sürümlerde de kullanılabilir:

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