Mengintegrasikan dengan B&A sebagai penjual

Layanan Bidding dan Lelang (B&A) adalah serangkaian layanan untuk pembeli dan penjual iklan yang berjalan di Trusted Execution Environment (TEE) untuk memfasilitasi lelang Protected Audience (PA). Panduan developer ini menjelaskan cara penjual dapat berintegrasi dengan lelang PA Chrome untuk B&A.

Panduan

Alur integrasi penjual tempat kode JavaScript mendapatkan payload lelang B&A yang dikirim ke SAS, dan SAS meneruskan permintaan ke Front-End Penjual (SFE). SFE menampilkan hasil yang harus diteruskan SAS ke browser, dan kode JavaScript penjual memanggil runAdAuction

Langkah-langkahnya dapat dirangkum sebagai berikut:

  1. Panggil getInterestGroupAdAuctionData() untuk mendapatkan payload terenkripsi dari browser
  2. Panggil fetch('https://your-ad-server.example') dan kirim permintaan lelang terpadu dengan payload terenkripsi ke SAS Anda
  3. Panggil operasi SelectAd() SFE dari SAS untuk menjalankan lelang B&A
  4. Menampilkan hasil lelang B&A ke halaman beserta hash respons
  5. Panggil runAdAuction() di browser untuk menjalankan lelang PA penjual tunggal, mode campuran, atau multi-penjual, dan teruskan hasil lelang B&A sisi server ke panggilan

Mendapatkan data lelang iklan terenkripsi

Diagram panduan yang sama dengan langkah pertama yang ditandai, yaitu saat kode JavaScript penjual memanggil getInterestGroupAdAuctionData

Untuk mendapatkan data yang diperlukan guna menjalankan lelang B&A sisi server, kode JavaScript penjual di halaman penayang memanggil navigator.getInterestGroupAdAuctionData().

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;
Kolom Deskripsi
seller Wajib diisi. Asal penjual yang menjalankan lelang. Nilai ini harus cocok dengan nilai seller dalam panggilan runAdAuction() nanti.
requestSize Opsional. Menetapkan ukuran payload maksimum dari semua data pembeli. Lihat bagian ukuran permintaan dalam penjelasan untuk mempelajari lebih lanjut.
perBuyerConfig Opsional. Menetapkan konfigurasi untuk setiap pembeli, dan juga mengontrol pembeli mana yang berpartisipasi dalam lelang B&A.

Jika asal pembeli tercantum dalam perBuyerConfig, hanya data grup minat pembeli tersebut yang disertakan dalam payload. Jika tidak ada pembeli yang tercantum di perBuyerConfig, semua grup minat pengguna akan disertakan dalam payload.
targetSize Opsional jika requestSize ditetapkan. Wajib jika asal pembeli ditetapkan di perBuyerConfig, tetapi requestSize tidak ditetapkan.

Menetapkan ukuran payload maksimum data pembeli tersebut. Lihat bagian ukuran permintaan dalam penjelasan untuk mempelajari lebih lanjut.
coordinatorOrigin Opsional, tetapi pada akhirnya akan diperlukan. Jika tidak ditetapkan, setelan defaultnya adalah https://publickeyservice.pa.gcp.privacysandboxservices.com.

Menetapkan koordinator yang akan digunakan untuk mengambil kunci guna mengenkripsi payload. Lihat bagian koordinator dalam penjelasan untuk mempelajari lebih lanjut.

Saat panggilan dilakukan, browser membaca grup minat pembeli yang tercantum di perBuyerConfig, dan mengenkripsi data pembeli. Data pembeli ini berisi informasi lintas situs yang akan digunakan untuk bidding, dan tidak dapat didekripsi di luar TEE. Untuk pengoptimalan payload, hanya nama grup minat, kunci sinyal bidding tepercaya, dan sinyal browser yang disertakan dalam payload.

Dalam objek data lelang iklan yang ditampilkan oleh panggilan getInterestGroupAdAuctionData(), string requestId dan array byte request terenkripsi tersedia.

Screenshot Chrome DevTools yang menampilkan permintaan dan ID permintaan yang tersedia dalam data lelang iklan

String requestId akan digunakan nanti saat runAdAuction() dipanggil untuk menyelesaikan lelang di browser. Payload request terenkripsi dikirim ke Layanan Iklan Penjual sebagai bagian dari permintaan lelang terpadu.

Untuk melihat contoh panggilan ini, lihat kode JavaScript penjual dari aplikasi pengujian lokal.

Mengirim permintaan lelang terpadu ke SAS

Diagram panduan yang sama dengan langkah kedua yang ditandai, yaitu saat kode JavaScript penjual mengirim permintaan lelang terpadu ke SAS

Permintaan lelang terpadu adalah permintaan yang berisi payload lelang kontekstual teks biasa dan payload lelang B&A PA. Payload lelang B&A PA adalah data request terenkripsi yang dihasilkan browser dalam panggilan getInterestGroupAdAuctionData(). Permintaan ini dikirim ke SAS, tempat lelang kontekstual dan lelang B&A PA diatur.

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

Untuk mengirim permintaan ke SAS, panggilan fetch() dilakukan dari halaman:

  • Panggilan harus menyertakan opsi adAuctionHeaders: true, yang memberi sinyal kepada browser untuk memverifikasi respons panggilan ini di lain waktu saat runAdAuction() dipanggil untuk menyelesaikan lelang di browser.
  • Asal permintaan pengambilan harus cocok dengan asal seller yang diberikan ke panggilan getInterestGroupAdAuctionData() dan runAdAuction().

Isi panggilan berisi:

  1. Payload lelang kontekstual teks biasa yang akan digunakan oleh SAS untuk menjalankan lelang kontekstual.
  2. Payload lelang Protected Audience terenkripsi yang akan dikirim ke SFE oleh SAS untuk menjalankan lelang B&A sisi server.

Untuk melihat contoh panggilan ini, lihat kode JavaScript penjual dari aplikasi pengujian lokal.

Encoding dan decoding base64

Payload request terenkripsi yang ditampilkan dari panggilan getInterestGroupAdAuctionData() adalah instance Uint8Array, yang merupakan jenis data yang tidak dapat ditangani JSON. Untuk mengirim array byte dalam format JSON, Anda dapat menerapkan encoding base64 ke data biner untuk mengonversinya menjadi string.

API browser JavaScript menyediakan fungsi atob() dan btoa() di window yang mengonversi antara data biner dan string ASCII yang dienkode base64. (atob berarti ASCII ke biner, dan btoa berarti biner ke ASCII).

Panggil btoa() untuk mengenkode data biner ke dalam string berenkode base64 yang terlihat seperti berikut:

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

Hasil lelang B&A terenkripsi yang ditampilkan dari panggilan fetch ini juga dalam encoding base64, sehingga Anda perlu mendekodenya kembali ke data biner. Panggil atob() untuk mendekode string ASCII yang dienkode base64 menjadi data biner:

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

Namun, string yang dienkode base64 biasanya sekitar 33% lebih besar daripada data asli. Jika Anda menginginkan peningkatan latensi lebih lanjut, gunakan format selain JSON untuk mengirim data biner.

Memanggil SelectAd SFE untuk menjalankan lelang B&A

Diagram panduan yang sama dengan langkah ketiga yang ditandai, yaitu saat SAS mengirimkan permintaan SelectAd ke SFE, dan SFE menjalankan lelang B&A

Setelah Layanan Iklan Penjual menerima permintaan lelang terpadu dari halaman, lelang kontekstual akan berjalan terlebih dahulu untuk menentukan pemenang lelang kontekstual dan mengumpulkan sinyal pembeli yang akan diteruskan ke lelang B&A PA. Kemudian, lelang B&A dimulai dengan memanggil operasi SelectAd SFE dari SAS dengan payload permintaan. Perhatikan bahwa beberapa metadata dari permintaan halaman ke SAS di langkah #2 diteruskan ke SFE.

Membuat payload SelectAdRequest

Payload permintaan panggilan SelectAd dapat dibuat seperti berikut:

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

Perhatikan bahwa jika data lelang iklan terenkripsi dari browser dienkode base64, data tersebut harus didekode kembali menjadi data biner jika permintaan ke SFE dikirim menggunakan gRPC. Jika permintaan dikirim menggunakan HTTP, data lelang iklan terenkripsi dapat tetap dalam bentuk yang dienkode base64.

Untuk melihat kolom lain yang ditentukan dalam permintaan SelectAd, lihat definisi proto SelectAdRequest.

Menetapkan kolom penjual tingkat teratas untuk lelang mode campuran dan komponen

Jika penjual menjalankan lelang mode campuran atau berpartisipasi sebagai penjual komponen dalam lelang multi-penjual, kolom top_level_seller harus ditentukan dalam permintaan.

Jika Anda adalah penjual mode campuran, nilai top_level_seller adalah asal Anda:

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

Jika Anda adalah penjual komponen, nilai top_level_seller adalah penjual tingkat teratas lelang multi-penjual:

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

Memanggil SelectAd SFE

Panggilan ke SFE dari SAS dapat dilakukan dengan gRPC atau HTTP.

Panggilan gRPC

Permintaan gRPC ke SFE terlihat seperti berikut menggunakan Express di Node dengan klien gRPC:

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

Definisi proto untuk klien SFE dapat ditemukan di repositori aplikasi pengujian lokal.

Panggilan HTTP ke proxy Envoy

Permintaan POST HTTP ke SFE dikirim ke jalur /v1/selectAd, dan terlihat seperti berikut:

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

Meneruskan metadata

Metadata berikut dari panggilan halaman ke SAS harus ditambahkan ke panggilan SelectAd SAS ke SFE:

Saat dikirim ke SFE, metadata harus menggunakan header non-standar berikut karena gRPC dapat mengubah header User-Agent:

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

Berikut adalah contoh cara meneruskan metadata menggunakan Express di Node dengan klien gRPC:

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

Berikut adalah contoh cara meneruskan metadata menggunakan panggilan HTTP:

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

Lelang multi-penjual yang diatur server

Jika Anda adalah penjual tingkat teratas yang menjalankan lelang multi-penjual yang diorkestrasi server, panggilan GetComponentAuctionCiphertexts akan dilakukan ke SFE sebelum panggilan SelectAd dilakukan. Respons berisi payload lelang komponen yang dienkripsi ulang yang dikirim ke layanan iklan penjual komponen. Hasil lelang iklan komponen B&A yang ditampilkan disediakan ke panggilan SelectAd SFE penjual tingkat atas.

Lihat penjelasan multi-penjual di GitHub untuk mempelajari lebih lanjut.

Menampilkan hasil lelang B&A ke halaman

Diagram panduan yang sama dengan langkah keempat yang ditandai, yaitu saat SAS mengirim hasil lelang SelectAd kembali ke browser

Setelah lelang B&A selesai, hasil lelang terenkripsi akan ditampilkan ke SAS, dan SAS akan merespons permintaan lelang terpadu dari halaman di langkah #2 dengan hasil lelang terenkripsi. Dalam respons SAS ke halaman, hash SHA-256 yang dienkode base64url dari hasil lelang terenkripsi ditetapkan di header respons Ad-Auction-Result. Hash ini digunakan oleh browser untuk memverifikasi payload saat menyelesaikan lelang di klien.

Membuat hash SHA-256 dengan encoding base64 terlihat seperti berikut di Node:

import { createHash } from 'crypto';

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

Melampirkan hash di header respons dan menampilkan hasil lelang ke halaman akan terlihat seperti berikut:

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()
    });
  });
})

Karena ini adalah respons terhadap permintaan lelang terpadu yang dibuat dari halaman di langkah #2, hasil lelang kontekstual juga disertakan dalam respons.

Beberapa hash dapat disertakan dalam Ad-Auction-Result dengan mengulangi header atau memisahkan hash. Dua header respons berikut setara:

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

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

Untuk melihat contoh panggilan ini, lihat kode server penjual aplikasi pengujian lokal.

Panggil runAdAuction() untuk menyelesaikan lelang

Diagram panduan yang sama dengan langkah kelima yang ditandai, yaitu saat kode JavaScript sisi klien menjalankan lelang dan memberikan respons server

Respons lelang terpadu yang ditampilkan dari SAS menyertakan hasil lelang B&A terenkripsi. Payload ini diteruskan ke panggilan runAdAuction() untuk menyelesaikan lelang di browser. Nilai requestId dari panggilan getInterestGroupAdAuctionData() di langkah #1 juga diteruskan ke lelang.

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

Struktur konfigurasi lelang yang diteruskan ke panggilan runAdAuction() berbeda-beda berdasarkan konfigurasi lelang yang dipilih oleh penjual.

Lelang penjual tunggal

Untuk menjalankan lelang B&A satu penjual, konfigurasi lelang panggilan runAdAuction() dibuat seperti berikut:

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

Kolom requestId menerima requestId yang ditampilkan oleh panggilan getInterestGroupAdAuctionData(). Kolom serverResponse menerima array byte lelang B&A yang berjalan di langkah #3.

Untuk melihat contoh panggilan ini, lihat kode JavaScript penjual dari aplikasi pengujian lokal.

Lelang mode campuran

Untuk menjalankan lelang B&A mode campuran tempat pembeli di perangkat dan B&A dapat berpartisipasi, konfigurasi lelang panggilan runAdAuction() dibuat seperti berikut:

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
      ],
    },
  ]
});

Untuk memfasilitasi lelang mode campuran, hasil lelang B&A dan konfigurasi lelang di perangkat diteruskan ke kolom componentAuctions. Dalam lelang mode campuran, nilai seller sama untuk konfigurasi tingkat atas dan konfigurasi komponen.

Untuk melihat contoh panggilan ini, lihat kode JavaScript penjual dari aplikasi pengujian lokal.

Lelang multi-penjual

Jika Anda adalah penjual tingkat teratas yang menjalankan lelang multi-penjual yang diorkestrasi perangkat, setiap penjual komponen akan mengirimkan hasil lelang B&A dan konfigurasi lelang di perangkat.

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',
    }
  ]
})

Untuk melihat contoh panggilan ini, lihat kode JavaScript penjual dari aplikasi pengujian lokal.

Langkah berikutnya

Setelah membaca panduan ini, Anda dapat melakukan langkah-langkah berikut:

Pelajari lebih lanjut

Ada pertanyaan?