إجراء مزاد يستند إلى المتصفّح مع بائع واحد

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

اقرأ دليل المطوّر للتعرّف على مراحل نشاط 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() الخاصة بالبائعين الموضّحة سابقًا في هذا الدليل لتقديم تقرير إلى خادمه.