TURTLEDOVE RTB Simulation API'sı

Özel Korumalı Alan kapsamında Chrome, reklamverenlerin ve reklam teknolojisi şirketlerinin ilgi alanı grubu hedefli reklamları üçüncü taraf çerezlere ihtiyaç duymadan göstermesine ve böylece kullanıcıları siteler arası izlemeye karşı korumasına olanak tanıyan bir tarayıcı içi API olan TURTLEDOVE'yi önerdi. Chrome, TURTLEDOVE'yu uygulamadan önce Google GZT ekibi, GZT iş ortaklarının (Authorized Buyers ve Open Bidding iş ortakları) API ile denemeler yapmasına olanak tanıyan sunucu tarafı bir TURTLEDOVE API simülasyonu sunar. Bu simülasyon, iş ortaklarının ve Google'ın TURTLEDOVE tarzı akışın verimliliği hakkında bilgi edinmesine, herkese açık forumlarda potansiyel API iyileştirmeleri hakkında alakalı geri bildirimler oluşturmasına ve üçüncü taraf çerezlerine bağımlı olmadan kişiselleştirilmiş reklamcılığı desteklemeye geçişi kolaylaştırır.

Teklif verenler, simülasyonun ilk aşamasında ilgi alanı grubu üyeliğini düzenler. Teklif verenler, API aracılığıyla Google'a önceden teklif işlevleri de sunar. Google, sunum sırasında simülasyon kapsamındaki tüm teklif isteklerini içeriğe dayalı istek ve ilgi alanına dayalı istek olmak üzere iki isteğe ayırır. Bağlamsal istek, mevcut teklif isteğine benzer ancak kullanıcı tanımlayıcıları (google_user_id, hosted_match_data alanları gibi) mevcut değildir. İlgi alanı grubu istekleri herhangi bir bağlam bilgisi içermez ve yalnızca kullanıcıyı tanımlayan alanları içerir (mevcut gizlilik denetimlerine tabidir). İlgi alanı grubu teklifleri, BGBM değeri içermez. Bunun yerine, Google'ın korumalı alana alınmış bir ortamda sunucu tarafında çalıştırdığı bir teklif işlevine başvurur. Açık artırma, teklifli sistem işlevleri tarafından hesaplanan içeriğe dayalı teklifler ve tekliflerle normal şekilde çalışır.

Simülasyonun ilk aşamasında Google, ilgi alanına dayalı istekler için belirsizleştirilmiş User-ID'ler gönderir. Amacımız, deneme işlemlerini daha erken başlatabilmemiz için iki tarafın da uygulama aşamasını en aza indirmek. İlgi alanına dayalı isteklerde kullanıcı tanımlayıcılarının varlığı, mevcut gizlilik korumalarına ve kontrollerine (kullanıcının kişiselleştirilmiş reklamcılığı devre dışı bırakması gibi) tabi olur.

Akma

akış şeması

  1. GZT Teklif Veren, her bir reklamveren ve bu ilgi alanı gruplarındaki kullanıcı üyelikleri için ilgi alanı grupları oluşturmak, bunları sürdürmek ve barındırmak üzere reklamverenlerle birlikte çalışır.
  2. Kullanıcı bir yayıncı web sayfasını ziyaret ettiğinde kullanıcının tarayıcısı Google'ın reklam etiketini indirir. Kullanıcının tarayıcısı Google yayıncı platformundan bir reklam ister.
  3. GZT teklif vereni, Google'a önceden bir veya daha fazla teklif işlevi (JavaScript işlevleri olarak) sağlar. (Teklif verme işlevleri bölümüne bakın).
  4. Deneme kapsamında olan isteklerin küçük bir kısmı için Google, denemeye katılan her bir teklif verene ayrı içeriğe dayalı teklif istekleri ve ilgi alanına dayalı teklif istekleri gönderir (bkz. Teklif istekleri).
  5. Teklif veren, ilgi alanı grubu teklif isteğinde bulunan belirsizleştirilmiş User-ID'yi kullanır ve bu kimliği ilgili ilgi alanı gruplarıyla eşleştirir. GZT teklif vereni, içeriğe dayalı teklif yanıtları ve ilgi alanına dayalı teklif yanıtları döndürecektir (bkz. Teklif yanıtları).
    1. İçeriğe dayalı teklif yanıtları, sıfır veya daha fazla içeriğe dayalı teklife sahip bugünkü teklif yanıtına benzer. Ayrıca içeriğe dayalı teklif yanıtı, teklif verme işlevine girdi olarak sunulacak özel bağlamsal sinyalleri taşıyabilir.
    2. İlgi alanına dayalı teklif yanıtları bir teklif değil, teklif işlevinin adını belirtir. Google, teklif almak için teklif verme işlevini yürütür.

  6. Google, aşağıdaki adaylarla sunucu tarafı açık artırma çalıştırır:

    1. Bağlamsal yanıttan gelen teklifler.
    2. İlgi alanı grubu yanıtında yer alan ve teklif işlevleri çalıştırılarak hesaplanan teklif fiyatlarına dayalı teklifler.
    3. Diğer teklif verenlerden gelen normal teklifler.

    Bunun bugünkü açık artırmayla aynı olduğunu unutmayın.

  7. Google, kullanıcının tarayıcısına normal bir şekilde oluşturulan kazanan bir reklam döndürür.

Teklif işlevleri

Teklif işlevleri, teklif verenlerin sağladığı ve belirli bir ilgi alanı tabanlı reklam ve reklam alanı için teklif değeri döndürecek işlevlerdir . Orijinal TURTLEDOVE teklifinde bu işlev, kullanıcının tarayıcısında depolanır. Bu simülasyonda, teklif verenler reklam sunmadan önce API'yi kullanarak Teklif İşlevleri'ni Google'a yükleyecektir. İlgi alanı yanıtı, reklam yayını sırasında bir teklif işlevi adı belirtir. Google, bu teklif işlevini korumalı bir ortamda yürütüp bir teklif değeri alır. Bu ilgi alanına dayalı teklif değeri, içeriğe dayalı teklifle aynı açık artırmaya girer.

Teklif verme işlevi arayüzü

Teklif işlevi, exchange'de sağlanan bir korumalı alanda çalıştırılacak, JavaScript'e uygulanmış tamamen yan efektli ücretsiz bir işlev olmalıdır. Bir teklif verme işlevinin ağa, depolama alanına veya diğer G/Ç biçimlerine erişimi yoktur ve farklı teklif istekleri için çağrılar arasındaki herhangi bir durumu saklayamaz. Teklifli sistem işlevi, belirli bir reklam adayı için içeriğe dayalı veriler ile ilgi grubu verilerinin kombinasyonuna göre algoritmik olarak teklif fiyatı BGBM'sini hesaplar ve döndürür.

Bir teklif verme işlevi, giriş parametresi olarak boş bir nesne ile kabul edilip çalıştırılmalıdır. Tek seferlik ilk kullanıma hazırlama sırasında teklif işlevlerine boş bir giriş sağlanır. İlk kullanıma hazırlama sırasında, teklif işlevinin anlık görüntüsü oluşturulur ve JIT (tam zamanında) derleyicinin koddaki etkin noktaları optimize edebilmesi için birkaç kez çağrılır.

/**
 * Returns a bid price CPM for a given ad candidate.
 *
 * @param {Object} inputs an object with the
 *                 following named fields:
 *                   - openrtbContextualBidRequest or googleContextualBidRequest
 *                   - customContextualSignal
 *                   - interestBasedBidData
 */
function biddingFunction(inputs) {
  ...
  return inputs.interestBasedBidData.cpm
      * inputs.customContextualSignals.placementMultiplier;
}

inputs Nesne bağımsız değişkenindeki adlandırılmış alanlar şunlardır (deneme ilerledikçe değişebilir):

openrtbContextualBidRequest (JS Nesnesi) OpenRTB protokolünde içeriğe dayalı teklif isteği. Authorized Buyers GZT protokolü kullanan teklif verenlerin bu girişi yoksayıp teklif işlevlerinde kullanmaması gerekir.
googleContextualBidRequest (JS Nesnesi) Google Authorized Buyers protokolündeki içeriğe dayalı teklif isteği. OpenRTB protokolünü kullanan teklif verenlerin bu girişi yoksayıp teklif işlevlerinde kullanmamaları gerekir.
customContextualSignal (JS Nesnesi) Teklif veren tarafından içeriğe dayalı teklif yanıtında sağlanan özel veriler. Teklif veren, biçimi belirler.
interestBasedBidData (JS Nesnesi) Teklif veren tarafından ilgi alanı grubu teklif yanıtında sağlanan özel veriler. Teklif veren, biçimi belirler.

Teklif verme işlevlerini API aracılığıyla yönetme

Bu deneysel API kaynağı, teklif verenlerin Google'a teklif işlevleri yüklemesine ve bu işlevleri yönetmesine olanak tanır.

Temel Hizmet Uç Noktası: https://realtimebidding.googleapis.com

Kaynak: Teklif verme işlevi

{
  "name": string,
  "biddingFunction": string
}

name alanı, teklif işlevinin adını temsil eder ve şu biçimde olmalıdır: bidders/{bidderAccountId}/biddingFunctions/{biddingFunctionName}, burada biddingFunctionName bir teklif veren tarafından seçilir.

biddingFunction alanı, teklif işlevinin JavaScript kaynak kodudur ve aşağıdaki gereksinimlere sahiptir:

  • 5 MiB'tan küçük boyut.
  • Teklif verme işlevi arayüzü gereksinimlerine uygundur.
  • Korumalı alanda ilk oluşturma sırasında herhangi bir giriş yapılmadan yürütme desteklenmelidir.

Örnek:

{
  "name": "bidders/1234567678/biddingFunctions/my_bidding_function_name",
  "biddingFunction": "(function(inputs) {return 1.23;})"
}

Teklif verme işlevi oluşturma

Bir teklif verme işlevi, başarılı bir CreateBiddingFunction API çağrısından sonraki yaklaşık bir saat içinde ilgi alanı grubu yanıtlarında kullanılabilir.

POST https://realtimebidding.googleapis.com/v1alpha/{parent=bidders/*}/biddingFunctions
Yol parametreleri
parent bidders/{bidderAccountId} biçiminde dize
Body: Oluşturulacak teklif işlevi
{
  "name": "bidders/1234567678/biddingFunctions/my_bidding_function_name",
  "biddingFunction": "(function(inputs) {return 1.23;})"
}
Yanıt (teklif verme işlevi)
{
  "name": "bidders/1234567678/biddingFunctions/my_bidding_function_name",
  "biddingFunction": "(function(inputs) {return 1.23;};)"
}

Mevcut teklif verme işlevlerini listeleme

GET https://realtimebidding.googleapis.com/v1alpha/bidders/{bidderAccountId}/biddingFunctions
Yol parametreleri
parent bidders/{bidderAccountId} biçiminde dize.
Sorgu parametreleri
pageToken Sunucunun döndürmesi gereken sonuçların olduğu sayfayı tanımlayan dize jetonu. Sonuçlar bir sayfaya sığmazsa bu değer, önceki bir ListBiddingFunctions çağrısı yanıtından alınır.
Yanıt
{
  "biddingFunctions": [
    {
      object (BiddingFunction)
    }
  ],
  "nextPageToken": string
}
Örnek arama
GET https://realtimebidding.googleapis.com/v1alpha/bidders/123456789/biddingFunctions

TURTLEDOVE simülasyonu GZT protokolü değişiklikleri

Authorized Buyers GZT protokolü

Teklif istekleri

Denemedeki bir içeriğe dayalı teklif isteği, geleneksel teklif istekleriyle aynı görünecek ancak belirsizleştirilmiş kullanıcı tanımlayıcıları çıkartılacaktır.

// All fields will be filled unless otherwise specified.
message BidRequest {
  // Fields below would not be populated in the experiment
  optional string google_user_id = ...;
  optional uint32 cookie_version = ...;
  optional int32 cookie_age_seconds = ...;
  optional bytes hosted_match_data = ...;
  optional string session_id = ...;

  // Contextual fields below will be populated
  optional string publisher_id = ...;
  optional string url = ...;
  ...
  message Mobile {
    // Device advertising identifiers below would not be populated
    // in the contextual requests in the experiment
    optional bytes encrypted_advertising_id = ...;
    optional bytes advertising_id = ...;
    ...
    optional bytes encrypted_hashed_idfa = ...;
    optional bytes hashed_idfa = ...;
    ...
  }
  ...
  message AdSlot {
    message MatchingAdData {
      repeated int64 billing_id = ...;
      ...
    }
    ...
  }
  repeated AdSlot adslot = ...;
  ...
}

Örneğin:

{
  id: "_\321\326\000\n\301\207\n\323\n\227",
  ip: "S\030\347",
  user_agent: "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
  publisher_country: "RU",
  geo_criteria_id: 9061060,
   adslot: [{
    id: 1,
    ad_block_key: 3613182520,
    width:   [240,200,120],
    height:   [400,200,240],
    matching_ad_data:   [{
      billing_id:     [923487589],
      minimum_cpm_micros: 850000
    }]
  }]
}

Denemedeki ilgi alanına dayalı istek, mevcut tüm gizlilik korumaları ve kontrollerine tabi olan geleneksel belirsizleştirilmiş kullanıcı tanımlayıcıları içerecek, ancak bağlamsal bilgiler (sayfa URL'si, yayıncı kimliği vb.) içermemelidir.

// Most fields would not be populated in the experiment unless otherwise specified.
message BidRequest {
   // Will be provided, subject to the existing privacy controls.
  optional string google_user_id = ...;
  optional uint32 cookie_version = ...;
  optional int32 cookie_age_seconds = ...;
  optional bytes hosted_match_data = ...;

  message AdSlot {
    // Will be filled.
    repeated int32 width = ...;
    repeated int32 height = ...;
    optional ConsentedProvidersSettings consented_providers_settings = ...;
    optional bool regs_gdpr = ...;
    optional bool regs_lgpd = ...;

    message MatchingAdData {
      // Will be filled.
      repeated int64 billing_id = ...;
      ...
    }
    ...
  }
  repeated AdSlot adslot = ...;
  ...
}

Örneğin:

id: "_\322\207\000\003\320\n\031\177C\307\215\035"
adslot {
  id: 1
  width: 1200
  height: 60
  consented_providers_settings {
    consented_providers: 292
    tcf_consent_string: "CO-eDrRO-eDrREkAAAAAAAAeYwf95y3p-wzhheMCY70-vv__7v3ff_3g"
  }
  regs_gdpr: true
  matching_ad_data {
    billing_id: 9833784997
  }
}
google_user_id: "ABCDEF1"
hosted_match_data: "ABCABCABC2"

Teklif yanıtları

İçeriğe dayalı teklif yanıtı, daha sonra teklif verme işlevine iletilecek isteğe bağlı biçimde özel, teklif verene özel bir içerik verisi içerebilir.

message BidResponse {
  message Ad {
    message AdSlot {
      required int64 max_cpm_micros = ...;
      ...
    }
    repeated AdSlot adslot = ...;
    ...
  }
  repeated Ad ad = ...;
  // Contains contextual signals that will be passed to the bidding function.
  // This can be any JSON value. For example:
  // {"foo": "bar", "base": [1, 2, 3]}
  optional google.protobuf.Value custom_contextual_signal = ...;

  ...
}

Örneğin,

ad {
  html_snippet: "<iframe src=\"http://example.com/something" width=\"300\" height=\"250\" scrolling=\"no\" frameBorder=\"0\" ></iframe>"
  adslot {
    id: 1
    max_cpm_micros: 100000
    billing_id: 1234567890
  }
  click_through_url: "https://www.example.com.pl"
  attribute: 47
  buyer_creative_id: "FFI399F3HI9HFH"
  width: 300
  height: 250
  impression_tracking_url: "http://example.com/impression"
}
custom_contextual_signal {
 struct_value {
   fields {
     name: "string_data_name"
     value {
       string_value: "string_value_1"
     }
   }
   fields {
     name: "bool_data_name"
     value {
       bool_value: true
     }
   }
 }
}
processing_time_ms: 1

İlgi alanı tabanlı teklif

İlgi alanı grubu teklif yanıtındaki her teklif, adına dayalı olarak teklif verme işlevine referans içerir. Teklif işlevleri teklif veren tarafından önceden sağlanır.

// All fields should be filled by a bidder as discussed in
// https://developers.google.com/authorized-buyers/rtb/response-guide
// unless otherwise specified.
message BidResponse {
  // Ad HTML code that will be rendered normally upon winning.
  optional string html_snippet = ...;

  message Ad {
    message AdSlot {
      // Should not be populated for interest group-based bids.
      required int64 max_cpm_micros = ...;
      ...
    }
    repeated AdSlot adslot = ...;

    // Will be filled.
    // This is the bidding function name that references a bidding function
    // that is provided ahead of time through Bidding functions API resource.
    optional string bidding_function_name = ...;

    // Contains interest group-related data that will be passed
    // to the bidding function. This can be any JSON value.
    optional google.protobuf.Value interest_group_data = ...;
    ...
  }
  repeated Ad ad = ...;
  ...
}

Örneğin:

ad {
  html_snippet: "<iframe src=\"http://example.com/something" width=\"300\" height=\"250\" scrolling=\"no\" frameBorder=\"0\" ></iframe>"
  adslot {
    id: 1
    max_cpm_micros: 0
    billing_id: 1234567890
    bidding_function_name: "bidders/123/biddingFunctions/my_bidding_function_1"
    interest_group_data {
      struct_value {
        fields {
          name: "string_data_name"
          value {
            string_value: "string_value_1"
          }
        }
        fields {
          name: "bool_data_name"
          value {
            bool_value: true
          }
        }
      }
    }
  }
  click_through_url: "https://www.example.com.pl"
  attribute: 47
  buyer_creative_id: "FFI399F3HI9HFH"
  width: 300
  height: 250
  impression_tracking_url: "http://example.com/impression"
}
processing_time_ms: 1

GZT

Teklif istekleri

Bağlamsal istek (JSON'da)
// All fields will be filled unless otherwise specified.
{
  // Fields below would not be populated in the experiment
  "user": {...}

  "device": {
    // Fields below would not be populated in the experiment
    "ifa": ...
    "dpidsha1": ...
    "dpidmd5": ...


    // Other fields will not be affected by the experiment
    ...
  }

  // Other fields will not be affected by the experiment
  ...
}
İlgi alanına dayalı istek (JSON'da)
// Most fields would not be populated in the experiment unless otherwise specified.
{
  // Will be provided, subject to the existing privacy controls.
  "user": {
    "id": "BFEUKH3"
    "buyeruid": "FEI3F3I29"
    "ext": {
      "consented_providers": [ 292 ]
      "tcf_consent_string": "CO-eDrRO-eDrREkAAilsbO2dYGD9Pn8HT3ZCY70-vv__7v3ff_3g"
    }
  }

  "imp": {
    // Will be provided, subject to the existing privacy controls.
    "banner": {
      "w": ...
      "h": ...
    }

    "ext": {
      // Will be provided, subject to the existing privacy controls.
      "billing_id": [...]

      // Other fields will not be provided by the experiment
      ...
    }
  }
}

Teklif yanıtları

İçeriğe dayalı teklif yanıtı, daha sonra teklif verme işlevine iletilecek özel, teklif verene özel bir içerik verisi içerebilir.

// All fields should be filled by a bidder as discussed in
// https://developers.google.com/authorized-buyers/rtb/response-guide
// unless otherwise specified.
{
  ...
  "seatbid": [{
     "bid": [...],
     ...
  }],
  ...
  "ext": {
    // Contains contextual signals that will be passed to the bidding function.
    // This signal can be any JSON blob. For example:
    // {"foo", "bar", "base": [1, 2, 3]}
    "custom_contextual_signal": ...
  }
}

İlgi alanı tabanlı teklif yanıtı

İlgi alanı grubu teklif yanıtındaki her teklif, adına dayalı olarak teklif verme işlevine referans içerir. Teklif işlevleri teklif veren tarafından önceden sağlanır.

// All fields should be filled by a bidder as discussed in
// https://developers.google.com/authorized-buyers/rtb/response-guide
// unless otherwise specified.
{
  "bid": [{
       "id": ...
       ...
       "ext": {
         // This is the bidding function name that references a bidding function
         // that is provided ahead of time through Bidding functions API resource.
         "bidding_function_name": ...

         // Contains interest group related data that will be passed to the
         // bidding function.
         // This signal can be any JSON blob. For example:
         // {"foo", "bar", "base": [1, 2, 3]}
         "interest_group_data": ...
       }
    }
    ...
  ]
}