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

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

اطّلِع على دليل المطوِّر للتعرُّف على جميع مراحل استخدام Protected Audience API. راجِع الفيديو التوضيحي حول Protected Audience API للحصول على معلومات مفصّلة كيفية إجراء البائعين للمزادات على الجهاز فقط.

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

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

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

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

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

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

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

يحتاج البائع إلى وظيفتَي 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() الخاص بالبائع الموضّح سابقًا. في هذا الدليل لإبلاغ خادمهم بذلك.