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 güvenilir yürütme ortamında (TEE) çalışan, reklam alıcıları ve satıcıları için 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 yapabileceği açıklanmaktadır.

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

Adımlar şu şekilde özetlenebilir:

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

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

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

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;

Ç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ı bilgiler içerir ve TEE dışında şifresi çözülemez. Yük optimizasyonu için yalnızca ilgi alanı grubu adı, güvenilir teklif sinyali anahtarları ve tarayıcı sinyalleri yüke 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.

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

Bu çağrıya ilişkin bir örnek görmek için yerel test uygulamasının satıcı JavaScript koduna bakın.

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

Birleşik açık artırma isteği, düz metin bağlamsal açık artırma yükünü 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 request çağrısında oluşturduğu şifrelenmiş getInterestGroupAdAuctionData() verilerdir. Bu istek, bağlamsal açık artırmanın ve PA B&A açık artırmasının düzenlendiği SAS'ye 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 bir fetch() çağrısı yapılır:

• Çağrı, 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ını bildiren adAuctionHeaders: true seçeneğini içermelidir.
• Getirme isteğinin kaynağı, seller ve runAdAuction() çağrılarına sağlanan getInterestGroupAdAuctionData() kaynağıyla eşleşmelidir.

Görüşmenin gövde bölümünde şunlar yer alır:

1. SAS'ın içerik açık artırmasını çalıştırmak için kullanacağı düz metin içerik açık artırması yükü.
2. Sunucu tarafında teklifli sistem ve açık artırma açık artırmasını yürütmek için SAS tarafından SFE'ye gönderilecek şifrelenmiş Protected Audience açık artırma yükü.

Bu çağrıya ilişkin bir örnek 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'ın işleyemediği bir veri türü olan Uint8Array örneğidir. Bayt dizisini JSON biçiminde göndermek için ikili verileri 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üşüm yapan atob() ve btoa() işlevlerini sağlar. (atob, ASCII'den ikiliye, btoa ise ikiliden ASCII'ye dönüştürme anlamına gelir).

İkili verileri base64 kodlu 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ıyla yapıldığından bunu tekrar ikili veriye dönüştürmeniz gerekir. Base64 kodlu ASCII dizesinin kodunu çözerek ikili verilere dönüştürmek 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'yi SelectAd arayın.

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üyle birlikte 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 yaptığı istekten gelen 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önderildiğinde ikili verilere geri çözülmesi 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ı ayarlama

Satıcı, karma modda bir açık artırma düzenliyorsa veya çok satıcılı bir açık artırmaya bileşen satıcı olarak katılıyorsa istekte top_level_seller alanı tanımlanmalıdır.

Karma modda satış yapıyorsanı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'tan SFE'ye yapılan çağrı gRPC veya HTTP ile yapılabilir.

gRPC çağrısı

SFE'ye yapılan 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 istemcisi için proto tanımı, yerel test uygulaması deposunda bulunabilir.

Envoy proxy'sine yapılan HTTP çağrısı

SFE'ye yönelik 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'ye yaptığı çağrıdaki aşağıdaki meta veriler, SAS'nin SFE'ye yaptığı SelectAd çağrısına eklenmelidir:

• Accept-Language
• User-Agent
• IP adresi

Meta veriler SFE'ye gönderilirken gRPC, User-Agent başlığını değiştirebileceğinden 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, gRPC istemcisi ile Node'da Express kullanılarak meta verilerin 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 düzenlenen çok satıcılı açık artırma

Sunucu tarafından düzenlenen çok satıcılı açık artırma yürüten ü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ıtta, bileşen satıcı reklam hizmetlerine gönderilen yeniden şifrelenmiş bileşen açık artırması yükleri yer alır. 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çıklayıcıya göz atın.

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

B&A açık artırması sona erdikten sonra şifrelenmiş açık artırma sonucu SAS'a döndürülür ve SAS, 2. adımda sayfadan gelen birleştirilmiş açık artırma isteğine şifrelenmiş açık artırma sonucuyla yanıt verir. Sayfaya verilen SAS yanıtında, şifrelenmiş açık artırma sonucunun base64url kodlu SHA-256 karması, Ad-Auction-Result yanıt başlığında ayarlanır. Bu karma, istemcideki açık artırma tamamlandığında tarayıcı tarafından yükü doğrulamak için kullanılır.

Base64 kodlamasıyla SHA-256 karması oluşturma işlemi Node'da aşağıdaki gibi görünür:

import { createHash } from 'crypto';

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

Yanıt üstbilgisine karma 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 yanıt olduğundan bağlamsal açık artırma sonucu da yanıta dahil edilir.

Üst bilgiyi tekrarlayarak veya karmaları ayırarak Ad-Auction-Result öğesine birden fazla karma ekleyebilirsiniz. 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ı sunucusu koduna bakın.

Açık artırmayı tamamlamak için runAdAuction() adlı restoranı arayın

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

// 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 farklılık gösterir.

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

Tek satıcılı bir marka ve reklamveren açık artırması yürütmek 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 bir bayt dizisini kabul eder.

Bu çağrıya ilişkin bir örnek görmek için yerel test uygulamasının satıcı JavaScript koduna bakın.

Karma mod açık artırması

Hem cihaz üzerinde hem de B&A alıcılarının katılabileceği karma modlu bir B&A açık artırması yürütmek 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 bir 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 bir açık artırmada, hem üst düzey yapılandırma hem de bileşen yapılandırmaları için seller değeri aynıdır.

Bu çağrıya ilişkin bir örnek 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 düzenlenen çok satıcılı bir açık artırma yürüten üst düzey bir satıcıysanız her bileşen satıcı, B&A açık artırma sonucunu ve cihazdaki 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ıya ilişkin bir örnek 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

• Daha ayrıntılı bilgi için GitHub'daki aşağıdaki açıklayıcı metinlere göz atın:
  • Chrome'da B&A API'si
  • B&A sistem tasarımı
  • B&A çok satıcılı açık artırması
  • B&A karma modlu açık artırması
• Web için B&A mimarisi hakkında daha fazla bilgi edinin.
• Uçtan uca yerel test codelab'ini uygulayarak B&A ile Protected Audience'ı deneyin.

Sorularınız mı var?

• Teklif verme ve açık artırma hizmetleriyle ilgili bir sorunuz varsa B&A Services deposunda bir sorun açın.