توفير ميزة استهداف الجمهور المخصّص باستخدام Protected Audience API

أجدد التحديثات

• تمت إضافة معلومات حول جدولة تعديلات شرائح الجمهور المخصّصة
• تمّت إضافة عملية دمج واجهة برمجة التطبيقات Attribution Reporting مع Protected Audiences
• نشر مخطط زمني لميزات Protected Audience.
• تمت إعادة تسمية FLEDGE إلى Protected Audience API.
• تمت إضافة اقتراح بشأن تفويض شرائح الجمهور المخصّصة.
• تمت إزالة شرط إخفاء هوية عدد معيّن من المستخدمين لعنوان URL الخاص بالتحديث اليومي.

تتوفّر واجهة برمجة التطبيقات Protected Audience API في الإصدار التجريبي ويمكن استخدامها في عملية التطوير.

باستخدام Protected Audience، يمكنك إجراء ما يلي:

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

للبدء، يُرجى قراءة دليل المطوّرين لواجهة Protected Audience. نقدّر ملاحظاتك بينما نواصل تطوير Protected Audience.

المخطط الزمني

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

نظرة عامة

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

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

تشمل واجهة Protected Audience API على Android (المعروفة سابقًا باسم FLEDGE) واجهات برمجة التطبيقات التالية لمنصات تكنولوجيا الإعلان والمعلِنين من أجل إتاحة حالات الاستخدام الشائعة المستندة إلى التفاعل بطرق تحدّ من مشاركة كل من المعرّفات بين التطبيقات ومعلومات تفاعل المستخدم مع التطبيق مع الجهات الخارجية:

1. Custom Audience API: يركّز هذا العنصر على تجريد "شريحة الجمهور المخصّصة"، الذي يمثّل شريحة جمهور يحدّدها المعلِن وتتشارك نوايا مشتركة. يتم تخزين معلومات الجمهور على الجهاز ويمكن ربطها بالإعلانات المرشّحة المناسبة للجمهور والبيانات الوصفية العشوائية، مثل إشارات عروض الأسعار. ويمكن استخدام هذه المعلومات لإبلاغ المعلِنين بعروض الأسعار، وفلترة الإعلانات، وعرضها.
2. واجهة برمجة التطبيقات لاختيار الإعلانات: توفّر هذه الواجهة إطار عمل ينظّم سير عمل منصات تكنولوجيا الإعلان التي تستخدم الإشارات على الجهاز لتحديد "الإعلان الفائز" من خلال أخذ الإعلانات المرشّحة المخزّنة محليًا في الاعتبار، وإجراء معالجة إضافية للإعلانات المرشّحة التي تعرضها منصة تكنولوجيا الإعلان على الجهاز.

بشكل عام، يعمل الدمج على النحو التالي:

1. يريد تطبيق SportingGoodsApp تذكير المستخدمين بشراء السلع المتبقية في سلة التسوّق إذا لم يكملوا عملية الشراء خلال يومين. يستخدم تطبيق SportingGoodsApp واجهة برمجة التطبيقات "شرائح الجمهور المخصّصة" لإضافة المستخدم إلى قائمة جمهور "المنتجات في سلة التسوّق". تتولّى المنصة إدارة قائمة المستخدمين هذه وتخزينها على الجهاز، ما يحدّ من مشاركتها مع جهات خارجية. تعقد SportingGoodsApp شراكة مع منصة تكنولوجيا إعلانية لعرض إعلاناتها للمستخدمين في قائمة الجمهور. تدير منصة تكنولوجيا الإعلان البيانات الوصفية لقوائم المستخدمين وتقدّم إعلانات مرشّحة، وتتوفّر هذه الإعلانات في سير عمل اختيار الإعلانات ليتم أخذها في الاعتبار. يمكن ضبط المنصة على استرداد الإعلانات المستندة إلى الجمهور المعدَّلة بشكل دوري في الخلفية. يساعد ذلك في إبقاء قائمة الإعلانات المرشّحة المستندة إلى الجمهور محدّثة وغير مرتبطة بالطلبات المُرسَلة إلى خوادم الإعلانات التابعة لجهات خارجية أثناء فرصة عرض الإعلان (أي طلب الإعلان السياقي).

2. عندما يلعب المستخدم لعبة FrisbeeGame على الجهاز نفسه، قد يظهر له إعلان يذكّره بإكمال عملية شراء السلع التي تركها في سلة التسوق في تطبيق SportingGoodsApp. ويمكن تحقيق ذلك من خلال FrisbeeGame (التي تتضمّن حزمة تطوير برامج (SDK) مدمجة لعرض الإعلانات) التي تستدعي Ad Selection API لاختيار إعلان رابح للمستخدم استنادًا إلى أي قائمة مستخدمين قد يكون جزءًا منها (في هذا المثال، شريحة الجمهور المخصّصة "المنتجات في سلّة التسوّق" التي أنشأتها SportingGoodsApp). يمكن إعداد سير عمل اختيار الإعلانات ليأخذ في الاعتبار الإعلانات التي يتم استرجاعها من خوادم منصات تكنولوجيا الإعلان، بالإضافة إلى الإعلانات على الجهاز المرتبطة بشرائح الجمهور المخصّصة، فضلاً عن الإشارات الأخرى على الجهاز. يمكن أيضًا تخصيص سير العمل من خلال منصة تكنولوجيا الإعلان وحزمة SDK للإعلانات باستخدام عروض الأسعار المخصّصة ومنطق تسجيل النقاط لتحقيق أهداف إعلانية مناسبة. يتيح هذا الأسلوب استخدام بيانات اهتمامات المستخدم أو تفاعلاته مع التطبيق في تحديد الإعلانات، مع الحدّ من مشاركة هذه البيانات مع جهات خارجية.

3. تعرض حزمة تطوير البرامج (SDK) الخاصة بالتطبيق الذي يعرض الإعلانات أو منصة تكنولوجيا الإعلان الإعلان المحدّد.

4. تسهّل المنصّة إعداد التقارير عن نتائج مرات الظهور واختيار الإعلانات. تتكامل إمكانية إعداد التقارير هذه مع Attribution Reporting API. ويمكن لمنصات تكنولوجيا الإعلان تخصيصها استنادًا إلى احتياجاتها المتعلقة بإعداد التقارير.

الحصول على إذن الوصول إلى واجهات Protected Audience API على Android

يجب تسجيل منصات تكنولوجيا الإعلان للوصول إلى Protected Audience API. يمكنك الاطّلاع على مقالة الاشتراك للحصول على حساب على "مبادرة حماية الخصوصية" لمزيد من المعلومات.

إدارة شرائح الجمهور المخصّصة

جمهور مخصّص

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

يمكن لتطبيق أحد المعلِنين أو حزمة SDK المدمَجة الانضمام إلى شريحة جمهور مخصّصة أو مغادرتها استنادًا إلى تفاعل المستخدم مع تطبيق معيّن مثلاً.

البيانات الوصفية لشرائح الجمهور المخصّصة

تحتوي كل شريحة جمهور مخصّصة على البيانات الوصفية التالية:

• المالك: اسم حزمة تطبيق المالك. يتم ضبط هذا الخيار ضمنيًا على اسم حزمة التطبيق الذي يجري الاتصال.
• المشتري: شبكة إعلانات المشتري التي تدير الإعلانات لشريحة الجمهور المخصّصة هذه يمثّل "المشتري" أيضًا الجهة التي يمكنها الوصول إلى شريحة الجمهور المخصّصة واسترجاع معلومات الإعلان ذات الصلة. يتم تحديد المشتري باتّباع تنسيق eTLD+1.
• الاسم: اسم أو معرّف عشوائي لشريحة الجمهور المخصّصة، مثل مستخدم لديه "متسوّقون تخلّوا عن عربة التسوّق". يمكن استخدام هذه السمة، على سبيل المثال، كأحد معايير الاستهداف في الحملات الإعلانية للمعلِن، أو كسلسلة طلب في عنوان URL لجلب رمز عروض الأسعار.
• وقت التفعيل ووقت انتهاء الصلاحية: يحدّد هذان الحقلان الفترة الزمنية التي ستكون فيها شريحة الجمهور المخصّصة هذه فعّالة. تستخدِم المنصّة هذه المعلومات لإزالة المستخدم من شريحة جمهور مخصّصة. يجب ألا يتجاوز وقت انتهاء الصلاحية الحد الأقصى لمدة الفترة الزمنية المحددة للحد من عمر شريحة الجمهور المخصّصة.
• عنوان URL للتعديل اليومي: هو عنوان URL الذي تستخدمه المنصة لجلب الإعلانات المرشّحة والبيانات الوصفية الأخرى المحدّدة في الحقلَين "إشارات عروض الأسعار من المستخدم" و "إشارات عروض الأسعار الموثوقة" بشكل متكرّر. لمزيد من التفاصيل، راجِع القسم حول كيفية استرداد الإعلانات المرشّحة للشرائح المخصّصة من الجمهور.
• إشارات عروض أسعار المستخدمين: إشارات خاصة بمنصّة تكنولوجيا الإعلان لأي عروض أسعار للإعلانات الموجَّهة إلى الزوّار السابقين وتتضمّن أمثلة الإشارات ما يلي: الموقع الجغرافي التقريبي للمستخدم أو اللغة المفضّلة.
• بيانات عروض الأسعار الموثوقة: تعتمد منصات تكنولوجيا الإعلان على البيانات في الوقت الفعلي لإعلام عملية استرداد الإعلانات وتسجيل النقاط. على سبيل المثال، قد تنفد ميزانية إعلان معيّن، وبالتالي يجب إيقاف عرضه على الفور. يمكن لتكنولوجيا الإعلان تحديد نقطة نهاية لعنوان URL يمكن من خلالها استرداد هذه البيانات في الوقت الفعلي ومجموعة المفاتيح التي يجب إجراء البحث في الوقت الفعلي عنها. سيكون الخادم الذي يتعامل مع هذا الطلب خادمًا موثوقًا به تديره منصة تكنولوجيا الإعلان.
• عنوان URL لمنطق عروض الأسعار: عنوان URL الذي تستخدمه المنصة لجلب رمز عروض الأسعار من منصة العرض. تنفّذ المنصة هذه الخطوة عند بدء مزاد إعلاني.
• الإعلانات: قائمة بالإعلانات المرشّحة لشريحة الجمهور المخصّصة. ويشمل ذلك بيانات وصفية للإعلانات خاصة بمنصات تكنولوجيا الإعلان وعنوان URL لعرض الإعلان. عند بدء مزاد للجمهور المخصّص، سيتم أخذ قائمة البيانات الوصفية للإعلانات هذه في الاعتبار. ستتم إعادة تحميل قائمة الإعلانات هذه باستخدام نقطة نهاية عنوان URL الخاصة بالتحديث اليومي عند الإمكان. بسبب القيود المفروضة على الموارد في الأجهزة الجوّالة، هناك حدّ أقصى لعدد الإعلانات التي يمكن تخزينها في شريحة جمهور مخصّصة.

تفويض الجمهور المخصّص

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

الانضمام إلى شريحة جمهور مخصّصة

يمكن الانضمام إلى شريحة جمهور مخصّصة بطريقتَين:

joinCustomAudience()

يمكن لتطبيق أو حزمة تطوير برامج (SDK) طلب الانضمام إلى شريحة جمهور مخصّصة من خلال استدعاء joinCustomAudience() بعد إنشاء مثيل للعنصر CustomAudience باستخدام المَعلمات المتوقّعة. في ما يلي مثال توضيحي لمقتطف رمز برمجي:

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

يمكن لأي تطبيق أو حزمة SDK أن يطلب الانضمام إلى شريحة جمهور مخصّصة نيابةً عن تكنولوجيا إعلانية لا تتوفّر على الجهاز، وذلك من خلال استدعاء fetchAndJoinCustomAudience() مع المَعلمات المتوقّعة، كما هو موضّح في المثال التالي:

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

تردّ نقطة نهاية عنوان URL، التي يملكها المشتري، بكائن CustomAudience JSON في نص الاستجابة. يتم تجاهل حقلَي المشتري والمالك لشريحة الجمهور المخصّصة (وتتم تعبئتهما تلقائيًا من خلال واجهة برمجة التطبيقات). تفرض واجهة برمجة التطبيقات أيضًا أن يتطابق عنوان URL الخاص بالتحديث اليومي مع eTLD+1 الخاص بالمشتري.

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

تحدّد واجهة برمجة التطبيقات fetchAndJoinCustomAudience() هوية المشتري من خلال eTLD+1 الخاص بـ fetchUri. يتم استخدام هوية CustomAudience المشتري لإجراء عمليات التحقّق نفسها من التسجيل وإذن التطبيق التي يجريها joinCustomAudience()، ولا يمكن تغييرها من خلال استجابة الجلب. مالك CustomAudience هو اسم حزمة التطبيق الذي يتم استدعاؤه. لا يتوفّر أي إجراء آخر للتحقّق من صحة fetchUri غير التحقّق من eTLD+1، ولا يتوفّر على وجه الخصوص أي تحقّق من k-anon. تُصدر واجهة برمجة التطبيقات fetchAndJoinCustomAudience() طلب HTTP GET إلى fetchUri وتتوقّع تلقّي عنصر JSON يمثّل شريحة الجمهور المخصّصة. يتم تطبيق القيود الإلزامية والاختيارية والقيم التلقائية نفسها لحقول عنصر الجمهور المخصّص على الردّ. يمكنك الاطّلاع على المتطلبات والقيود الحالية في دليل المطوّرين.

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

يتيح العنصر CustomAudienceFetchRequest لمستدعي واجهة برمجة التطبيقات تحديد بعض المعلومات الخاصة بالجمهور المخصّص باستخدام الخصائص الاختيارية الموضّحة في المثال. إذا تم ضبط هذه القيم في الطلب، لا يمكن استبدالها بردّ المشتري الذي تلقّته المنصة، إذ تتجاهل Protected Audience API الحقول في الردّ. إذا لم يتم ضبطها في الطلب، يجب ضبطها في الردّ، لأنّ هذه الحقول مطلوبة لإنشاء شريحة جمهور مخصّصة. يتم تضمين تمثيل JSON لمحتوى CustomAudience الذي يحدده جزئيًا طالب البيانات من واجهة برمجة التطبيقات في طلب GET إلى fetchUri في عنوان خاص X-CUSTOM-AUDIENCE-DATA. يقتصر حجم النموذج المتسلسل للبيانات المحدّدة لـ "الجمهور المخصّص" على 8 كيلوبايت. إذا تجاوز الحجم الحد المسموح به، سيتعذّر طلب البيانات من واجهة برمجة التطبيقات fetchAndJoinCustomAudience.

يسمح لك عدم توفّر عملية التحقّق من k-anon باستخدام fetchUri للتحقّق من هوية المشتري ولإتاحة مشاركة المعلومات بين المشتري وحزمة SDK. لتسهيل عملية إثبات ملكية شرائح الجمهور المخصّصة، يمكن للمشتري تقديم رمز مميّز لإثبات الملكية. يجب أن يتضمّن حزمة تطوير البرامج (SDK) على الجهاز هذا الرمز المميّز في fetchUri لكي يتمكّن نقطة النهاية التي يستضيفها المشتري من استرداد محتوى شرائح الجمهور المخصّصة واستخدام رمز التحقّق للتأكّد من أنّ عملية fetchAndJoinCustomAudience() تخصّ المشتري وأنّها صادرة من شريك موثوق به على الجهاز. لمشاركة المعلومات، يمكن للمشتري الاتفاق مع المتصل على الجهاز على أنّه سيتم إضافة بعض المعلومات التي سيتم استخدامها لإنشاء شريحة الجمهور المخصّصة كمعلَمات طلب بحث إلى fetchUri. يتيح ذلك للمشتري تدقيق الطلبات واكتشاف ما إذا كانت تكنولوجيا إعلان ضارة قد استخدمت رمزًا مميزًا للتحقّق من الصحة لإنشاء عدّة شرائح جمهور مخصّصة مختلفة.

ملاحظة حول تعريف رمز التحقّق وتخزينه

• لا تستخدم واجهة Protected Audience API رمز التحقّق لأي أغراض، كما أنّه اختياري.

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

مغادرة شريحة جمهور مخصّصة

يمكن لمالك شريحة جمهور مخصّصة اختيار المغادرة عن طريق الاتصال بـ leaveCustomAudience()، كما هو موضّح في مقتطف الرمز التوضيحي التالي:

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

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

تحكّم المستخدم

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

تصميم هذه الميزة قيد التطوير، وسيتم تضمين التفاصيل في تحديث لاحق.

التحديثات المُجدوَلة

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

لتسهيل ذلك، يمكن لتقنيات الإعلان استدعاء واجهة برمجة التطبيقات scheduleCustomAudienceUpdate(). تسمح واجهة برمجة التطبيقات هذه لجهة طلب البيانات بتحديد تأخير في وقت إجراء طلب البيانات من واجهة برمجة التطبيقات، ما يوفّر وقتًا إضافيًا لتقنية الإعلان المستجيبة لمعالجة الأحداث على مستوى التطبيق وتحديد المجموعات التي يجب أن ينضم إليها المستخدم أو تتم إزالته منها في Protected Audience.

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

ScheduleCustomAudienceUpdateRequest

public final class ScheduleCustomAudienceUpdateRequest {
  // Required Field
  @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

  // Required Field
  @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

  //  Required Field
  @NonNull public List<PartialCustomAudience> getPartialCustomAudienceList() {
    return mPartialCustomAudiences;
  }

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

يحتوي ScheduleCustomAudienceUpdateRequest على المعلومات اللازمة لتسجيل مهمة مؤجّلة ليتم تنفيذها على المنصة. بعد التأخير المحدّد، سيتم تشغيل مهمة في الخلفية بشكل دوري وإرسال الطلبات. يمكن أن يحتوي ScheduleCustomAudienceUpdateRequest على المعلومات التالية:

• UpdateUri: نقطة نهاية معرّف الموارد المنتظم (URI) التي سيتم إرسال طلب GET إليها لجلب التحديث. يتم استنتاج هوية المشتري بشكل أساسي من eTLD+1، ولا يلزم تقديمها بشكل صريح، ولا يمكن تغييرها من خلال استجابة التحديث. يتوقّع طلب GET عنصر JSON يحتوي على قائمة بعناصر customAudience يتم عرضها.
• DelayTime: الوقت الذي يشير إلى التأخير من وقت إجراء طلب البيانات من واجهة برمجة التطبيقات scheduleCustomAudienceUpdate() إلى وقت تحديد موعد التحديث.

• ‫PartialCustomAudience: تتيح واجهة برمجة التطبيقات أيضًا لحزمة SDK على الجهاز إرسال قائمة بشرائح جمهور مخصّصة تم إنشاؤها جزئيًا. يتيح ذلك لحِزم SDK داخل التطبيق أداء دور مزدوج، بدءًا من التحكّم الكامل إلى التحكّم الجزئي في إدارة شرائح الجمهور المخصّصة، وذلك استنادًا إلى شراكتها مع منصات طلب الإعلانات.

  • يضمن ذلك أيضًا توافق واجهة برمجة التطبيقات هذه مع واجهة برمجة التطبيقات fetchAndJoinCustomAudience() التي تتيح مشاركة معلومات مشابهة.

• ShouldReplacePendingUpdates: قيمة منطقية تحدّد ما إذا كان سيتم إلغاء أي تحديثات مجدوَلة معلّقة واستبدالها بالتحديث الموضّح في ScheduleCustomAudienceUpdateRequest الحالي. إذا تم ضبط هذا الحقل على false وكانت هناك تحديثات سبق أن طلبها المشتري نفسه ولا تزال معلّقة في التطبيق نفسه، سيتعذّر تنفيذ طلب scheduleCustomAudienceUpdate باستخدام ScheduleCustomAudienceUpdateRequest هذا. القيمة التلقائية هي false.

أذونات التطبيقات والتحكّم فيها

يهدف الاقتراح إلى منح التطبيقات التحكّم في شرائح الجمهور المخصّصة:

• يمكن لأي تطبيق إدارة عمليات الربط بالجماهير المخصّصة.
• يمكن أن يمنح التطبيق منصّات تكنولوجيا الإعلان التابعة لجهات خارجية أذونات لإدارة شرائح الجمهور المخصّصة نيابةً عنه.

تصميم هذه الميزة قيد التطوير، وسيتم تضمين التفاصيل في تحديث لاحق.

التحكّم في منصة تكنولوجيا الإعلان

يقترح هذا الاقتراح طرقًا تتيح لتقنيات الإعلان التحكّم في شرائح الجمهور المخصّصة:

• تسجّل تكنولوجيات الإعلان في "مبادرة حماية الخصوصية" وتوفّر نطاق eTLD+1 يتطابق مع جميع عناوين URL الخاصة بشريحة جمهور مخصّصة.
• يمكن لشركات تكنولوجيا الإعلان التعاون مع التطبيقات أو حِزم تطوير البرامج (SDK) لتوفير رموز مميّزة لإثبات صحة المعلومات تُستخدَم لإثبات صحة عملية إنشاء شريحة جمهور مخصّصة. عند تفويض هذه العملية إلى أحد الشركاء، يمكن ضبط عملية إنشاء شرائح الجمهور المخصّصة لتتطلّب إقرارًا من تكنولوجيا الإعلان.
• يمكن لتكنولوجيا الإعلان اختيار إيقاف طلبات joinCustomAudience نيابةً عنك والسماح لواجهة برمجة التطبيقات fetchAndJoinCustomAudience فقط بتفعيل جميع شرائح الجمهور المخصّصة التي يتم إنشاؤها من خلال طلبات البيانات. يمكن تعديل عنصر التحكّم أثناء التسجيل في "مبادرة حماية الخصوصية". يُرجى العِلم أنّ عنصر التحكّم يسمح إما بجميع تكنولوجيات الإعلان أو لا يسمح بأي منها. بسبب القيود المفروضة على المنصة، لا يمكن منح أذونات التفويض على أساس كل تكنولوجيا إعلانية.

استجابة الإعلانات والبيانات الوصفية للمرشحين

يجب أن تتضمّن الإعلانات المرشّحة والبيانات الوصفية التي يتم عرضها من منصة جهة الشراء الحقول التالية:

• البيانات الوصفية: بيانات وصفية خاصة بالإعلانات على جانب الشراء وتقنيات الإعلان على سبيل المثال، قد يشمل ذلك معلومات حول الحملة الإعلانية ومعايير الاستهداف، مثل الموقع الجغرافي واللغة.
• عنوان URL للعرض: نقطة نهاية لعرض تصميم الإعلان.
• الفلتر: معلومات اختيارية ضرورية لكي تتمكّن Protected Audience API من فلترة الإعلانات استنادًا إلى البيانات المتوفّرة على الجهاز لمزيد من التفاصيل، اطّلِع على القسم الخاص بمنطق الفلترة من جهة المشتري.

سير عمل اختيار الإعلان

يهدف هذا الاقتراح إلى تحسين الخصوصية من خلال طرح واجهة برمجة التطبيقات Ad Selection API التي تنظّم عملية تنفيذ المزاد لمنصات تكنولوجيا الإعلان.

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

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

يتيح هذا النهج استخدام بيانات تفاعلات المستخدم مع التطبيق في تحديد الإعلانات، مع الحدّ من مشاركة هذه البيانات مع جهات خارجية.

تنسّق سير عمل اختيار الإعلانات هذا عملية تنفيذ رمز JavaScript المقدَّم من تكنولوجيات الإعلان على الجهاز استنادًا إلى التسلسل التالي:

1. تنفيذ منطق عروض الأسعار من جهة الشراء
2. فلترة الإعلانات ومعالجتها من جهة الشراء
3. تنفيذ منطق اتّخاذ القرار من جهة البيع

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

يخضع تصميم عمليات اختيار الإعلانات التي لا تتضمّن شرائح جمهور مخصّصة إلى عملية تصميم نشطة.

بدء سير عمل اختيار الإعلانات

عندما يحتاج تطبيق إلى عرض إعلان، يمكن أن تبدأ حزمة تطوير البرامج (SDK) لمنصة تكنولوجيا الإعلان سير عمل اختيار الإعلان من خلال استدعاء الطريقة selectAds() بعد إنشاء العنصر AdSelectionConfig باستخدام المَعلمات المتوقّعة:

• البائع: معرّف لمنصّة الإعلانات من جهة البائع، باتّباع تنسيق eTLD+1
• عنوان URL الخاص بمنطق اتّخاذ القرار: عند بدء مزاد على الإعلانات، ستستخدِم المنصة عنوان URL هذا لجلب رمز JavaScript من منصة العرض من جهة البيع من أجل تسجيل نقاط للإعلان الفائز.
• مشترو شرائح الجمهور المخصّصة: قائمة بمنصّات الشراء التي لديها طلب مخصّص يستند إلى شرائح الجمهور في هذه المزاد، وذلك بالتنسيق eTLD+1.
• إشارات اختيار الإعلان: معلومات عن المزاد (حجم الإعلان وشكله وما إلى ذلك).
• إشارات البائع: إشارات خاصة بمنصة العرض.
• عنوان URL الخاص بإشارات قياس الأداء الموثوقة: نقطة نهاية عنوان URL للإشارة الموثوقة من جهة البيع والتي يمكن من خلالها استرداد معلومات في الوقت الفعلي خاصة بتصميم الإعلان.
• إشارات لكلّ مشترٍ: قد تستخدم جهات الطلب المشارِكة هذه المَعلمة لتقديم مدخلات للمزاد. على سبيل المثال، قد تتضمّن هذه المَعلمة معلومات سياقية شاملة مفيدة في تحديد عروض الأسعار.

يعرض مقتطف الرمز التوضيحي التالي حزمة SDK لمنصّة تكنولوجيا الإعلان تبدأ سير عمل اختيار الإعلان من خلال تحديد AdSelectionConfig أولاً، ثم استدعاء selectAds للحصول على الإعلان الفائز:

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

منطق عروض الأسعار من جهة الشراء

عادةً ما توفّر منصّات جهة الشراء منطق عروض الأسعار. والغرض من هذا الرمز هو تحديد عروض الأسعار للإعلانات المرشّحة. وقد يطبّق منطقًا تجاريًا إضافيًا لتحديد النتيجة.

ستستخدم المنصة البيانات الوصفية "عنوان URL لمنطق عروض الأسعار" الخاصة بشريحة الجمهور المخصّصة لجلب رمز JavaScript الذي يجب أن يتضمّن توقيع الدالة التالي:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

تعرض الطريقة generateBid() مبلغ عرض السعر المحسوب. ستستدعي المنصة هذه الدالة لجميع الإعلانات (السياقية أو تجديد النشاط التسويقي) بالتسلسل. في حال توفّر عدة مقدّمي منطق عروض أسعار، لا يضمن النظام ترتيب التنفيذ بين المقدّمين.

تتوقّع الدالة المَعلمات التالية:

• الإعلان: الإعلان الذي يأخذه رمز عروض الأسعار من جهة الشراء في الاعتبار. سيكون هذا الإعلان من شريحة جمهور مخصّصة مؤهَّلة
• إشارات المزاد: إشارات خاصة بمنصة البيع.
• إشارات لكلّ مشترٍ: قد تستخدم جهات الطلب المشارِكة هذه المَعلمة لتقديم مدخلات للمزاد. على سبيل المثال، قد تتضمّن هذه المَعلمة معلومات سياقية شاملة مفيدة في تحديد عروض الأسعار.
• إشارات عروض الأسعار الموثوقة: تعتمد منصّات تكنولوجيا الإعلان على البيانات في الوقت الفعلي لتوجيه عملية استرداد الإعلانات وتسجيل نقاطها. على سبيل المثال، قد تنتهي ميزانية حملة إعلانية، ويجب إيقاف عرضها فورًا. يمكن أن تحدّد تكنولوجيا الإعلان نقطة نهاية عنوان URL يمكن من خلالها جلب هذه البيانات في الوقت الفعلي ومجموعة المفاتيح التي يجب إجراء البحث في الوقت الفعلي عنها. سيكون الخادم المُدار التابع لمنصة تكنولوجيا الإعلان والذي يعرض هذا الطلب خادمًا موثوقًا به تديره منصة تكنولوجيا الإعلان.
• الإشارات السياقية: قد يشمل ذلك الطابع الزمني المضبوط أو معلومات الموقع الجغرافي التقريبية أو التكلفة لكل نقرة على الإعلان.
• إشارات المستخدم: قد يشمل ذلك معلومات مثل معلومات الحِزم المثبَّتة المتاحة.

تكلفة الإعلان

بالإضافة إلى عرض السعر، يمكن لمنصات جهة الشراء عرض تكلفة النقرة كجزء من generateBid(). على سبيل المثال:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

إذا فاز هذا الإعلان، سيتم تقريب قيمة adCost بشكل عشوائي إلى 8 بتات للحفاظ على الخصوصية. بعد ذلك، يتم تمرير القيمة المقرَّبة لـ adCost إلى المَعلمة contextual_signals في reportWin أثناء تسجيل مرات الظهور.

منطق الفلترة من جهة الشراء

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

يمكن تنفيذ منطق الفلترة من جهة الشراء كجزء من منطق عروض الأسعار من خلال عرض قيمة عرض سعر تبلغ 0 لإعلان معيّن.

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

منطق تسجيل النقاط من جهة البيع

يتم توفير منطق التسجيل عادةً من خلال منصة جهة البيع. الغرض من الرمز هو تحديد الإعلان الفائز استنادًا إلى نتائج منطق عروض الأسعار. وقد تطبّق منطقًا تجاريًا إضافيًا لتحديد النتيجة. في حال توفّر عدة جهات تقدّم منطق اتخاذ القرار، لا يضمن النظام ترتيب التنفيذ بين الجهات. ستستخدِم المنصة مَعلمة الإدخال "عنوان URL لمنطق اتّخاذ القرار" في واجهة برمجة التطبيقات selectAds() لجلب رمز JavaScript الذي يجب أن يتضمّن توقيع الدالة التالي:

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

تتوقّع الدالة المَعلمات التالية:

• الإعلان: الإعلان الذي يتم تقييمه، وهو الناتج من الدالة generateBid().
• عرض السعر: ناتج مبلغ عرض السعر من الدالة generateBid().
• إعدادات المزاد: مَعلمة إدخال لطريقة selectAds().
• إشارات تسجيل النقاط الموثوقة: تعتمد منصّات تكنولوجيا الإعلان على البيانات في الوقت الفعلي لتحديد معايير فلترة الإعلانات وتسجيل النقاط. على سبيل المثال، يمكن لناشر تطبيق حظر حملة إعلانية من عرض الإعلانات في التطبيق. يتم جلب هذه البيانات من مَعلمة عنوان URL الخاصة بإشارات التسجيل الموثوقة في إعدادات المزاد. يجب أن يكون الخادم الذي يعرض هذا الطلب خادمًا موثوقًا به تديره تكنولوجيا الإعلان.
• الإشارة السياقية: قد تشمل هذه الإشارة طابعًا زمنيًا غير دقيق أو معلومات تقريبية عن الموقع الجغرافي.
• إشارة المستخدم: قد تتضمّن هذه الإشارة معلومات مثل متجر التطبيقات الذي بدأ عملية تثبيت التطبيق.
• إشارة الجمهور المخصّص: إذا كان الإعلان الذي يتم تسجيل نقاطه واردًا من جمهور مخصّص على الجهاز، سيتضمّن هذا الحقل معلومات مثل القارئ واسم الجمهور المخصّص.

وقت تشغيل رمز اختيار الإعلان

في العرض، سيجلب النظام رمز المزاد الذي توفّره منصة تكنولوجيا الإعلان من نقاط نهاية عناوين URL القابلة للإعداد وينفّذه على الجهاز. نظرًا إلى قيود الموارد على الأجهزة الجوّالة، يجب أن يلتزم رمز المزاد بالإرشادات التالية:

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

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

لغة البرمجة

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

عرض الإعلان الفائز

ويُعتبر الإعلان الذي يحصل على أعلى نتيجة هو الفائز في المزاد. في هذا الاقتراح الأوّلي، يتم تمرير الإعلان الفائز إلى حزمة SDK لعرضه.

وتتمثّل الخطة في تطوير الحلّ للتحقّق من أنّه لا يمكن للتطبيق أو حزمة SDK تحديد المعلومات المتعلّقة باشتراك المستخدم في الجمهور المخصّص أو سجلّ التفاعل مع التطبيق من خلال معلومات حول الإعلان الفائز (على غرار اقتراح الإطارات المحصورة في Chrome).

إعداد التقارير عن مرّات الظهور والأحداث

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

1. إعداد التقارير من جهة البيع
2. إعداد التقارير من جهة الشراء

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

هناك خطوتان مطلوبتان لإتاحة إعداد تقارير الأحداث: يجب أن يسجّل JavaScript من جهة البيع ومن جهة الشراء الحدث الذي يجب أن يتلقّى تقارير الأحداث بشأنه، وتكون جهة البيع مسؤولة عن إعداد تقارير عن المعلومات على مستوى الحدث.

توفّر Protected Audience آلية للاشتراك في الأحداث المستقبلية ذات الصلة بمزاد ناجح من خلال تسجيل إشارات. في reportResult()دالة JavaScript الخاصة بالبائع، يمكن لمنصات العرض تسجيل إشارات باستخدام الدالة registerAdBeacon() الخاصة بالمنصة. وبالمثل، يمكن لمنصات جانب الشراء استدعاء الطريقة registerAdBeacon() من دالة JavaScript reportWin().

registerAdBeacon(beacons)

الإدخال:

• ‫event_key: سلسلة تحدّد نوع التفاعل المطلوب تسجيله. يُستخدَم هذا المعرّف كمفتاح للبحث عن نقطة النهاية التي يرسل إليها النظام الأساسي إشارة أثناء إعداد تقارير بنتائج المزاد.
• ‫reporting_url: عنوان URL الذي تملكه منصة تكنولوجيا الإعلان لمعالجة الحدث.

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

إعداد التقارير من جهة البيع

تستدعي المنصة دالة reportResult() JavaScript في الرمز المقدَّم من جهة العرض والذي تم تنزيله من المَعلمة عنوان URL لمنطق اتخاذ القرار الخاصة بالبائع لواجهة برمجة التطبيقات selectAds():

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

الناتج: عنصر JSON يحتوي على

• الحالة: 0 في حال النجاح، وأي قيمة أخرى في حال التعذّر.
• عنوان URL لإعداد التقارير: تستدعي المنصة عنوان URL هذا الذي تم إرجاعه من الدالة.
• إشارات للمشتري: كائن JSON سيتم تمريره إلى وظيفة reportWin الخاصة بالمشتري.

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

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

إعداد التقارير من جهة الشراء

تستدعي المنصة دالة reportWin() JavaScript في الرمز الذي يوفّره جانب الطلب والذي يتم تنزيله من البيانات الوصفية لعنوان URL لمنطق عروض الأسعار الخاصة بشريحة الجمهور المخصّصة المرتبطة بالمزاد.

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

الإدخال:

• يتم استرداد auction_signals وper_buyer_signals من AuctionConfig. يمكن أن تأتي أي معلومات تحتاج منصة الشراء إلى تمريرها إلى عنوان URL الخاص بإعداد التقارير من هذه البيانات.
• ‫signals_for_buyer هو ناتج sell-side reportResult. ويوفّر ذلك لوسيط عرض المبيعات فرصة مشاركة البيانات مع وسيط جهة الشراء لأغراض إعداد التقارير.
• يحتوي contextual_signals على معلومات مثل اسم التطبيق، بينما يحتوي custom_audience_signals على معلومات شرائح الجمهور المخصّصة. قد تتم إضافة معلومات أخرى في المستقبل.

إخراج:

• الحالة: 0 في حال النجاح، وأي قيمة أخرى في حال التعذّر.
• عنوان URL لإعداد التقارير: تستدعي المنصة عنوان URL هذا الذي تم إرجاعه من الدالة.

تسجيل الأحداث

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

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

الإدخال:

• يجب أن يكون ad_selection_id هو AdSelectionId لمزاد تم إجراؤه مؤخرًا وتم استرداده من AdSelectionOutcome.
• ‫event_key هي سلسلة نصية يحدّدها جانب البيع وتصف حدث التفاعل.
• ‫event_data هي سلسلة تمثّل البيانات المرتبطة بـ event_key
• ‫reporting_destinations هو قناع بت يتم ضبطه باستخدام العلامات التي توفّرها المنصة. يمكن أن يكون أحد الخيارين FLAG_REPORTING_DESTINATION_SELLER أو FLAG_REPORTING_DESTINATION_BUYER، أو كليهما.
• يُستخدَم input_event (اختياري) للدمج مع Attribution Reporting API. وهو إما كائن InputEvent (لحدث نقر) أو قيمة فارغة (لحدث عرض). لمزيد من التفاصيل حول هذه المَعلمة، يُرجى الاطّلاع على مقالة دمج Attribution Reporting API.

بعد أن تستدعي حزمة تطوير البرامج (SDK) من جهة البيع reportEvent، وبناءً على العلامة reporting_destinations، تحاول المنصة مطابقة event_key مع المفاتيح التي سجّلها المشترون والبائعون في وظائف JavaScript reportWin وreportResult. في حال العثور على تطابق، ترسل المنصة طلب POST إلى reporting_url المرتبط بالمعرّف event_data. content type الطلب هو نص عادي، ويكون النص الأساسي هو event_data. يتم تقديم هذا الطلب بأفضل ما يمكن، وفي حال حدوث خطأ في الشبكة أو خطأ في استجابة الخادم أو عدم العثور على أي مفاتيح مطابقة، سيتم إيقاف الطلب بدون إشعار.

دمج واجهة برمجة التطبيقات Attribution Reporting API

لدعم المشترين المشاركين في مزاد يستخدم Protected Audience API، نوفّر وظائف مشتركة بين واجهتَي Protected Audience API وAttribution Reporting API (ARA). تتيح هذه الوظيفة لتقنيات الإعلان تقييم أداء تحديد المصدر على مستوى مختلف تكتيكات تجديد النشاط التسويقي، ما يتيح لها معرفة أنواع شرائح الجمهور التي تحقّق أعلى عائد استثمار.

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

• أنشئ خريطة مفتاح-قيمة لمعرّفات الموارد المنتظمة (URI) التي سيتم استخدامها في كلّ من 1) إعداد تقارير التفاعل مع الإعلانات و2) تسجيل المصدر.
• تضمين بيانات المزاد من مزاد Protected Audience في عملية ربط المفاتيح من جهة المصدر لإعداد تقارير الملخّصات المجمّعة (باستخدام Attribution Reporting API). يمكنك الاطّلاع على اقتراح تصميم ARA للحصول على مزيد من المعلومات.

عندما يرى مستخدم إعلانًا أو ينقر عليه:

• سيوفّر عنوان URL المستخدَم لإعداد تقارير عن تفاعلات الأحداث هذه باستخدام Protected Audience البيانات اللازمة للمشتري كي يتمكّن من تسجيل مرّة مشاهدة أو نقرة كمصدر مؤهَّل باستخدام Attribution Reporting API.
• يمكن أن تختار تكنولوجيا الإعلان تمرير CustomAudience (أو معلومات سياقية أخرى ذات صلة بالإعلان، مثل موضع الإعلان أو مدة العرض) باستخدام عنوان URL هذا، حتى يمكن نشر البيانات الوصفية إلى التقارير الموجزة عندما تراجع تكنولوجيا الإعلان الأداء المجمّع للحملة.

تفعيل تسجيل المصدر

ستقبل reportEvent() مَعلمة اختيارية جديدة InputEvent. يمكن للمشترين الناجحين الذين يسجّلون إشارات الإعلانات اختيار تقارير reportEvent التي يتم تسجيلها باستخدام واجهات برمجة التطبيقات Attribution Reporting كإعلان مصدر مسجّل. ستتم إضافة عنوان الطلب Attribution-Reporting-Eligible إلى جميع طلبات تسجيل الأحداث التي يتم إرسالها من reportEvent(). سيتم تحليل أي ردود تتضمّن عناوين ARA مناسبة بالطريقة نفسها التي يتم بها تحليل أي ردود أخرى عادية لتسجيل مصدر ARA. راجِع شرح واجهة برمجة التطبيقات Attribution Reporting API لمعرفة كيفية تسجيل عنوان URL للمصدر.

بما أنّ ميزة "إعداد التقارير عن الإحالات الناجحة على مستوى التطبيق" على Android تتيح تسجيل أحداث المشاهدة والنقر، يتم استخدام InputEvents للتمييز بين النوعَين. كما هو الحال في تسجيل مصدر ARA، ستفسّر واجهة برمجة التطبيقات reportEvent() InputEvent تم التحقّق منه على المنصة على أنّه حدث نقرة. إذا كانت قيمة InputEvent غير متوفّرة أو فارغة أو غير صالحة، سيتم اعتبار تسجيل المصدر بمثابة مشاهدة.

يُرجى العِلم أنّ eventData بعد انتهاء المزاد قد يحتوي على معلومات حساسة، لذا تحذف المنصة eventData في طلبات تسجيل المصدر التي تتم إعادة توجيهها.

مثال على إعداد تقارير التفاعل والإحالات الناجحة

في هذا المثال، سننظر إلى الأمر من منظور المشتري المهتم بربط البيانات من المزاد والإعلان المعروض وتطبيق الإحالة الناجحة معًا.

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

سير العمل: قبل بدء المزاد، يرسل المشتري معرّفًا فريدًا إلى البائع كجزء من ردّ عرض الأسعار الخاص بعرض الأسعار الآلي في الوقت الفعلي. يمكن ضبط رقم التعريف كمتغيّر، مثل auctionId. يتم تمرير المعرّف كـ perBuyerSignals في auctionConfig، ويصبح متاحًا في منطق عروض الأسعار الخاص بالمشتري.

1. أثناء تنفيذ reportWin، يمكن للمشتري تسجيل إشارة إعلان ليتم تشغيلها أثناء وقت عرض الإعلان ولأحداث تفاعل معيّنة (registerAdBeacon()). لربط إشارات المزاد بحدث إعلان، اضبط auctionId كمَعلمة طلب بحث لعنوان URL الخاص بالإشارة.
2. أثناء عرض الإعلان، يمكن تفعيل إشارات التتبُّع التي سجّلتها أثناء المزاد أو تحسينها باستخدام بيانات على مستوى الحدث. على البائع تشغيل reportEvent() وتمرير البيانات على مستوى الحدث. سترسل المنصة إشارة إلى عنوان URL الخاص بموقع إشارة الإعلان المسجّل لدى المشتري والذي يرتبط بالحدث reportEvent() الذي تم تنشيطه.
3. سيسجّل المشتري الإعلان باستخدام Attribution Reporting API من خلال الردّ على طلبات إشارات الإعلان باستخدام العنوان Attribution-Reporting-Register-Source. لربط إشارات المزاد بحدث إحالة ناجحة، اضبط auctionId في عنوان URL الخاص بمصدر التسجيل.

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

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

خادم موثوق تديره منصة تكنولوجيا الإعلان

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

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

جهة الشراء: بعد أن تبدأ جهة الشراء منطق عروض الأسعار، تجلب المنصة بيانات عروض الأسعار الموثوقة من الخادم الموثوق به باستخدام بروتوكول HTTP. يتم إنشاء عنوان URL من خلال إضافة عنوان URL والمفاتيح المتوفّرة في البيانات الوصفية لإشارات Trusted Bidding Signals الخاصة بشريحة الجمهور المخصّصة التي تتم معالجتها. لا يتم إجراء عملية الجلب هذه إلا عند معالجة الإعلانات من شرائح الجمهور المخصّصة على الجهاز. في هذه المرحلة، يمكن لجهة الشراء فرض ميزانيات، والتحقّق من حالة الإيقاف المؤقت للحملة أو استئنافها، وتنفيذ الاستهداف، وما إلى ذلك.

في ما يلي نموذج لعنوان URL لاسترداد بيانات "عروض الأسعار الموثوقة"، استنادًا إلى البيانات الوصفية لإشارة "عروض الأسعار الموثوقة" من شريحة الجمهور المخصّصة:

https://www.kv-server.example/getvalues?keys=key1,key2

يجب أن يكون الردّ من الخادم عبارة عن عنصر JSON تكون مفاتيحه هي key1 وkey2 وما إلى ذلك، وستكون قيمه متاحة لوظائف عروض الأسعار الخاصة بالمشتري.

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

في ما يلي نموذج لعنوان URL لجلب معلومات عن تصاميم الإعلانات التي تم أخذها في الاعتبار في المزاد، استنادًا إلى عناوين URL لعرض تصاميم الإعلانات:

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

يجب أن يكون الردّ من الخادم عبارة عن عنصر JSON تكون مفاتيحه هي عناوين URL للعرض التي تم إرسالها في الطلب.

ستعمل هذه الخوادم بطريقة موثوقة لتقديم العديد من مزايا الأمان والخصوصية، وهي:

• يمكن الوثوق بقيمة الإرجاع التي يقدّمها الخادم لكل مفتاح على أنّها تستند فقط إلى هذا المفتاح.
• لا ينفّذ الخادم تسجيلًا على مستوى الحدث.
• لا يتسبب الخادم في أي آثار جانبية أخرى استنادًا إلى هذه الطلبات.

كآلية مؤقتة، يمكن للمشتري والبائع استرداد إشارات عروض الأسعار هذه من أي خادم، بما في ذلك خادم يديرانه بأنفسهما. ومع ذلك، في الإصدار النهائي، سيتم إرسال الطلب فقط إلى خادم موثوق به من نوع قيمة مفتاحية.

يمكن للمشترين والبائعين استخدام خادم مشترك موثوق به من نوع مفتاح-قيمة للمنصات المتوافقة مع "مبادرة حماية الخصوصية على Android" و"مبادرة حماية الخصوصية على الويب".