دليل التنفيذ على مستوى المواقع الإلكترونية والتطبيقات في Attribution Reporting API

تتيح Attribution Reporting API تحديد المصدر على مستوى التطبيقات والمواقع الإلكترونية للنقرات التي تتم على الجهاز نفسه. يمكن للمتصفّحات، مثل Chrome، تفويض تسجيلات المصدر والعامل المشغِّل إلى Attribution Reporting API لنظام التشغيل Android بدلاً من معالجة هذه التسجيلات في المتصفّح. يتيح ذلك لنظام التشغيل Android مطابقة المصادر وعوامل التفعيل على مستوى كلٍّ من المواقع الإلكترونية والتطبيقات.

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

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

تسجيل المصادر وعوامل التفعيل باستخدام نظام التشغيل Android

لن تتوفّر ميزة تحديد المصدر على مستوى التطبيقات والويب إلا إذا تم تفعيل واجهة برمجة التطبيقات Attribution reporting API في كلّ من المتصفّح ونظام التشغيل Android على الجهاز نفسه. يتم إرسال مدى توفّر واجهة برمجة التطبيقات Attribution Reporting API لنظام التشغيل Android من خلال العنوان Attribution-Reporting-Support. سيعرض هذا العنوان os أو web أو كليهما، حسب ما هو متاح على ذلك الجهاز. إذا كان كلاهما متاحًا، ستتمكّن تكنولوجيات الإعلان من اختيار تسجيل مصادر الويب وعوامل بدء الويب إما في المتصفّح أو نظام التشغيل.

على تكنولوجيا الإعلان تحديد ما إذا كان سيتم تسجيل مصدر الويب أو عامل تشغيل الويب مع المتصفّح أو نظام التشغيل.

  • بالنسبة إلى الحملات على الويب فقط، لا تزال تكنولوجيات الإعلان قادرة على تسجيل كلّ من المصادر وعوامل التفعيل باستخدام Attribution Reporting API في Chrome أو اختيار تفويض كليهما إلى نظام التشغيل. بالنسبة إلى الحملات على الويب فقط التي قد يحدث فيها المصدر أو العامل المشغِّل في WebView، على تكنولوجيات الإعلان تفويض تسجيلَي المصدر والعامل المشغِّل إلى نظام التشغيل. راجِع القسم الخاص بـ WebViews للحصول على مزيد من المعلومات.

  • على تكنولوجيات الإعلان تجنُّب تسجيل المصادر وعوامل التفعيل باستخدام واجهات برمجة التطبيقات لكلّ من Chrome وAndroid في الوقت نفسه لتجنُّب إنشاء تقارير تحديد مصدر مكرّرة.

  • ويتمّ تحديد المصدر بشكل منفصل للمتصفّحات ونظام التشغيل. إذا تم تسجيل مصدر في المتصفّح ولكن تم تسجيل العامل المشغِّل في نظام التشغيل، لا يمكن مطابقة هذين المكوّنين بالعكس.

  • بالنسبة إلى المصادر التي قد تؤدي إلى تطبيق أو عامل تشغيل على الويب، ننصح بشدة بأن تفوض تقنية الإعلان تفويض عمليات تسجيل مصدر الويب وعامل التشغيل إلى واجهة برمجة التطبيقات Attribution Reporting API لنظام التشغيل Android.

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

  • بالنسبة إلى الحملات التي يحدث فيها كلّ من المصدر والعامل المشغِّل في أحد التطبيقات، يجب تسجيل كلاهما باستخدام OS Attribution Reporting API.

تسجيل مصدر تطبيق وعامل تشغيل على الويب

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

مثال

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

مسار تحديد المصدر من التطبيق إلى الموقع الإلكتروني
مسار تحديد المصدر من التطبيق إلى الموقع الإلكتروني

تسجيل مصدر التطبيق:

  1. تسجِّل حزمة تطوير البرامج (SDK) لتكنولوجيا الإعلان في تطبيق Daily News لنظام التشغيل Android النقرة باستخدام registerSource()

  2. تُرسِل واجهة برمجة التطبيقات Attribution Reporting API على Android طلبًا إلى خادم تكنولوجيا الإعلان عنوان URL المقدَّم إلى registerSource()

  3. يستجيب خادم تكنولوجيا الإعلان باستخدام العنوان Attribution-Reporting-Register-Source لإكمال تسجيل المصدر.

تسجيل عامل تشغيل الويب:

  1. تسجِّل تقنية الإعلان عامل تشغيل وتتحقّق من توفّر نظام التشغيل في واجهة برمجة التطبيقات Attribution Reporting API.

  2. تعرِض أداة ARA على الويب معلومات عن المنصة المتوافقة.

  3. يطلب الرأس OS-Trigger من واجهة برمجة تطبيقات ARA للويب طلب تنفيذ وظيفة registerWebTrigger() في واجهة برمجة تطبيقات ARA لنظام التشغيل.

  4. يتم إجراء المكالمة إلى registerWebTrigger() بشكل تلقائي ولا يحتاج المطوِّر إلى الاتصال بـ registerWebTrigger() باستخدام نظام التشغيل مباشرةً.

  5. يتولّى OS ARA إرسال طلب إلى عنوان URL لخادم تكنولوجيا الإعلان المقدَّم من العنوان Attribution-Reporting-Register-OS-Trigger.

  6. ستُكمِل تقنية الإعلان عملية تسجيل المشغِّل باستخدام واجهة برمجة التطبيقات لنظام التشغيل.

  7. ستُجري ميزة ARA لنظام التشغيل عملية تحديد المصدر وفقًا للمنطق نفسه المُطبَّق على تحديد مصدر التطبيق<>التطبيق، وستُرسِل التقارير نفسها.

سير العمل

تتضمّن الخطوات التالية تفاصيل إضافية حول كيفية إكمال المهمة:

  1. تسجِّل تقنية عرض الإعلانات من التطبيق مصدرًا في Attribution Reporting API من Android مع التعديلات التالية:

    • لتسجيل مصدر تطبيق يُتوقّع أن يحقّق إحالة ناجحة على موقع إلكتروني، يجب أن يتضمّن عنوان الاستجابة Attribution-Reporting-Register-Source وجهة موقع إلكتروني (eTLD+1) بدلاً من وجهة تطبيق.
    Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
      .
    • قد يستخدم بعض المعلِنين مقدّمي خدمات قياس متعدّدين (مثل أداة قياس أو أداة إحصاءات تابعة لجهة خارجية) باستخدام سلاسل عمليات إعادة التوجيه 302. في بعض الحالات، ستتّبع Attribution Reporting API مسار إعادة التوجيه المحدّد في عنوان Attribution-Reporting-Redirect في الخلفية، وفي الوقت نفسه، سيتم تنفيذ مسار إعادة التوجيه 302 في المقدّمة لطلبات التنقّل الحالية. ستنتقل هذه الطلبات إلى عنوان URL نفسه، وقد يؤدي ذلك إلى احتساب مقدّم خدمة القياس التابع لجهة خارجية عمليات التسجيل مرّتين. لتجنُّب التعداد المزدوج للتسجيلات، يمكن لتكنولوجيات الإعلان تعديل سلوك إعادة التوجيه لإرسال تسجيل Attribution Reporting API إلى عنوان URL بديل ومُحدَّد.

    • لتفعيل هذا السلوك، يجب أن تتضمّن تقنيات الإعلان عنوان HTTP جديدًا عند الردّ على طلب التسجيل:

      • العنوان هو Attribution-Reporting-Redirect-Config
      • يجب أن تكون قيمة العنوان هي redirect-302-to-well-known.
      Attribution-Reporting-Redirect-Config: redirect-302-to-well-known

    • وتتشابه بقية عملية تسجيل المصدر مع تسجيل مصدر عادي بين التطبيقات.

    .

  2. تسجِّل تقنية عرض الإعلانات على الموقع الإلكتروني للمعلِن عامل التفعيل من خلال طلب من Chrome تفويض التسجيل إلى واجهة برمجة التطبيقات Attribution Reporting API لنظام التشغيل Android:

    • بعد أن يُكمل المستخدِم إحالة ناجحة على موقع إلكتروني، ستقدّم تكنولوجيا الإعلان طلبًا لتسجيل العامل المشغِّل في Chrome.

      1. يمكن استخدام طلب علامة بكسل أو fetch() لتقديم طلب تسجيل ملف شخصي مشغِّل

      2. يعرض ChromeAttribution-Reporting-Support عنوان الطلب ويرسله إلى تقنية عرض الإعلانات. في حال تفعيل واجهة برمجة التطبيقات على كلّ من متصفّح Chrome و جهاز Android، سيعرض العنوانos, web.

      Attribution-Reporting-Support: os, web

    • بعد ذلك، من المفترض أن تطلب تقنية عرض الإعلانات من Chrome تفويض نظام التشغيل باستخدام العنوان Attribution-Reporting-Register-OS-Trigger الذي:

      1. يطلب من Chrome تفويض عملية التسجيل إلى نظام التشغيل

      2. يفوّض Chrome عملية التسجيل إلى نظام التشغيل من خلال استدعاء وظيفة واجهة برمجة التطبيقات لنظام التشغيل registerWebTrigger()

        • يتم إجراء المكالمة إلى registerWebTrigger() في الخلفية، ولا تحتاج تكنولوجيا الإعلان إلى الاتصال بـ registerWebTrigger() مباشرةً.

      3. تبدأ واجهة برمجة التطبيقات لنظام التشغيل طلب بيانات ثانويًا من واجهة برمجة التطبيقات إلى معرّف الموارد المنتظم لتكنولوجيا الإعلان الذي تم تمريره من المتصفّح.

      Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger",
"https://other-adtech.example/register-trigger"

    • في بعض الحالات، لا يتوفّر عنوان Attribution-Reporting-Support ولا يمكن إرساله. عند حدوث ذلك، سيظل بإمكان تكنولوجيا الإعلان ضبط منصّة مفضّلة لمعالجة تسجيل العامل المشغِّل من خلال تضمين عنوان Attribution-Reporting-Info. المفتاح هو preferred-platform والقيمة المسموح بها هي os وweb. سيستخدم المتصفّح النظام الأساسي المفضّل عند توفّره، وسيعود إلى نظام الويب الأساسي عند عدم توفّر نظام التشغيل.

    Attribution-Reporting-Info: preferred-platform=os
    • لإكمال تسجيل العامل المشغِّل، يجب أن تستجيب نقطة نهاية تكنولوجيا الإعلان لطلب Android Attribution Reporting API باستخدام عنوان الاستجابة.
    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}

تسجيل مصدر ويب وعامل تشغيل تطبيق

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

مثال

مستخدم يتصفّح موقعًا إلكترونيًا في متصفّح Chrome على هاتف Android يظهر له إعلان عن سترة من أحد متاجره المفضّلة. ينقر المستخدم على الإعلان ويتم نقله إلى التطبيق الذي سبق أن نزّله. تسجِّل تكنولوجيا الإعلان على الموقع الإلكتروني الذي تم عرض الإعلان عليه مصدر النقرة من خلال توجيه Chrome إلى تفويض التسجيل لواجهة برمجة التطبيقات Attribution Reporting API لنظام التشغيل Android بدلاً من استخدام Attribution Reporting API على Chrome. يشتري المستخدم سترة في تطبيق التسوّق. بعد ذلك، تسجِّل تقنية عرض الإعلانات في تطبيق المعلِن عامل تشغيل الإحالة الناجحة باستخدام واجهة برمجة التطبيقات Android Attribution Reporting API. يمكن لواجهة برمجة التطبيقات Attribution Reporting API على مستوى نظام التشغيل مطابقة مصدر الويب وعامل تشغيل التطبيق وإرسال التقارير ذات الصلة.

مسار تحديد المصدر من الموقع الإلكتروني إلى التطبيق
مسار تحديد المصدر من الويب إلى التطبيق

تسجيل مصدر الويب:

  1. تسجِّل تقنية عرض الإعلانات مصدرًا وتتحقّق من توفّر نظام التشغيل في واجهة برمجة التطبيقات Attribution Reporting API.

  2. تعرِض أداة ARA على الويب معلومات عن المنصة المتوافقة.

  3. يطلب الرأس OS-Source من واجهة برمجة تطبيقات ARA للويب طلب تنفيذ وظيفة registerWebSource() في واجهة برمجة تطبيقات ARA لنظام التشغيل.

  4. يتم إجراء المكالمة إلى registerWebSource() بشكل تلقائي ولا يحتاج المطوّر إلى الاتصال بـ registerWebSource() باستخدام نظام التشغيل مباشرةً.

  5. يتولّى OS ARA إرسال طلب إلى عنوان URL لخادم تكنولوجيا الإعلان الذي يقدّمهAttribution-Reporting-Register-OS-Source

  6. ستُكمِل تقنية الإعلان عملية تسجيل المصدر باستخدام واجهة برمجة التطبيقات لنظام التشغيل.

تسجيل مصدر بيانات التطبيق:

  1. تسجِّل حزمة تطوير البرامج (SDK) لتكنولوجيا الإعلان في تطبيق "متجر الملابس" على Android عامل التفعيل باستخدام نظام ARA لنظام التشغيل

  2. تُرسِل واجهة برمجة التطبيقات Attribution Reporting API على Android طلبًا إلى خادم تكنولوجيا الإعلان عنوان URL المقدَّم إلى registerTrigger()

  3. يستجيب خادم تكنولوجيا الإعلان باستخدام العنوان Attribution-Reporting-Register-Trigger لإكمال تسجيل المشغّل.

  4. ستُجري ميزة ARA لنظام التشغيل عملية تحديد المصدر وفقًا للمنطق نفسه المُطبَّق على تحديد مصدر التطبيق<>التطبيق، وستُرسِل التقارير نفسها.

سير العمل

تتضمّن الخطوات التالية تفاصيل إضافية حول كيفية إكمال المهمة:

  1. تسجِّل تقنية عرض الإعلانات على الموقع الإلكتروني للناشر المصدر من خلال توجيه Chrome إلى تفويض التسجيل لواجهة برمجة التطبيقات Attribution Reporting API لنظام التشغيل Android:

    • في حالة استخدام الويب للوصول إلى التطبيق، عند تسجيل مصدر، يجب تحديد مَعلمة تحديد المصدر source مباشرةً، إما باستخدام علامة attributionsrc أو باستخدام تسجيل JavaScript.
    • يستخدِم المثال التالي العلامة attributionsrc لتحديد مَعلمة source:
    <img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">

  2. يعرض Chrome عنوان الطلب Attribution-Reporting-Support لتكنولوجيا الإعلان. إذا كانت واجهة برمجة التطبيقات مفعّلة في كلّ من متصفّح Chrome وجهاز Android، سيعرض العنوان os, web.

    Attribution-Reporting-Support: os, web

  3. على تكنولوجيا الإعلان أن تطلب من Chrome تفويض واجهة برمجة التطبيقات على مستوى نظام التشغيل باستخدام العنوان Attribution-Reporting-Register-OS-Source الذي:

    1. يطلب من Chrome تفويض عملية التسجيل إلى نظام التشغيل
    2. يفوّض Chrome عملية التسجيل إلى نظام التشغيل من خلال استدعاء وظيفة واجهة برمجة التطبيقات لنظام التشغيل registerWebSource()
    3. يتم إجراء المكالمة إلى registerWebSource() بشكل تلقائي، ولا تحتاج تكنولوجيا الإعلان إلى الاتصال بـ registerWebSource() مباشرةً.
    4. تبدأ واجهة برمجة التطبيقات OS API طلب بيانات ثانويًا من واجهة برمجة التطبيقات إلى معرّف الموارد المنتظم لتكنولوجيا الإعلان الذي تم تمريره من المتصفّح.
    Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
    • في بعض الحالات، لا يتوفّر العنوان Attribution-Reporting-Support. وفي هذه الحالة، سيظل بإمكان تكنولوجيا الإعلان ضبط منصة مفضّلة للتعامل مع تسجيل المصدر من خلال تضمين العنوان Attribution-Reporting-Info. المفتاح هو preferred-platform والقيم المسموح بها هي os وweb. سيستخدم المتصفّح منصّة التشغيل المفضّلة عند توفّرها، وسيستخدم منصّة الويب عند عدم توفّر نظام التشغيل.
    Attribution-Reporting-Info: preferred-platform=os
    • لإكمال عملية تسجيل المصدر، يجب أن تستجيب نقطة نهاية تكنولوجيا الإعلان لطلب Android Attribution Reporting API باستخدام عنوان الاستجابة Attribution-Reporting-Register-Source. يجب أن يحدِّد الردّ أيضًا وجهة تطبيق في حقل الوجهة.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}

  4. تسجِّل تكنولوجيا الإعلان في تطبيق المعلِن عامل تشغيل في واجهة برمجة التطبيقات لخدمة تحليل الإحالات الناجحة على Android:

    • بالنسبة إلى عوامل التفعيل التي تحدث في التطبيقات، تسجِّل التطبيقات عوامل التفعيل باستخدام واجهة برمجة التطبيقات Android Attribution Reporting API كالمعتاد.

الحملات التي تتضمّن وجهات محتملة للتطبيقات والويب

  1. إعداد وجهات مزدوجة

    • قد يتم إعداد بعض الحملات لتحويل الإحالات الناجحة في تطبيق المعلِن أو على صفحة الويب الخاصة بالمعلِن استنادًا إلى عوامل مختلفة، مثل ما إذا كان المستخدِم قد ثبَّت التطبيق.
    • في هذه الحالات، يُنصح بتفويض تسجيل المصدر إلى نظام التشغيل حيثما كان ذلك متاحًا حتى يمكن تحديد المصدر بشكل صحيح بغض النظر عن مكان حدوث العامل المشغِّل. عند تسجيل المصدر في نظام التشغيل، يمكن تحديد كل من وجهة التطبيق والويب في المَعلمات ذات الصلة.
    • يجب أن تكون وجهة التطبيق في حقل destination.
    • يجب أن تكون وجهة الويب في الحقل web_destination.
    • على مطوّري Chrome ملاحظة أنّ حقل destination لواجهة برمجة التطبيقات OS Attribution Reporting API يجب أن يكون حزمة تطبيق وليس عنوان URL.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    "web_destination": "https://example.advertiser"
    ...
}
    • سيوضّح القسم التالي عن إعداد التقارير التقريبية كيفية تأثير استخدام الوجهات المزدوجة في التشويش في تقاريرك.

  2. استخدِم إعداد التقارير التقريبية لتقليل الضوضاء في التقارير على مستوى الحدث لمصادر الوجهة المزدوجة:

    • إذا تم تحديد كلّ من نظام التشغيل (التطبيق) ووجهة الويب في تسجيل المصدر، ستحدّد التقارير على مستوى الحدث ما إذا كان المشغّل قد حدث في وجهة ويب أو وجهة تطبيق تلقائيًا. ومع ذلك، للحفاظ على حدود الخصوصية، ستتم إضافة ضوضاء إضافية إلى هذه التقارير.
    • يمكن لتقنيات الإعلان استخدام الحقل coarse_event_report_destinations ضمن العنوان Attribution-Reporting-Register-Source لتفعيل إعداد التقارير التقريبية وتقليل التشويش. إذا حصل مصدر يتضمّن حقل coarse_event_report_destinations المحدّد على عملية الإحالة الناجحة، يتضمّن التقرير الناتج كلاً من وجهة التطبيق ووجهة الويب بدون تمييز مكان حدوث عامل التفعيل ، ولكن مع قدر أقل من التشويش مقارنةً بالتقارير التي يتم فيها تحديد وجهة التطبيق أو الويب.
    • لن تتغيّر التقارير المجمّعة.

بالنسبة إلى التطبيقات التي تستخدم علامات التبويب المخصّصة في Chrome

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

  1. سجِّل مصدر تطبيق وعامل تشغيل علامة تبويب مخصّصة:

  2. سجِّل مصدر علامة التبويب المخصّصة وعامل تشغيل التطبيق:

  3. تسجيل مصدر حملة إعلانية على شبكة البحث وعامل تشغيلها

بالنسبة إلى التطبيقات التي تستخدم WebView

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

  1. للسماح لـ WebViews باستخدام Attribution Reporting API، يجب ضبط التطبيق المضمّن باستخدام الأذونات الصحيحة.

  2. لا تتوفّر إلا عملية تحديد المصدر على مستوى نظام التشغيل في WebView. لن يعرض العنوان Attribution-Reporting-Support سوى os، ولن يعرضه إلا إذا كانت واجهة برمجة التطبيقات Android Attribution Reporting API متاحة.

  3. عند تفويض المهام إلى نظام التشغيل، قد يستخدم WebView registerSource أو registerWebSource وregisterTrigger أو registerWebTrigger. إنّ الطرق التي يستخدمها WebView يتم ضبطها من خلال التطبيق الذي يعرض WebView ويتم تحديدها على أساس كل WebView.

    • يتمثل الفرق بين registerSource وregisterWebSource في المصدر الذي يتم تسجيله باعتباره الناشر. باستخدام registerSource، يتم تسجيل التطبيق بصفته الناشر. ومن الأمثلة على حالات استخدام registerSource هو تطبيق الناشر الذي يعرض إعلانًا يتم عرضه باستخدام WebView. باستخدام registerWebSource، يتم تسجيل الموقع الإلكتروني المستضاف في WebView باعتباره ناشرًا. ومن الأمثلة على حالات استخدام registerWebSource تطبيق يستضيف WebView، ويعرض الموقع الإلكتروني الذي يعرضه WebView إعلانات. يتصرف registerTrigger وregisterWebTrigger بشكلٍ مشابه. يوضّح المخطّط البياني في العنصر رقم 3 سيناريوهات مختلفة لحالات يريد فيها مطوّر التطبيقات أو حِزم SDK ضبط واجهة برمجة التطبيقات لاستخدام registerSource أو registerWebSource، وregisterTrigger أو registerWebTrigger.
    • سيستخدِم WebView تلقائيًا registerSource وregisterWebTrigger عند استدعاء واجهة برمجة التطبيقات Attribution Reporting API لنظام التشغيل Android. يؤدي ذلك إلى ربط المصادر بالتطبيق وربط عوامل التفعيل بمصدر عنوان URL من المستوى الأعلى في WebView عند حدوث عامل التفعيل.

      • إذا كان التطبيق يتطلّب سلوكًا مختلفًا، عليه استخدام طريقة جديدة setAttributionRegistrationBehavior في فئة androidx.webkit.WebViewSettingsCompat. تحدِّد هذه الطريقة ما إذا كان يجب أن يُطلِق WebView registerWebSource() أو registerWebTrigger() بدلاً من registerSource() أو registerTrigger().

      • يجب ضبط هذا السلوك لكل WebView يتم تشغيله.

      • إذا كانت حزمة تطوير البرامج (SDK) لتكنولوجيا الإعلان تبدأ WebView، يجب أن تضبط حزمة SDK هذا السلوك التلقائي.

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

      القيمة الوصف مثال على حالة استخدام
      APP_SOURCE_AND_WEB_TRIGGER (التلقائي) السماح للتطبيقات بتسجيل مصادر التطبيقات (المصادر المرتبطة باسم حزمة التطبيق) وعوامل تشغيل الويب (عوامل التشغيل المرتبطة بنطاق eTLD+1) من WebView التطبيقات التي تستخدم WebView لعرض الإعلانات بدلاً من تفعيل تصفُّح الويب
      WEB_SOURCE_AND_WEB_TRIGGER السماح للتطبيقات بتسجيل مصادر الويب وعوامل تشغيل الويب من WebView تطبيقات المتصفّحات المستندة إلى WebView، حيث يمكن أن تحدث مرّات ظهور الإعلانات والإحالات الناجحة على المواقع الإلكترونية في WebView
      APP_SOURCE_AND_APP_TRIGGER السماح للتطبيقات بتسجيل مصادر التطبيقات وعوامل تشغيلها من WebView التطبيقات المستندة إلى WebView التي يجب فيها ربط مرّات ظهور الإعلانات والإحالات الناجحة دائمًا بالتطبيق بدلاً من النطاق العلوي للمستوى التالي (eTLD+1) لمكوّن WebView
      غير مفعّلة يؤدي هذا الإجراء إلى إيقاف تسجيل المصدر والعامل المشغِّل من WebView.
    1. تسجيلات المصدر والتشغيل من WebView

    2. على تكنولوجيات الإعلان الردّ على عمليات تسجيل المصادر باستخدام العنوان Attribution-Reporting-Register-OS-Source. استنادًا إلى السلوك الذي تم ضبطه لـ WebView، سيؤدي ذلك إلى استدعاء registerSource() أو registerWebSource() مع نظام التشغيل وبدء طلب بيانات ثانوي من واجهة برمجة التطبيقات من Reporting API لنظام التشغيل Android إلى معرّف الموارد المنتظم لتكنولوجيا الإعلان.

      • لإكمال عملية تسجيل المصدر، يجب أن تستجيب نقطة نهاية تكنولوجيا الإعلان لطلب Android Attribution Reporting API باستخدام عنوان الاستجابة.
       Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}

    3. ويظلّ الجزء المتبقّي من تسجيل المصدر كما هو.

    4. يجب أن تستجيب تكنولوجيات الإعلان لعمليات تسجيل العوامل المشغِّلة باستخدام العنوان Attribution-Reporting-Register-OS-Trigger. استنادًا إلى السلوك المضبوط لـ WebView، سيؤدي ذلك إلى طلب registerTrigger() أو registerWebTrigger() من نظام التشغيل وبدء طلب ثانوي من واجهة برمجة التطبيقات من Rb إلى معرّف الموارد المنتظم لتكنولوجيا الإعلان.

    5. لإكمال عملية تسجيل العامل المشغِّل، يجب أن تستجيب نقطة نهاية تكنولوجيا الإعلان لطلب Android Attribution Reporting API باستخدام عنوان الردّ.

    Attribution-Reporting-Register-OS-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}

تصحيح الأخطاء

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

للحصول على خطوات عامة لتصحيح أخطاء تقارير تحديد المصدر، يمكنك الرجوع إلى كتاب طبخ تصحيح الأخطاء.