به عنوان فروشنده با B&A ادغام شوید

خدمات مناقصه و حراج (B&A) مجموعه ای از خدمات برای خریداران و فروشندگان آگهی است که در یک محیط اجرای معتمد (TEE) اجرا می شود تا حراج مخاطب محافظت شده (PA) را تسهیل کند. این راهنمای توسعه‌دهنده توضیح می‌دهد که چگونه یک فروشنده می‌تواند با حراج Chrome PA برای B&A یکپارچه شود.

توجه: این راهنما فرض می‌کند که خواننده جریان مخاطب محافظت شده روی دستگاه را درک می‌کند. همچنین خواندن راهنمای معماری B&A قبل از مطالعه این راهنما به شدت توصیه می شود.

قدم زدن

مراحل را می توان به صورت زیر خلاصه کرد:

1. برای دریافت بار رمزگذاری شده از مرورگر، با getInterestGroupAdAuctionData() تماس بگیرید.
2. با fetch('https://your-ad-server.example') تماس بگیرید و درخواست حراج یکپارچه را با محموله رمزگذاری شده به SAS خود ارسال کنید.
3. برای اجرای حراج B&A، عملیات SelectAd() SFE را از SAS خود فراخوانی کنید
4. نتیجه حراج B&A را به همراه هش پاسخ به صفحه برگردانید
5. برای اجرای حراج PA تک‌فروشنده، ترکیبی یا چند فروشنده‌ای در مرورگر، runAdAuction() را فراخوانی کنید و نتیجه حراج B&A سمت سرور را به تماس منتقل کنید.

داده های حراج تبلیغات رمزگذاری شده را دریافت کنید

برای دریافت اطلاعات مورد نیاز برای اجرای حراج B&A سمت سرور، کد جاوا اسکریپت فروشنده در صفحه ناشر، 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;

میدان	توضیحات
seller	مورد نیاز . مبدا فروشنده که حراج را اجرا می کند. این مقدار باید با مقدار seller در فراخوانی runAdAuction() بعدا مطابقت داشته باشد.
requestSize	اختیاری حداکثر اندازه بار تمام داده‌های خریدار را تنظیم می‌کند. برای اطلاعات بیشتر به بخش اندازه درخواست توضیح دهنده مراجعه کنید.
perBuyerConfig	اختیاری تنظیمات را برای هر خریدار تنظیم می کند و همچنین کنترل می کند که چه خریدارانی در حراج B&A شرکت می کنند. اگر مبدا خریدار در perBuyerConfig فهرست شده باشد، فقط آن داده‌های گروه علاقه خریدار در بارگذاری گنجانده می‌شود. اگر هیچ خریداری در perBuyerConfig فهرست نشده باشد، همه گروه‌های علاقه‌مند کاربر در محموله گنجانده می‌شوند.
targetSize	اگر requestSize تنظیم شده باشد اختیاری است . اگر مبدأ خریدار در perBuyerConfig تنظیم شده باشد، اما requestSize تنظیم نشده باشد، الزامی است . حداکثر اندازه محموله داده های آن خریدار را تنظیم می کند. برای اطلاعات بیشتر به بخش اندازه درخواست توضیح دهنده مراجعه کنید.
coordinatorOrigin	اختیاری است ، اما در نهایت مورد نیاز خواهد بود. زمانی که تنظیم نشده باشد به صورت پیش‌فرض روی https://publickeyservice.pa.gcp.privacysandboxservices.com قرار می‌گیرد. هماهنگ کننده را برای واکشی کلید برای رمزگذاری محموله تنظیم می کند. برای کسب اطلاعات بیشتر به بخش هماهنگ کننده توضیح دهنده مراجعه کنید.

هنگامی که تماس برقرار می شود، مرورگر گروه های علاقه مندی خریداران فهرست شده در perBuyerConfig را می خواند و داده های خریدار را رمزگذاری می کند. این داده‌های خریدار حاوی اطلاعات بین‌سایتی برای استفاده در مناقصه است و خارج از TEE قابل رمزگشایی نیست. برای بهینه‌سازی محموله، فقط نام گروه علاقه‌مند، کلیدهای سیگنال پیشنهادی قابل اعتماد و سیگنال‌های مرورگر در محموله گنجانده شده است.

در شیء داده مزایده آگهی که توسط فراخوانی getInterestGroupAdAuctionData() برگردانده شده است، رشته requestId و آرایه بایت request رمزگذاری شده در دسترس هستند.

رشته requestId بعداً زمانی که runAdAuction() فراخوانی می شود برای پایان دادن به حراج در مرورگر استفاده می شود. محموله request رمزگذاری شده به عنوان بخشی از درخواست حراج یکپارچه به سرویس آگهی فروشنده ارسال می شود.

برای مشاهده نمونه ای از این تماس، به کد جاوا اسکریپت فروشنده برنامه آزمایش محلی مراجعه کنید.

درخواست حراج یکپارچه را به SAS ارسال کنید

یک درخواست حراج یکپارچه درخواستی است که حاوی محموله مزایده متنی متنی و محموله حراج PA B&A است. بار مزایده PA B&A داده های request رمزگذاری شده ای است که مرورگر در فراخوانی getInterestGroupAdAuctionData() ایجاد کرده است. این درخواست به SAS ارسال می شود، جایی که حراج متنی و حراج PA B&A هماهنگ شده است.

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

برای ارسال درخواست به SAS، یک فراخوان fetch() از صفحه انجام می شود:

• فراخوانی باید شامل گزینه adAuctionHeaders: true باشد، که به مرورگر سیگنال می‌دهد تا در زمان دیگری که runAdAuction() برای پایان حراج در مرورگر فراخوانی شود، پاسخ این تماس را تأیید کند.
• مبدا درخواست واکشی باید با مبدا seller ارائه شده برای فراخوانی های getInterestGroupAdAuctionData() و runAdAuction() مطابقت داشته باشد.

متن تماس شامل:

1. محموله حراج متنی ساده که باید توسط SAS برای اجرای حراج متنی استفاده شود.
2. محموله حراج مخاطب محافظت شده رمزگذاری شده برای اجرای حراج B&A سمت سرور توسط SAS به SFE ارسال می شود.

برای مشاهده نمونه ای از این تماس، به کد جاوا اسکریپت فروشنده برنامه آزمایش محلی مراجعه کنید.

کدگذاری و رمزگشایی Base64

بار request رمزگذاری شده که از فراخوانی getInterestGroupAdAuctionData() برگردانده شده است، نمونه‌ای از Uint8Array است که یک نوع داده است که JSON نمی‌تواند آن را مدیریت کند. برای ارسال آرایه بایت در فرمت JSON، می‌توانید یک رمزگذاری base64 روی داده‌های باینری اعمال کنید تا آن را به رشته تبدیل کنید.

API مرورگر جاوا اسکریپت توابع atob() و btoa() را در window ارائه می کند که بین داده های باینری و رشته ASCII کدگذاری شده با base64 تبدیل می شود. ( atob به معنی ASCII-to-binary و btoa به معنای باینری-to-ASCII است).

فراخوانی btoa() برای کدگذاری داده های باینری در یک رشته کدگذاری شده با base64 به شکل زیر است:

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

نتیجه مزایده B&A رمزگذاری شده که از این تماس fetch بازگردانده شده است نیز در یک کدگذاری base64 است، بنابراین باید آن را به داده‌های باینری رمزگشایی کنید. برای رمزگشایی رشته ASCII کدگذاری شده با base64 به داده های باینری، atob() را فراخوانی کنید:

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

با این حال، یک رشته رمزگذاری شده با base64 معمولاً حدود 33٪ بزرگتر از داده های اصلی است. اگر می‌خواهید تاخیر بیشتری داشته باشید، از قالبی غیر از JSON برای ارسال داده‌های باینری استفاده کنید.

برای اجرای حراج B&A با SelectAd SFE تماس بگیرید

هنگامی که سرویس آگهی فروشنده درخواست حراج یکپارچه را از صفحه دریافت کرد، حراج متنی ابتدا برای تعیین برنده حراج متنی و جمع‌آوری سیگنال‌های خریدار برای ارسال به حراج PA B&A اجرا می‌شود. سپس، حراج B&A با فراخوانی عملیات SelectAd SFE از SAS همراه با بار درخواست آغاز می شود. توجه داشته باشید که برخی از فراداده های درخواست صفحه به SAS در مرحله 2 به SFE ارسال می شود.

محموله SelectAdRequest را بسازید

بار درخواست تماس SelectAd می تواند به صورت زیر ساخته شود:

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

توجه داشته باشید که اگر داده‌های مزایده تبلیغات رمزگذاری‌شده از مرورگر با پایه ۶۴ کدگذاری شده بود، اگر درخواست به SFE با استفاده از gRPC ارسال شود، باید به داده‌های باینری رمزگشایی شوند. اگر درخواست با استفاده از HTTP ارسال شود، داده‌های مزایده تبلیغات رمزگذاری‌شده می‌توانند در فرم کدگذاری شده پایه ۶۴ خود باقی بمانند.

برای مشاهده سایر فیلدهای تعریف شده در درخواست SelectAd ، به تعریف اولیه SelectAdRequest مراجعه کنید.

فیلد فروشنده سطح بالا را برای مزایده های ترکیبی و کامپوننت تنظیم کنید

اگر فروشنده در حال اجرای حراج ترکیبی است یا به عنوان فروشنده جزء در یک حراج چند فروشنده شرکت می کند، باید قسمت top_level_seller در درخواست تعریف شود.

اگر فروشنده حالت مختلط هستید، مقدار top_level_seller مبدأ شما است:

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

اگر فروشنده کامپوننت هستید، مقدار top_level_seller فروشنده سطح بالای حراج چند فروشنده است:

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

با SelectAd SFE تماس بگیرید

تماس SFE از SAS را می توان با gRPC یا HTTP انجام داد.

تماس gRPC

درخواست gRPC به SFE با استفاده از Express در Node با مشتری 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
});

تعریف اولیه برای مشتری SFE را می توان در مخزن برنامه آزمایشی محلی یافت.

تماس HTTP به پروکسی Envoy

درخواست HTTP POST به SFE به مسیر /v1/selectAd ارسال می‌شود و به شکل زیر است:

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

فراداده فوروارد

فراداده زیر از تماس صفحه با SAS باید به تماس SelectAd SAS به SFE اضافه شود:

• Accept-Language
• User-Agent
• آدرس IP

هنگامی که ابرداده ها به SFE ارسال می شوند، باید از هدرهای غیر استاندارد زیر استفاده کنند زیرا gRPC ممکن است هدر User-Agent را تغییر دهد:

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

در زیر مثالی از نحوه ارسال ابرداده با استفاده از Express در Node با کلاینت 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);
})

در زیر نمونه ای از نحوه ارسال ابرداده با استفاده از تماس 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)
  });
})

حراج چند فروشنده با هماهنگی سرور

اگر فروشنده سطح بالایی هستید که یک مزایده چند فروشنده هماهنگ شده توسط سرور را اجرا می کنید، تماس GetComponentAuctionCiphertexts قبل از برقراری تماس SelectAd با SFE برقرار می شود. پاسخ حاوی محموله‌های مزایده مؤلفه‌های رمزگذاری‌شده مجدد است که به خدمات آگهی فروشنده مؤلفه ارسال می‌شود. نتایج مزایده آگهی B&A برگردانده شده به تماس SelectAd SFE فروشنده سطح بالا ارائه می شود.

برای کسب اطلاعات بیشتر به توضیح چند فروشنده در GitHub مراجعه کنید.

نتیجه حراج B&A را به صفحه برگردانید

پس از پایان حراج B&A، نتیجه حراج رمزگذاری شده به SAS بازگردانده می شود و SAS به درخواست حراج یکپارچه از صفحه در مرحله شماره 2 با نتیجه حراج رمزگذاری شده پاسخ می دهد. در پاسخ SAS به صفحه، هش SHA-256 -Encoded -base64url از نتیجه حراج رمزگذاری شده در سرصفحه پاسخ Ad-Auction-Result تنظیم شده است. این هش توسط مرورگر برای تأیید بار در هنگام اتمام حراج در مشتری استفاده می شود.

ایجاد یک هش SHA-256 با رمزگذاری base64 به شکل زیر در Node است:

import { createHash } from 'crypto';

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

پیوست کردن هش در هدر پاسخ و برگرداندن نتیجه حراج به صفحه به صورت زیر است:

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

از آنجایی که این پاسخی است به درخواست حراج یکپارچه ارائه شده از صفحه در مرحله #2 ، نتیجه حراج متنی نیز در پاسخ گنجانده شده است.

با تکرار سرصفحه یا جدا کردن هش‌ها، می‌توان چندین هش را در Ad-Auction-Result گنجاند. دو سرصفحه پاسخ زیر معادل هستند:

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

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

برای مشاهده نمونه ای از این تماس، کد سرور فروشنده برنامه آزمایش محلی را ببینید.

برای تکمیل حراج با runAdAuction() تماس بگیرید

پاسخ حراج یکپارچه که از SAS برگردانده شده است شامل نتیجه حراج B&A رمزگذاری شده است. این محموله به فراخوانی runAdAuction() ارسال می شود تا حراج در مرورگر به پایان برسد. مقدار requestId از فراخوانی getInterestGroupAdAuctionData() در مرحله شماره 1 نیز به حراج داده می شود.

// 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() بر اساس پیکربندی حراج انتخاب شده توسط فروشنده متفاوت است.

حراج تک فروشنده

برای اجرای یک حراج B&A تک فروشنده، پیکربندی حراج فراخوانی runAdAuction() به صورت زیر ساخته شده است:

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

فیلد requestId requestId می‌پذیرد که با فراخوانی getInterestGroupAdAuctionData() بازگردانده شده است. فیلد serverResponse آرایه بایتی از حراج B&A را می‌پذیرد که در مرحله 3 اجرا شد.

برای مشاهده نمونه ای از این تماس، به کد جاوا اسکریپت فروشنده برنامه آزمایش محلی مراجعه کنید.

حراج حالت مختلط

برای اجرای یک حراج B&A با حالت مختلط که در آن خریداران روی دستگاه و B&A می توانند شرکت کنند، پیکربندی حراج فراخوانی runAdAuction() به صورت زیر ساخته می شود:

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

برای تسهیل حراج حالت مختلط، نتیجه حراج B&A و پیکربندی حراج روی دستگاه به قسمت componentAuctions منتقل می‌شوند. در حراجی با حالت مختلط، ارزش seller برای پیکربندی سطح بالا و پیکربندی جزء یکسان است.

برای مشاهده نمونه ای از این تماس، به کد جاوا اسکریپت فروشنده برنامه آزمایش محلی مراجعه کنید.

حراج چند فروشنده

اگر فروشنده سطح بالایی هستید که یک حراج چند فروشنده تنظیم شده توسط دستگاه را اجرا می کنید، هر فروشنده جزء نتیجه حراج B&A و تنظیمات حراج روی دستگاه را ارسال می کند.

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

برای مشاهده نمونه ای از این تماس، به کد جاوا اسکریپت فروشنده برنامه آزمایش محلی مراجعه کنید.

مراحل بعدی

پس از مطالعه این راهنما، می توانید مراحل زیر را انجام دهید:

بیشتر بدانید

• برای درک عمیق تر، توضیح دهنده های زیر را در GitHub ببینید:
  • B&A API در کروم
  • طراحی سیستم B&A
  • حراج چند فروشنده B&A
  • حراج ترکیبی B&A
• درباره معماری B&A برای وب بیشتر بیاموزید
• با دنبال کردن کد لبه تست محلی End-to-End با B&A با مخاطب محافظت شده آزمایش کنید.

سوالی دارید؟

• اگر در مورد خدمات مزایده و مزایده سؤالی دارید، موضوعی را در مخزن خدمات B&A باز کنید .
• اگر در مورد Privacy Sandbox به طور کلی سؤالی دارید، یک مشکل را در مخزن privacy-sandbox-dev-support باز کنید .