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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

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

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

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

  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. تتولّى ميزة "القياس المحدود للإعلانات" في نظام التشغيل إرسال طلب إلى عنوان URL لخادم تكنولوجيا الإعلان المقدَّم من خلال العنوان Attribution-Reporting-Register-OS-Trigger.

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

  7. ستنفّذ ميزة"الإحالة الناجحة المحدودة" على مستوى نظام التشغيل عملية تحديد المصدر وفقًا للمنطق نفسه المطبَّق على تحديد المصدر من تطبيق إلى تطبيق، وسترسل التقارير نفسها.

سير العمل

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

  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. يعرض Chrome عنوان الطلب Attribution-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. تُرسِل واجهة برمجة تطبيقات نظام التشغيل طلبًا ثانويًا إلى معرّف الموارد المنتظم (URI) الخاص بتكنولوجيا الإعلان الذي تم تمريره من المتصفّح.

      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
    • لإكمال عملية تسجيل المشغّل، يجب أن تستجيب نقطة نهاية تكنولوجيا الإعلان لطلب واجهة برمجة التطبيقات Attribution Reporting API على Android باستخدام عنوان الاستجابة.
    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. يشتري المستخدم السترة في تطبيق التسوّق، ثم تسجّل تكنولوجيا الإعلان في تطبيق المعلِن عامل تشغيل الإحالة الناجحة باستخدام واجهة برمجة التطبيقات Attribution Reporting API على Android. يمكن لواجهة برمجة التطبيقات Attribution Reporting API على مستوى نظام التشغيل مطابقة المصدر على الويب مع مشغّل التطبيق وإرسال التقارير ذات الصلة.

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

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

  1. تسجّل تكنولوجيا الإعلان مصدرًا وتتحقّق من توفّر نظام التشغيل في Attribution Reporting API

  2. تعرض واجهة برمجة التطبيقات ARA على الويب معلومات حول المنصة المتوافقة

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

  4. يتم إجراء عملية الاتصال بـ registerWebSource() في الخلفية، ولا يحتاج المطوّر إلى الاتصال بـ registerWebSource() مباشرةً من خلال نظام التشغيل.

  5. تتولّى ميزة "قيود الإعلان على مستوى نظام التشغيل" إرسال طلب إلى عنوان URL لخادم تكنولوجيا الإعلان المقدَّم من خلال العنوان Attribution-Reporting-Register-OS-Source

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

تسجيل مشغّل التطبيق:

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

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

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

  4. ستنفّذ ميزة"الإحالة الناجحة المحدودة" على مستوى نظام التشغيل عملية تحديد المصدر وفقًا للمنطق نفسه المطبَّق على تحديد المصدر من تطبيق إلى تطبيق، وسترسل التقارير نفسها.

سير العمل

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

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

    • في ما يتعلّق بحالة استخدام الويب إلى التطبيق، عند تسجيل مصدر، يجب تحديد مَعلمة مصدر تحديد المصدر مباشرةً، إما باستخدام العلامة attributionsrc أو باستخدام تسجيل JavaScript.
    • يستخدم المثال التالي العلامة attributionsrc لتحديد مَعلمة المصدر:
    <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. تبدأ واجهة برمجة التطبيقات الخاصة بنظام التشغيل طلب بيانات ثانويًا من واجهة برمجة التطبيقات إلى معرّف الموارد المنتظم (URI) الخاص بتكنولوجيا الإعلان الذي تم تمريره من المتصفّح.
    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
    • لإكمال عملية تسجيل المصدر، يجب أن تستجيب نقطة نهاية تكنولوجيا الإعلان لطلب واجهة برمجة التطبيقات Attribution Reporting API على Android من خلال عنوان الاستجابة Attribution-Reporting-Register-Source. يجب أن تحدّد الاستجابة أيضًا وجهة التطبيق في حقل الوجهة.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}

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

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

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

  1. إعداد وجهتَين

    • قد يتم إعداد بعض الحملات لتحقيق إحالات ناجحة في تطبيق المعلِن أو على صفحة المعلِن على الويب، وذلك استنادًا إلى عوامل مختلفة، مثل ما إذا كان المستخدم قد ثبَّت التطبيق.
    • في هذه الحالات، يُنصح بتفويض تسجيل المصدر إلى نظام التشغيل حيثما كان ذلك متاحًا، كي يمكن تحديد مصدر الإحالة بشكل صحيح بغض النظر عن مكان حدوث المشغّل. عند تسجيل المصدر لدى نظام التشغيل، يمكن تحديد كل من التطبيق والوجهة على الويب في المَعلمات ذات الصلة.
    • يجب أن تكون وجهة التطبيق في الحقل destination
    • يجب أن تكون وجهة الويب في الحقل web_destination
    • على مطوّري Chrome الانتباه إلى أنّ الحقل destination الخاص بواجهة برمجة التطبيقات Attribution Reporting لنظام التشغيل يجب أن يكون حزمة تطبيق وليس عنوان 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 Custom Tabs

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

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

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

  3. تسجيل مصدر CCT ومشغّل CCT

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

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

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

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

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

      القيمة الوصف مثال على حالة الاستخدام
      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() من نظام التشغيل، وسيتم بدء طلب بيانات ثانوي من واجهة برمجة التطبيقات Android Attribution Reporting API إلى معرّف الموارد المنتظم (URI) الخاص بتكنولوجيا الإعلان.

      • لإكمال عملية تسجيل المصدر، يجب أن تستجيب نقطة نهاية تكنولوجيا الإعلان لطلب واجهة برمجة التطبيقات Attribution Reporting API على Android من خلال عنوان الاستجابة.
       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. لإكمال عملية تسجيل المشغّل، يجب أن تستجيب نقطة نهاية تكنولوجيا الإعلان لطلب واجهة برمجة التطبيقات Attribution Reporting API على Android من خلال عنوان الاستجابة.

    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"]}
    ],
    ...
}

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

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

للحصول على خطوات عامة لتحديد المشاكل وحلّها في Attribution Reporting، يُرجى الرجوع إلى كتاب الطبخ لتحديد المشاكل وحلّها.