الدمج مع B&A بصفتك بائعًا

خدمات عروض الأسعار والمزادات (B&A) هي مجموعة من الخدمات لمشتري الإعلانات وبائعيها التي تعمل في بيئة تنفيذ موثوقة (TEE) لتسهيل مزاد الجمهور المحمي (PA). يشرح دليل المطوّرين هذا كيفية دمج البائع مع مزاد إعلانات المنتجات داخل المتجر في Chrome لميزة "الإعلانات المتجاوبة على شبكة البحث".

ملاحظة: يفترض هذا الدليل أنّ القارئ يفهم مسار "الجمهور المحمي على الجهاز". ننصحك أيضًا بقراءة دليل بنية "الإعلانات الصورية" قبل قراءة هذا الدليل.

جولة تفصيلية

يمكن تلخيص الخطوات على النحو التالي:

1. اتصل برقم getInterestGroupAdAuctionData() للحصول على الحمولة المشفّرة من المتصفّح.
2. اتصل برقم ‎fetch('https://your-ad-server.example') وأرسِل طلب المزاد الموحّد مع الحمولة المشفّرة إلى SAS.
3. استدعاء عملية SelectAd() في SFE من SAS لتنفيذ مزاد B&A
4. عرض نتيجة مزاد B&A على الصفحة مع الرمز المميّز للردّ
5. استدعاء runAdAuction() في المتصفّح لإجراء مزاد إعلانات ديناميكية على شبكة البحث من بائع واحد أو في وضع مختلط أو من بائعين متعدّدين، وإدخال نتيجة مزاد الإعلانات الديناميكية على شبكة البحث من جهة الخادم إلى الاستدعاء

الحصول على بيانات مشفّرة لمزاد الإعلانات

للحصول على البيانات اللازمة لتشغيل مزاد B&A من جهة الخادم، يُطلِب رمز JavaScript الخاص بالبائع على صفحة الناشر 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	Optional. تُستخدَم لضبط الحد الأقصى لحجم الحمولة لجميع بيانات المشترين. اطّلِع على قسم حجم الطلب في الشرح للحصول على مزيد من المعلومات.
perBuyerConfig	Optional. تُستخدَم لضبط الإعدادات لكل مشترٍ، كما تتحكّم في المشترين الذين يشاركون في مزاد B&A. إذا كانت مصادر المشترين مُدرَجة في perBuyerConfig، يتم تضمين بيانات مجموعات اهتمامات المشترين هذه فقط في الحمولة. إذا لم يتم إدراج أيّ مشترين في perBuyerConfig، يتمّ تضمين جميع مجموعات الاهتمامات للمستخدم في الحمولة.
targetSize	اختيارية في حال ضبط requestSize سمة مطلوبة إذا تم ضبط مصدر مشتري في perBuyerConfig ولكن لم يتم ضبط requestSize. لضبط الحد الأقصى لحجم الحمولة لبيانات هذا المشتري. اطّلِع على قسم حجم الطلب في الشرح للحصول على مزيد من المعلومات.
coordinatorOrigin	اختيارية، ولكن ستصبح مطلوبة في النهاية. يتم ضبط القيمة تلقائيًا على https://publickeyservice.pa.gcp.privacysandboxservices.com في حال عدم ضبطها. تُستخدَم لضبط المُنسق الذي سيتم استخدامه للحصول على مفتاح تشفير الحمولة. اطّلِع على قسم المنسق في الشرح للحصول على مزيد من المعلومات.

عند إجراء المكالمة، يقرأ المتصفّح مجموعات الاهتمامات للمشترين المدرَجين في perBuyerConfig، ويشفّر بيانات المشترين. تحتوي بيانات المشترين هذه على معلومات من مواقع إلكترونية متعددة لاستخدامها في عروض الأسعار، ولا يمكن فك تشفيرها خارج بيئة التشغيل المخصّصة للبرامج الحسّاسة. لتحسين الحمولة، لا يتم تضمين سوى اسم مجموعة الاهتمامات ومفاتيح إشارات عروض الأسعار الموثوق بها وإشارات المتصفّح في الحمولة.

في عنصر بيانات مزاد الإعلانات الذي يعرضه طلب getInterestGroupAdAuctionData()، تتوفّر سلسلة requestId ومصفوفة request بايت مشفّرة.

يتم استخدام سلسلة requestId لاحقًا عند استدعاء runAdAuction() لإنهاء المزاد في المتصفّح. يتم إرسال الحمولة المشفّرة request إلى "خدمة إعلانات البائع" كجزء من طلب المزاد الموحّد.

للاطّلاع على مثال على هذا الطلب، يمكنك الاطّلاع على رمز JavaScript الخاص بالبائع في تطبيق الاختبار على الجهاز.

إرسال طلب المزاد الموحّد إلى SAS

طلب المزاد الموحّد هو طلب يحتوي على الحمولة النصية للمزاد السياقي وحمولة مزاد الإعلانات المتجاوبة على شبكة البحث. حمولة مزاد B&A في "الإعلانات الصورية على شبكة البحث" هي بيانات request المشفّرة التي أنشأها المتصفّح في طلب getInterestGroupAdAuctionData(). يتم إرسال هذا الطلب إلى SAS، حيث يتمّ تنسيق المزاد السياقي ومزاد 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. حمولة مزاد Protected Audience المشفَّرة التي سيتم إرسالها إلى SFE من خلال SAS لتنفيذ مزاد B&A من جهة الخادم

للاطّلاع على مثال على هذا الطلب، يمكنك الاطّلاع على رمز JavaScript الخاص بالبائع في تطبيق الاختبار على الجهاز.

ترميز Base64 وفك ترميزه

إنّ الحمولة المشفَّرة request التي يتم إرجاعها من طلب getInterestGroupAdAuctionData() هي مثيل Uint8Array، وهو نوع بيانات لا يمكن لـ JSON معالجته. لإرسال صفيف البايت بتنسيق JSON، يمكنك تطبيق ترميز base64 على البيانات الثنائية لتحويلها إلى سلسلة.

توفّر واجهة برمجة تطبيقات JavaScript للمتصفح الدالتَين atob() وbtoa() في window اللتين تحوّلان بين البيانات الثنائية وسلسلة ASCII المُرمّزة باستخدام Base64. (atob تعني تحويل ASCII إلى ثنائي، وbtoa تعني تحويل ثنائي إلى ASCII).

تبدو طريقة الاتصال btoa() لتشفير البيانات الثنائية في سلسلة بترميز base64 على النحو التالي:

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

إنّ نتيجة مزاد B&A المشفّرة التي تم عرضها من طلب fetch هذا تكون أيضًا بترميز base64، لذا عليك فك تشفيرها مرة أخرى إلى بيانات ثنائية. استخدِم atob() لفك ترميز سلسلة ASCII المُشفّرة باستخدام base64 إلى بيانات ثنائية:

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

ومع ذلك، تكون السلسلة المشفّرة بترميز base64 عادةً أكبر بنسبة% 33 تقريبًا من البيانات الأصلية. إذا أردت تحسين وقت الاستجابة بشكل أكبر، استخدِم تنسيقًا آخر غير JSON لإرسال البيانات الثنائية.

اتصل بـ SelectAd في SFE لتنفيذ مزاد 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)
};

يُرجى العِلم أنّه إذا تم ترميز بيانات مزاد الإعلانات المشفَّرة من المتصفّح باستخدام ترميز base64، يجب فك ترميزها مرة أخرى إلى بيانات ثنائية في حال إرسال الطلب إلى SFE باستخدام gRPC. إذا تم إرسال الطلب باستخدام بروتوكول HTTP، يمكن أن تظل بيانات مزاد الإعلانات المشفّرة في شكلها المشفَّر بترميز base64.

للاطّلاع على الحقول الأخرى المحدّدة في طلب SelectAd، اطّلِع على تعريف proto لـ 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
});

يمكن العثور على تعريف proto لخدمة 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 إلى SFE قبل إجراء طلب SelectAd. يحتوي الردّ على بيانات أساسية تمت إعادة تشفيرها لمزاد المكوّنات التي يتم إرسالها إلى خدمات الإعلانات الخاصة ببائع المكوّنات. يتم توفير نتائج مزاد الإعلانات للعنصرَين "الإعلانات الصورية" و"الإعلانات المتجاوبة" المعروضة في طلب SelectAd لـ SFE الخاص بالبائع من المستوى الأعلى.

اطّلِع على الشرح المفصّل عن ميزة "الحسابات المتعددة البائعين" على GitHub للتعرّف على مزيد من المعلومات.

عرض نتيجة مزاد B&A على الصفحة

بعد انتهاء مزاد B&A، يتم عرض نتيجة المزاد المشفّرة في SAS، ويستجيب SAS لطلب المزاد الموحّد من الصفحة في الخطوة 2 مع نتيجة المزاد المشفّرة. في استجابة SAS للصفحة، يتمّ ضبط تجزئة SHA-256 بترميز 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.

للاطّلاع على مثال على هذا الطلب، يمكنك الاطّلاع على رمز JavaScript الخاص بالبائع في تطبيق الاختبار على الجهاز.

المزاد المختلط

لتشغيل مزاد 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 متطابقة لكلّ من الإعدادات على مستوى أعلى المستويات وإعدادات المكوّنات.

للاطّلاع على مثال على هذا الطلب، يمكنك الاطّلاع على رمز JavaScript الخاص بالبائع في تطبيق الاختبار على الجهاز.

مزاد يضمّ بائعين متعدّدين

إذا كنت بائعًا من المستوى الأعلى وتُجري مزادًا متعدّد البائعين يتم تنظيمه على مستوى الجهاز، يُرسِل كل بائع مكوّنات نتيجة مزاد 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',
    }
  ]
})

للاطّلاع على مثال على هذا الطلب، يمكنك الاطّلاع على رمز JavaScript الخاص بالبائع في تطبيق الاختبار على الجهاز.

الخطوات التالية

بعد قراءة هذا الدليل، يمكنك اتّخاذ الخطوات التالية:

مزيد من المعلومات

• لفهم هذه الميزة بشكل أفضل، يمكنك الاطّلاع على المراجع التوضيحية التالية على GitHub:
  • B&A API في Chrome
  • تصميم نظام B&A
  • مزاد متعدد البائعين في "إعلانات Google" و"إعلانات شبكة البحث"
  • مزاد "الإعلانات الصورية" و"الإعلانات المتجاوبة على شبكة البحث" بالوضع المختلط
• مزيد من المعلومات حول بنية B&A للويب
• جرِّب ميزة "الجمهور المحمي" مع ميزة "الاختبار التجريبي" باتّباع الدرس التطبيقي حول ترميز "الاختبار المحلي الشامل".

هل لديك أسئلة؟

• إذا كان لديك سؤال حول خدمات عروض الأسعار والمزادات، يمكنك فتح مشكلة في مستودع خدمات عروض الأسعار والمزادات.
• إذا كان لديك سؤال عن "مبادرة حماية الخصوصية" بشكل عام، يمكنك فتح مشكلة في مستودع privacy-sandbox-dev-support.