Satıcı olarak B&A ile entegrasyon

Teklifli Sistem ve Açık Artırma (B&A) Hizmetleri, Protected Audience (PA) açık artırmasını kolaylaştırmak için reklam alıcıları ve satıcılarına yönelik, Güvenilir Yürütme Ortamı'nda (TEE) çalışan bir hizmet grubudur. Bu geliştirici kılavuzunda, bir satıcının B&A için Chrome PA açık artırmasıyla nasıl entegrasyon sağlayabileceği açıklanmaktadır.

Adım adım açıklamalı kılavuz

JavaScript kodunun SAS'a gönderilen B&A açık artırma yükünü aldığı ve SAS'ın isteği Satıcı Ön Ucu'na (SFE) yönlendirdiği satıcı entegrasyon akışı. SFE, SAS'in tarayıcıya iletmesi gereken sonucu döndürür ve satıcı JavaScript kodu runAdAuction'ı çağırır.

Adımlar şu şekilde özetlenebilir:

  1. Tarayıcıdan şifrelenmiş yükü almak için getInterestGroupAdAuctionData() işlevini çağırın.
  2. fetch('https://your-ad-server.example')'ü arayın ve birleşik açık artırma isteğini şifrelenmiş yük ile SAS'inize gönderin
  3. B&A açık artırmasını çalıştırmak için SAS'inizden SFE'nizin SelectAd() işlevini çağırın
  4. B&A açık artırma sonucunu, yanıtın karmasıyla birlikte sayfaya döndürme
  5. Tek satıcılı, karma modlu veya çok satıcılı PA açık artırması çalıştırmak için tarayıcıda runAdAuction() işlevini çağırın ve sunucu tarafı B&A açık artırma sonucunu çağrıya iletin

Şifrelenmiş reklam açık artırması verilerini alma

Satıcı JavaScript kodunun getInterestGroupAdAuctionData işlevini çağırdığı ilk adımın vurgulandığı aynı açıklamalı şema

Satıcının yayıncı sayfasındaki JavaScript kodu, sunucu tarafı B&A açık artırmasını çalıştırmak için gereken verileri almak üzere navigator.getInterestGroupAdAuctionData() işlevini çağırır.

const adAuctionData = await navigator.getInterestGroupAdAuctionData({
  seller: 'https://ssp.example', // Required
  requestSize: 51200,
  coordinatorOrigin: 'https://publickeyservice.pa.gcp.privacysandboxservices.com/',
  perBuyerConfig: {
    'https://dsp-x.example': { targetSize: 8192 },
    'https://dsp-y.example': { targetSize: 8192 }
  }
});

const { requestId, request } = adAuctionData;
Alan Açıklama
seller Zorunludur. Açık artırmayı yürüten satıcının kaynağı. Bu değer, daha sonra yapılan runAdAuction() çağrısındaki seller değeriyle eşleşmelidir.
requestSize İsteğe bağlı. Tüm alıcı verilerinin maksimum yük boyutunu belirler. Daha fazla bilgi edinmek için açıklamanın istek boyutu bölümüne bakın.
perBuyerConfig İsteğe bağlı. Her alıcı için yapılandırmaları belirler ve ayrıca B&A açık artırmasına hangi alıcıların katılacağını kontrol eder.

Alıcı kaynakları perBuyerConfig içinde listelenirse yalnızca bu alıcı ilgi alanı grubu verileri yüke dahil edilir. perBuyerConfig alanında alıcı listelenmemişse kullanıcının tüm ilgi alanı grupları yüke dahil edilir.
targetSize requestSize ayarlandıysa isteğe bağlıdır. perBuyerConfig içinde bir alıcı kaynağı ayarlandıysa ancak requestSize ayarlanmadıysa zorunludur.

Söz konusu alıcının verilerinin maksimum yükü boyutunu belirler. Daha fazla bilgi edinmek için açıklamanın istek boyutu bölümüne bakın.
coordinatorOrigin İsteğe bağlıdır ancak sonunda gerekli olacaktır. Ayarlanmamışsa varsayılan değeri https://publickeyservice.pa.gcp.privacysandboxservices.com'tür.

Yükün şifrelenmesi için anahtarı almak üzere kullanılacak koordinatörü ayarlar. Daha fazla bilgi edinmek için açıklamanın koordinatör bölümüne bakın.

Çağrı yapıldığında tarayıcı, perBuyerConfig içinde listelenen alıcıların ilgi alanı gruplarını okur ve alıcı verilerini şifreler. Bu alıcı verileri, teklif verme için kullanılacak siteler arası bilgileri içerir ve TEE dışında şifresi çözülemez. Yük optimizasyonu için yüke yalnızca ilgi alanı grubu adı, güvenilir teklif sinyal anahtarları ve tarayıcı sinyalleri dahil edilir.

getInterestGroupAdAuctionData() çağrısı tarafından döndürülen reklam açık artırması veri nesnesinde requestId dizesi ve şifrelenmiş request bayt dizisi bulunur.

Reklam açık artırması verilerinde istek ve istek kimliğinin mevcut olduğunu gösteren Chrome Geliştirici Araçları ekran görüntüsü

requestId dizesi daha sonra tarayıcıda açık artırmayı tamamlamak için runAdAuction() çağrıldığında kullanılır. Şifrelenmiş request yükü, birleştirilmiş açık artırma isteğinin bir parçası olarak Satıcı Reklam Hizmeti'ne gönderilir.

Bu çağrının bir örneğini görmek için yerel test uygulamasının satıcı JavaScript koduna bakın.

Birleştirilmiş açık artırma isteğini SAS'e gönderme

Satıcı JavaScript kodunun SAS'a birleşik bir açık artırma isteği gönderdiği ikinci adımın vurgulandığı aynı açıklamalı şema

Birleştirilmiş açık artırma isteği, açık artırma bağlamında açık metin yükü ve PA B&A açık artırma yükünü içeren bir istektir. PA B&A açık artırma yükü, tarayıcının getInterestGroupAdAuctionData() çağrısında oluşturduğu şifrelenmiş request verileridir. Bu istek, bağlamsal açık artırmanın ve PA B&A açık artırmasının düzenlendiği SAS'e gönderilir.

fetch('https://ssp.example/ad-auction', {
  method: 'POST',
  adAuctionHeaders: true,
  body: JSON.stringify({
    contextualAuctionPayload: { somePayload },
    protectedAudienceAuctionPayload: encodeBinaryData(request)
  }),
});

İsteği SAS'a göndermek için sayfadan fetch() çağrısı yapılır:

  • Çağrıda adAuctionHeaders: true seçeneği bulunmalıdır. Bu seçenek, tarayıcıda açık artırmayı tamamlamak için runAdAuction() çağrıldığında tarayıcıya bu çağrının yanıtını daha sonra doğrulaması gerektiğini bildirir.
  • Getirme isteğinin kaynağı, getInterestGroupAdAuctionData() ve runAdAuction() çağrılarına sağlanan seller kaynağıyla eşleşmelidir.

Aramanın gövdesinde şunlar yer alır:

  1. İçeriğe dayalı açık artırmayı çalıştırmak için SAS tarafından kullanılacak açık metin içerikli açık artırma yükü.
  2. Sunucu tarafı B&A açık artırmasını çalıştırmak için SAS tarafından SFE'ye gönderilecek şifrelenmiş Protected Audience açık artırma yükü.

Bu çağrının bir örneğini görmek için yerel test uygulamasının satıcı JavaScript koduna bakın.

Base64 kodlama ve kod çözme

getInterestGroupAdAuctionData() çağrısından döndürülen şifrelenmiş request yükü, JSON'un işleyemediği bir veri türü olan Uint8Array örneğidir. Bayt dizisini JSON biçiminde göndermek için ikili verileri bir dizeye dönüştürmek üzere base64 kodlaması uygulayabilirsiniz.

JavaScript tarayıcı API'si, window üzerinde ikili veriler ile base64 kodlu ASCII dizesi arasında dönüştürme yapan atob() ve btoa() işlevlerini sağlar. (atob, ASCII'den ikili sisteme, btoa ise ikili sistemden ASCII'ye dönüşüm anlamına gelir.)

İkili verileri base64 olarak kodlanmış bir dizeye kodlamak için btoa() işlevini çağırma işlemi aşağıdaki gibi görünür:

function encodeBinaryData(data) {
  return btoa(String.fromCharCode.apply(null, data));
}

Bu fetch çağrısından döndürülen şifrelenmiş B&A açık artırma sonucu da base64 kodlamasındadır. Bu nedenle, kodunu ikili veriye geri çözmeniz gerekir. Base64 kodlu ASCII dizesinin kodunu ikili verilere çözmek için atob() işlevini çağırın:

function decodeBase64String(base64string) {
  return new Uint8Array(
    atob(base64string)
      .split('')
      .map((char) => char.charCodeAt(0))
  );
}

Ancak base64 ile kodlanmış bir dize genellikle orijinal verilerden yaklaşık% 33 daha büyüktür. Gecikmeyi daha da azaltmak istiyorsanız ikili verileri göndermek için JSON dışında bir biçim kullanın.

B&A açık artırmasını çalıştırmak için SFE'nin SelectAd numaralı telefonunu arayın

Üçüncü adımın vurgulandığı aynı açıklamalı şema. Bu adımda SAS, SFE'ye bir SelectAd isteği gönderir ve SFE bir B&A açık artırması düzenler.

Satıcı reklam hizmeti sayfadan birleştirilmiş açık artırma isteğini aldıktan sonra, içeriğe dayalı açık artırma kazananını belirlemek ve PA B&A açık artırmasına iletilecek alıcı sinyallerini toplamak için önce içeriğe dayalı açık artırma çalıştırılır. Ardından, istek yükü ile SAS'tan SFE'nin SelectAd işlemi çağrılarak B&A açık artırması başlatılır. 2. adımda sayfanın SAS'ye gönderdiği istekteki bazı meta verilerin SFE'ye yönlendirildiğini unutmayın.

SelectAdRequest yükünü oluşturma

SelectAd çağrısının istek yükü aşağıdaki gibi oluşturulabilir:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp.example',
    auction_signals: '{"testKey":"someValue"}',
    seller_signals: '{"testKey":"someValue"}',
    buyer_list: [
      'https://dsp-x.example',
      'https://dsp-y.example',
    ],
    per_buyer_config: {
      'https://dsp-x.example': { buyer_signals: '{"testKey": "someValue"}' },
      'https://dsp-y.example': { buyer_signals: '{"testKey": "someValue"}' },
    },
  },
  client_type: 'CLIENT_TYPE_BROWSER',
  protected_auction_ciphertext: decodeBase64string(request)
};

Tarayıcıdan gelen şifrelenmiş reklam açık artırması verileri base64 olarak kodlanmışsa SFE'ye istek gRPC kullanılarak gönderiliyorsa verilerin ikili verilere geri kodlanması gerektiğini unutmayın. İstek HTTP kullanılarak gönderilirse şifrelenmiş reklam açık artırması verileri base64 kodlu biçiminde kalabilir.

SelectAd isteğinde tanımlanan diğer alanları görmek için SelectAdRequest proto tanımına bakın.

Karma mod ve bileşen açık artırmaları için üst düzey satıcı alanını ayarlama

Satıcı karma modda açık artırma yayınlıyorsa veya çok satıcılı açık artırmaya bileşen satıcısı olarak katılıyorsa istekte top_level_seller alanının tanımlanması gerekir.

Karma modda satış yapan bir satıcıysanız top_level_seller değeri kaynağınızdır:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp-mix.example',
    top_level_seller: 'https://ssp-mix.example',
  }
}

Bileşen satıcısıysanız top_level_seller değeri, çok satıcılı açık artırmanın üst düzey satıcısıdır:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp-mix.example',
    top_level_seller: 'https://ssp-top.example',
  }
}

SFE'nin SelectAd numaralı telefonunu arayın

SAS'ten SFE'ye çağrı gRPC veya HTTP ile yapılabilir.

gRPC çağrısı

SFE'ye gönderilen gRPC isteği, gRPC istemcisi ile Node'da Express kullanılarak aşağıdaki gibi görünür:

import grpc from '@grpc/grpc-js';

// Load proto definition
const packageDefinition = protoLoader.loadSync(protoPath, { keepCase: true, enums: String });

const {
  privacy_sandbox: {
    bidding_auction_servers: { SellerFrontEnd }
  }
} = grpc.loadPackageDefinition(packageDefinition);

// Instantiate the gRPC client
const sfeGrpcClient = new SellerFrontEnd('192.168.84.104:50067', grpc.credentials.createInsecure());

// Send SelectAd request
sfeGrpcClient.selectAd(selectAdRequest,(error, response) => {
  // Handle SFE response
});

SFE istemcisinin proto tanımı, yerel test uygulaması deposunda bulunabilir.

Envoy proxy'ye HTTP çağrısı

SFE'ye gönderilen HTTP POST isteği /v1/selectAd yoluna gönderilir ve aşağıdaki gibi görünür:

fetch('https://ssp-ba.example/sfe/v1/selectAd', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(selectAdRequest),
});

Meta verileri iletme

Sayfanın SAS'a yaptığı çağrıdaki aşağıdaki meta veriler, SAS'ın SFE'ye yaptığı SelectAd çağrısına eklenmelidir:

gRPC, User-Agent başlığını değiştirebileceğinden, meta veriler SFE'ye gönderilirken aşağıdaki standart olmayan başlıklar kullanılmalıdır:

  • X-Accept-Language
  • X-User-Agent
  • X-BnA-Client-IP

Aşağıda, meta verilerin gRPC istemcisi ile Node'da Express kullanılarak nasıl yönlendirilebileceğine dair bir örnek verilmiştir:

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  const metadata = new grpc.Metadata();
  metadata.add('X-Accept-Language', req.header('Accept-Language'));
  metadata.add('X-User-Agent', req.header('User-Agent'));
  metadata.add('X-BnA-Client-IP', req.ip);

  const sfeGrpcClient = createSfeGrpcClient();
  sfeGrpcClient.selectAd(selectAdRequest, metadata, callbackFn);
})

Aşağıda, meta verilerin bir HTTP çağrısı kullanılarak nasıl yönlendirilebileceğine dair bir örnek verilmiştir:

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  fetch('https://ssp-ba.example/sfe/v1/selectAd', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Accept-Language': req.header('Accept-Language'),
      'X-User-Agent': req.header('User-Agent'),
      'X-BnA-Client-IP': req.ip
    },
    body: JSON.stringify(selectAdRequest)
  });
})

Sunucu tarafından yönetilen çok satıcılı açık artırma

Sunucu tarafından yönetilen çok satıcılı açık artırma çalıştıran üst düzey bir satıcıysanız SelectAd çağrısı yapılmadan önce SFE'ye GetComponentAuctionCiphertexts çağrısı yapılır. Yanıt, bileşen satıcısı reklam hizmetlerine gönderilen yeniden şifrelenmiş bileşen açık artırma yüklerini içerir. Döndürülen bileşen B&A reklam açık artırması sonuçları, üst düzey satıcının SFE'sinin SelectAd çağrısına sağlanır.

Daha fazla bilgi edinmek için GitHub'daki çok satıcılı açıklama sayfasına bakın.

B&A açık artırma sonucunu sayfaya döndürme

Dördüncü adımın vurgulandığı aynı açıklamalı şema. Bu adımda SAS, SelectAd'ın açık artırma sonucunu tarayıcıya geri gönderir.

B&A açık artırması sona erdikten sonra şifrelenmiş açık artırma sonucu SAS'e döndürülür ve SAS, 2. adımdaki sayfadan gelen birleştirilmiş açık artırma isteğine şifrelenmiş açık artırma sonucuyla yanıt verir. Sayfaya gönderilen SAS yanıtında, şifrelenmiş açık artırma sonucunun base64url kodlu SHA-256 karma oluşturma işlemi uygulanmış değeri Ad-Auction-Result yanıt başlığında ayarlanır. Bu karma değer, istemcide açık artırma tamamlanırken tarayıcı tarafından yükü doğrulamak için kullanılır.

Node'da base64 kodlamasıyla SHA-256 karma oluşturma işlemi aşağıdaki gibidir:

import { createHash } from 'crypto';

createHash('sha256')
  .update(binaryData, 'base64')
  .digest('base64url');

Karma oluşturma işlemini yanıt üstbilgisine ekleme ve açık artırma sonucunu sayfaya döndürme işlemi aşağıdaki gibi görünür:

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  sfeGrpcClient.selectAd(selectAdRequest, metadata, (error, response) => {
    const { auction_result_ciphertext } = response;

    const ciphertextShaHash = createHash('sha256')
      .update(auction_result_ciphertext, 'base64')
      .digest('base64url');

    res.set('Ad-Auction-Result', ciphertextShaHash);

    res.json({
      protectedAudienceAuctionResult: encodeBinaryData(auction_result_ciphertext),
      contextualAuctionResult: getContextualAuctionResult()
    });
  });
})

Bu, 2. adımda sayfadan yapılan birleştirilmiş açık artırma isteğine verilen bir yanıt olduğundan, içeriğe duyarlı açık artırma sonucu da yanıta dahil edilir.

Başlığı tekrarlayarak veya karmaları ayırarak Ad-Auction-Result değerine birden fazla karma eklenebilir. Aşağıdaki iki yanıt üstbilgisi eşdeğerdir:

Ad-Auction-Result: ungWv48Bz-pBQUDeXa4iI7ADYaOWF3qctBD_YfIAFa0=,9UTB-u-WshX66Xqz5DNCpEK9z-x5oCS5SXvgyeoRB1k=

Ad-Auction-Result: ungWv48Bz-pBQUDeXa4iI7ADYaOWF3qctBD_YfIAFa0=
Ad-Auction-Result: 9UTB-u-WshX66Xqz5DNCpEK9z-x5oCS5SXvgyeoRB1k=

Bu çağrının bir örneğini görmek için yerel test uygulamasının satıcı sunucu koduna bakın.

Açık artırmayı tamamlamak için runAdAuction() numaralı telefonu arayın

İstemci tarafı JavaScript kodunun açık artırmayı çalıştırıp sunucu yanıtını sağladığı beşinci adımın vurgulandığı aynı açıklamalı şema

SAS'den döndürülen birleşik açık artırma yanıtı, şifrelenmiş B&A açık artırma sonucunu içerir. Bu yükü, açık artırmayı tarayıcıda tamamlamak için runAdAuction() çağrısına iletebilirsiniz. 1. adımdaki getInterestGroupAdAuctionData() çağrısından alınan requestId değeri de açık artırmaya aktarılır.

// Get the encrypted ad auction data (Step #1)
const { requestId, request } = navigator.getInterestGroupAdAuctionData(adAuctionDataConfig)

// Send unified auction request (Step #2)
const response = await fetch('https://ssp-ba.example/ad-auction', {
  method: 'POST',
  body: JSON.stringify({
    adAuctionRequest: encodeBinaryData(request),
  }),
});

const { protectedAudienceAuctionResult } = await response.json();

// Finish the auction in the browser
await navigator.runAdAuction({
  // pass in "requestId" and "protectedAudienceAuctionResult"
  // the config structure will differ based on the auction configuration
});

runAdAuction() çağrısına iletilen açık artırma yapılandırmasının yapısı, satıcı tarafından seçilen açık artırma yapılandırmasına göre değişir.

Tek satıcılı açık artırma

Tek satıcılı bir B&A açık artırması çalıştırmak için runAdAuction() çağrısının açık artırma yapılandırması aşağıdaki gibi oluşturulur:

await navigator.runAdAuction({
  seller: 'https://ssp-ba.example',
  requestId,
  serverResponse: protectedAudienceAuctionResult,
});

requestId alanı, getInterestGroupAdAuctionData() çağrısı tarafından döndürülen requestId değerini kabul eder. serverResponse alanı, 3. adımda çalıştırılan B&A açık artırmasının bayt dizisini kabul eder.

Bu çağrının bir örneğini görmek için yerel test uygulamasının satıcı JavaScript koduna bakın.

Karma modlu açık artırma

Hem cihaz üzerinde hem de B&A alıcılarının katılabileceği karma modlu bir B&A açık artırması çalıştırmak için runAdAuction() çağrısının açık artırma yapılandırması aşağıdaki gibi oluşturulur:

await navigator.runAdAuction({
  seller: 'https://ssp-mix.example',
  decisionLogicURL: 'https://ssp-mix.example/score-ad.js',
  componentAuctions: [
    // B&A auction result
    {
      seller: 'https://ssp-mix.example',
      requestId,
      serverResponse: protectedAudienceAuctionResult,
    },
    // On-device auction config
    {
      seller: 'https://ssp-mix.example',
      decisionLogicURL: 'https://ssp-mix.example/on-device-score-ad.js',
      interestGroupBuyers: [
        'https://dsp-a.example', // On-device buyer
        'https://dsp-a.example', // On-device buyer
      ],
    },
  ]
});

Karma modlu açık artırmayı kolaylaştırmak için B&A açık artırma sonucu ve cihaz üzerinde açık artırma yapılandırması componentAuctions alanına iletilir. Karma modlu açık artırmada seller değeri hem üst düzey yapılandırma hem de bileşen yapılandırmaları için aynıdır.

Bu çağrının bir örneğini görmek için yerel test uygulamasının satıcı JavaScript koduna bakın.

Çok satıcılı açık artırma

Cihaz tarafından koordine edilen çok satıcılı bir açık artırma çalıştıran üst düzey bir satıcıysanız her bileşen satıcısı, B&A açık artırma sonucunu ve cihaz üzerindeki açık artırma yapılandırmalarını gönderir.

await navigator.runAdAuction({
  seller: 'https://ssp-top.example',
  decisionLogicURL: 'https://ssp-top.example/score-ad.js',
  componentAuctions: [
    // SSP-BA's B&A-only auction result
    {
      seller: 'https://ssp-ba.example',
      requestId: 'g8312cb2-da2d-4e9b-80e6-e13dec2a581c',
      serverResponse: Uint8Array(560) [193, 120, 4, …] // Encrypted B&A auction result
    },
    // SSP-MIX's B&A auction result
    {
      seller: 'https://ssp-mix.example',
      requestId: 'f5135cb2-da2d-4e9b-80e6-e13dec2a581c',
      serverResponse: Uint8Array(560) [133, 20, 4, …] // Encrypted B&A auction result
    }.
    // SSP-MIX's on-device auction config
    {
      seller: 'https://ssp-mix.example',
      interestGroupBuyers: ['https://dsp-a.example', 'https://dsp-b.example'],
      decisionLogicURL: 'https://ssp-mix.example/score-ad.js',
    }
    // SSP-OD's on-device auction config
    {
      seller: 'https://ssp-od.example',
      interestGroupBuyers: ['https://dsp-a.example', 'https://dsp-b.example'],
      decisionLogicURL: 'https://ssp-od.example/score-ad.js',
    }
  ]
})

Bu çağrının bir örneğini görmek için yerel test uygulamasının satıcı JavaScript koduna bakın.

Sonraki adımlar

Bu kılavuzu okuduktan sonra aşağıdaki adımları uygulayabilirsiniz:

Daha fazla bilgi

Sorularınız mı var?