بدء استخدام تقارير تحديد المصدر

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

في البداية، ستتعرّف على كيفية:

  • التمييز بين أنواع التقارير في Attribution Reporting API

  • إكمال خطوات تنفيذ واجهة برمجة التطبيقات وإنشاء التقارير

  • العثور على معلومات مرجعية وتحديد المشاكل وحلّها

اختيار نوع التقرير

لقياس أداء الحملات الإعلانية بشكل فعّال بمستويات مختلفة من التفاصيل والخصوصية، توفّر Attribution Reporting API نوعَين مختلفَين من التقارير:

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

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

نظرة عامة حول خطوات التنفيذ

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

شرط أساسي: يجب أن تتضمّن مواقعك الإلكترونية شهادات طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (HTTPS) قبل أن تتمكّن من تسجيل المصادر والمشغّلات وتلقّي التقارير.

إنشاء التقارير على مستوى الحدث

توضّح الخطوات التالية كيفية إنشاء تقارير على مستوى الحدث:

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

  2. تسجيل مشغّل: يتم تسجيل حدث إحالة ناجحة وربطه بمصدر مسجَّل سابقًا. راجِع تسجيل مشغّلات تحديد المصدر للحصول على التعليمات.

  3. إعداد نقطة نهاية لإعداد التقارير: أنشئ نقطة نهاية على خادمك لتلقّي التقارير على مستوى الحدث. يجب أن يكون عنوان URL لنقطة النهاية بالتنسيق التالي: {REPORTING_ENDPOINT}/.well-known/attribution-reporting/report-event-attribution. يمكنك الاطّلاع على نموذج الرمز في adtech.js لمعرفة مثال على طريقة POST. لمزيد من المعلومات حول .well-known، يُرجى الاطّلاع على Wikipedia.

للحصول على مزيد من التفاصيل حول التقارير على مستوى الحدث، اطّلِع على شرح التقارير على مستوى الحدث.

إنشاء تقرير موجز

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

  2. تسجيل مشغّل: كما هو الحال في التقارير على مستوى الحدث اطّلِع على تسجيل مشغّلات تحديد المصدر.

  3. إعداد نقطة نهاية لإعداد التقارير: أنشئ نقطة نهاية لتلقّي التقارير المجمّعة. يجب أن يكون عنوان URL هو: {REPORTING_ENDPOINT}/.well-known/attribution-reporting/report-aggregate-attribution. يمكنك الاطّلاع على adtech.js للحصول على مثال على طريقة POST وويكيبيديا للحصول على معلومات حول .well-known.

  4. تجميع التقارير وإرسالها: يتم تجميع التقارير المجمّعة وإرسالها إلى خدمة تجميع البيانات لمعالجتها. ستنشئ "خدمة تجميع البيانات" بعد ذلك تقارير موجَزة. لمزيد من المعلومات، اطّلِع على استراتيجيات التجميع.

للحصول على مزيد من المعلومات حول التقارير الموجزة، يُرجى الرجوع إلى شرح التقارير القابلة للتجميع.

بالإضافة إلى خطوات التنفيذ، ستساعدك المواضيع التالية في التخطيط لاستراتيجية إعداد التقارير الموجزة:

إعداد الفلاتر (اختياري)

للحصول على تحكّم أكثر دقة في بيانات تحديد المصدر التي تتلقّاها، يمكنك إعداد فلاتر.

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

لإعداد الفلترة، اطّلِع على تحديد قواعد مخصّصة باستخدام الفلاتر وقسم المشغّلات في تسجيل مشغّل تحديد المصدر للحصول على تفاصيل خاصة بالتقارير القابلة للتجميع.

التأكّد من تفعيل واجهة برمجة التطبيقات

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

if (document.featurePolicy.allowsFeature('attribution-reporting')) {
  // the Attribution Reporting API is enabled
}

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

الخطوات التالية

تقدّم الأقسام التالية معلومات إضافية حول بدء استخدام تقارير تحديد المصدر.

التنفيذ

الخلفية والمفاهيم

العروض التوضيحية والأدوات

التخطيط