إطلاق مزاد مستند إلى المتصفّح مع بائع واحد

يتضمّن هذا المستند نظرة عامة عالية المستوى حول إجراء مزاد باستخدام بيانات Protected Audience لبائع واحد، كما هو مستخدَم في الإصدار الحالي من Protected Audience API. يمكن تنفيذ مزاد يتضمّن بائعًا واحدًا كجزء من مزاد أكثر تعقيدًا يتضمّن بائعين متعدّدين. في هذه الحالة، يُشار إلى المزاد الذي يشارك فيه بائع واحد باسم "المزاد المكوّن"، والذي يمكن أن يقدّم مرشّحين للإعلانات إلى "المزاد الأعلى مستوى" الذي يشارك فيه عدة بائعين.

يمكنك الاطّلاع على دليل المطوّرين لمعرفة دورة الحياة الكاملة لواجهة Protected Audience API، والرجوع إلى شرح Protected Audience API للحصول على مناقشة مفصّلة حول كيفية إجراء البائعين للمزادات على الأجهزة.

ست مراحل لمزاد الإعلانات في Protected Audience API

1. يزور أحد المستخدمين موقعًا إلكترونيًا يعرض إعلانات.
2. ينفّذ رمز البائع navigator.runAdAuction(). تحدّد هذه السمة مساحة الإعلان المعروضة للبيع والجهات التي يمكنها تقديم عروض أسعار. على البائعين أيضًا تضمين نص برمجي يقيّم كل عرض سعر، scoreAd().
3. يتم تنفيذ رمز المشتري المدعو لإنشاء عرض سعر وعنوان URL لتصميم إعلان ذي صلة وبيانات أخرى. يمكن لبرنامج عروض الأسعار أن يطلب بيانات في الوقت الفعلي، مثل الميزانية المتبقية للحملة الإعلانية، من خدمة المفتاح/القيمة الخاصة بالمشتري.
4. يقيّم رمز البائع كل عرض سعر ويختار العرض الفائز. تستخدِم هذه المنطق قيمة عرض السعر وبيانات أخرى لعرض مدى ملاءمة عرض السعر. ويتم رفض الإعلانات التي لا يمكنها التفوق على الإعلان السياقي الفائز. يمكن للبائع استخدام خدمة المفتاح/القيمة الخاصة به للحصول على البيانات في الوقت الفعلي.
5. يتم عرض الإعلان الفائز كقيمة مبهمة، ويظهر في إطار مسوّر. ولن يتمكّن كل من البائع والناشر من الاطّلاع على هذه القيمة.
6. يتم إبلاغ البائع والمشترين الفائزين بالمزاد.

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

يبدأ البائعون مزاد الإعلانات، ويقيّمون الإعلانات المرشّحة باستخدام منطق مخصّص يتم توفيره كدالة scoreAd()، وهم مسؤولون عن إبلاغ أنفسهم والمشتري الفائز بنتائج المزاد. يمكن للبائعين أيضًا فرض قواعد الناشرين وفلترة جودة الإعلانات باستخدام وظيفة scoreAd().

قد يشير البائع إلى ما يلي:

• ناشرو المحتوى الذين يعملون لحسابهم الخاص لاستضافة محتوى إعلاني على مواقعهم الإلكترونية
• وسائط عرض إعلانات المورّدين (SSP) التي تعمل مع ناشر الإعلانات وتقدّم خدمات أخرى
• برامج نصية تابعة لجهات خارجية تعمل لصالح الناشرين من أجل إتاحة المشاركة في مزادات الإعلانات

المتطلبات الأساسية لإجراء مزاد

يحتاج البائع إلى تعريف دالتَي JavaScript لتنفيذ مزاد:

• ‫scoreAd()، الذي يقيّم المرشّحين للإعلان
• ‫reportResult()، الذي يتولّى إبلاغ البائع بنتيجة المزاد

يجب عرض هذه النصوص البرمجية من نقطة نهاية واحدة يملكها البائع.

scoreAd()

على البائع تحديد الدالة scoreAd() التي يتم عرضها من نقطة نهاية يملكها. يتم تحديد نقطة النهاية في إعدادات المزاد على النحو التالي: decisionLogicUrl. تتضمّن الدالة scoreAd() التوقيع التالي:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

مَعلمات scoreAd() هي:

• ‫adMetaData، وهي بيانات وصفية اختيارية حول تصميم الإعلان يقدّمها المشتري. هذا عنصر قابل للتسلسل بتنسيق JSON، ويجب أن يحدّده البائعون والمشترون ويتفقوا على بنيته.
• bid، وهي قيمة عددية تمثّل عرض السعر.
• ‫auctionConfig، وهو إعداد المزاد المستخدَم لتنفيذ المزاد.
• trustedScoringSignals، وهي إشارات تتم قراءتها في وقت المزاد من خادم المفتاح/القيمة الخاص بالبائع. ستستخدم المنصة renderUrl للإعلان المرشّح كمفتاح للبحث.
• ‫browserSignals، وهو عنصر ينشئه المتصفّح ويتضمّن معلومات يعرفها المتصفّح وقد يريد نص برمجي خاص بالمزاد تابع للبائع التحقّق منها.
• ‫directFromSellerSignals هو عنصر يمكن أن يحتوي على الحقول التالية: ** sellerSignals: يشبه auctionConfig.sellerSignals، ولكن يتم تمريره باستخدام آلية directFromSellerSignals. ** auctionSignals: مثل auctionConfig.auctionSignals، ولكن يتم تمريره باستخدام آلية directFromSellerSignals.

في ما يلي مثال على browserSignals. يُرجى العِلم أنّ renderUrl الإعلان المرشّح متاح من خلال الإشارات التالية:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

على البائع تحديد دالة reportResult() يتم عرضها من نقطة نهاية يملكها. يتم تحديد نقطة النهاية في إعدادات المزاد على النحو التالي: decisionLogicUrl. تتضمّن الدالة reportResult() التوقيع التالي:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

مَعلمات reportResult() هي:

• ‫auctionConfig، وهو إعداد المزاد المستخدَم لتنفيذ المزاد.
• ‫browserSignals، وهو عنصر ينشئه المتصفّح ويتضمّن معلومات يعرفها المتصفّح وقد يريد نص برمجي خاص بالمزاد تابع للبائع التحقّق منها. هذا هو الكائن نفسه الذي تم تمريره إلى الدالة scoreAds().

تعرض الدالة reportResult() القيمة signalsForWinner، وهي عبارة عن عنصر JSON عشوائي يتم تمريره إلى دالة إعداد التقارير الخاصة بالمشتري الفائز. يجب أن يشمل ذلك أي معلومات ذات صلة يمكن أن يقدّمها البائع حول المزاد والتي يحتاج إليها المشتري لإعداد التقارير.

إجراء مزاد باستخدام Protected Audience API

هناك أربع خطوات رئيسية يجب أن يتّخذها البائع لإجراء مزاد. يُرجى العِلم أنّ هذه الخطوات تفترض أنّ البائع قد أعدّ نقطة نهاية لعرض رمز JavaScript المطلوب المذكور سابقًا في هذا الدليل.

1. ضبط المزاد تتضمّن هذه الخطوة إنشاء عنصر auctionConfig. يتيح ذلك للبائع تحديد المشترين الذين يجب أن يشاركوا في المزاد، بالإضافة إلى تقديم أي إشارات قد تكون ذات صلة أثناء إنشاء عروض الأسعار أو تسجيل الإعلانات.
2. نفِّذ المزاد من خلال استدعاء navigator.runAdAuction()، مع تمرير الإعداد الذي تم إنشاؤه في الخطوة السابقة. يؤدي ذلك إلى بدء سلسلة من المشترين الذين يقدّمون عروض أسعار، ثم يتم تسجيل النتائج. النتيجة النهائية لهذه الخطوة هي إعلان مرشّح يمكن عرضه لعرض إعلان.
3. عرض الإعلان الفائز في إطار محمي أو iframe
4. الإبلاغ عن نتيجة المزاد هناك دالة، navigator.sendReportTo()، ستبدأ عملية الإبلاغ. سيتلقّى البائع دائمًا تقريرًا بنتائج المزاد. سيتلقّى المشتري الذي فاز بالمزاد تقريرًا فقط. يستخدم ذلك reportResult() البائع الموضّح سابقًا في هذا الدليل لإرسال التقارير إلى خادمه.