أرقام تعريف إعداد التقارير

التعرّف على طريقة عمل معرّفات إعداد التقارير في مزاد يستخدم Protected Audience API

نظرة عامة

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

تتيح لك معرّفات الإبلاغ إمكانية الإبلاغ عن معرّف إعلان، كما تتيح حالات استخدام مثل الصفقات.

هناك ثلاثة أرقام تعريف لإعداد التقارير من نوعَين:

• معرّفات إعداد التقارير غير القابلة للاختيار
  • buyerReportingId (سلسلة)
  • buyerAndSellerReportingId (سلسلة)
• معرّفات إعداد التقارير القابلة للاختيار
  • ‫selectableBuyerAndSellerReportingIds (مصفوفة من السلاسل النصية)

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

معرّفات التقارير غير القابلة للاختيار

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

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

لا تتوفّر المعرّفات غير القابلة للاختيار داخل generateBid() وscoreAd() إذا لم يتم استخدامها مع معرّفات إعداد التقارير القابلة للاختيار.

أرقام التعريف المستخدَمة في إعداد التقارير ضمن مجموعات الاهتمامات

يحدّد المشتري معرّفات إعداد التقارير لكل إعلان في مجموعة اهتمامات:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

إعداد تقارير البائعين

خلال مرحلة إعداد تقارير البائع، تصبح القيمة buyerAndSellerReportingId متاحة لـ reportResult():

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

قبل أن يصبح المعرّف متاحًا داخل reportResult()، يتم التحقّق من إخفاء هوية عدد معيّن من المستخدمين باستخدام مالك مجموعة الاهتمامات وعنوان URL لبرنامج نصي خاص بالمزايدة وعنوان URL للعرض وحجم الإعلان (يتم استبعاد حجم الإعلان من عملية التحقّق هذه حتى الربع الأول من عام 2025 على الأقل). إذا لم يكن المعرّف مجهول الهوية بمقدار k، سيظلّ يتم تشغيل الدالة reportResult()، ولكن لن تتوفّر قيمة معرّف إعداد التقارير داخل الدالة.

إعداد تقارير المشترين

خلال مرحلة إعداد تقارير المشتري في المزاد، يصبح معرّف إعداد تقارير واحد متاحًا reportWin(). إذا تم تحديد أكثر من معرّف تقارير واحد في مجموعة الاهتمامات، يتم تطبيق قاعدة إعادة الكتابة حيث يحلّ buyerAndSellerReportingId محلّ buyerReportingId:

• إذا تم تحديد كل من buyerAndSellerReportingId وbuyerReportingId، سيحلّ buyerAndSellerReportingId محلّ buyerReportingId، وسيتوفّر buyerAndSellerReportingId داخل reportWin().
• إذا تم تحديد buyerReportingId فقط، ستكون buyerReportingId متاحة.
• إذا لم يتم تحديد buyerAndSellerReportingId أو buyerReportingId، ستتوفّر interestGroupName.

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

يتم التحقّق من إخفاء هوية عدد معيّن من المستخدمين لرقم تعريف إعداد التقارير الذي يصبح متاحًا داخل reportWin() مع مالك مجموعة الاهتمامات وعنوان URL لبرنامج عروض الأسعار النصي وعنوان URL لعرض الإعلان وحجم الإعلان (يتم استبعاد حجم الإعلان من هذا التحقّق حتى الربع الأول من عام 2025 على الأقل). إذا لم تجتَز عملية التحقّق من عدم الكشف عن الهوية، سيظلّ reportWin() يعمل، ولكن لن تتوفّر قيمة معرّف إعداد التقارير داخل الدالة.

تم تحديد buyerReportingId فقط

في حال تحديد buyerReportingId فقط في إعدادات مجموعة الاهتمامات:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

بعد ذلك، يتوفّر buyerReportingId داخل reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

قبل أن يصبح buyerReportingId متاحًا لـ reportWin()، يتم التحقّق من إخفاء هوية عدد معيّن من المستخدمين باستخدام مالك مجموعة الاهتمامات وعنوان URL لبرنامج عروض الأسعار النصي وعنوان URL للعرض وحجم الإعلان (يتم استبعاد حجم الإعلان من هذا التحقّق حتى الربع الأول من عام 2025 على الأقل).

تم تحديد buyerAndSellerReportingId فقط

في حال تحديد buyerAndSellerReportingId فقط في إعدادات مجموعة الاهتمامات:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

بعد ذلك، يتوفّر buyerAndSellerReportingId داخل reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

قبل أن يصبح buyerAndSellerReportingId متاحًا لـ reportWin()، يتم التحقّق من إخفاء هوية عدد معيّن من المستخدمين باستخدام مالك مجموعة الاهتمامات وعنوان URL لبرنامج عروض الأسعار النصي وعنوان URL للعرض وحجم الإعلان (يتم استبعاد حجم الإعلان من هذا التحقّق حتى الربع الأول من عام 2025 على الأقل).

تم تحديد كل من buyerAndSellerReportingId وbuyerReportingId

في حال تحديد كلّ من buyerAndSellerReportingId وbuyerReportingId في إعدادات مجموعة الاهتمامات:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

بعد ذلك، لن يتوفّر سوى buyerAndSellerReportingId داخل reportWin() بسبب سلوك الكتابة فوق البيانات:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

قبل أن يصبح buyerAndSellerReportingId متاحًا لـ reportWin()، يتم التحقّق من إخفاء هوية عدد معيّن من المستخدمين باستخدام مالك مجموعة الاهتمامات وعنوان URL لبرنامج عروض الأسعار النصي وعنوان URL للعرض وحجم الإعلان (يتم استبعاد حجم الإعلان من هذا التحقّق حتى الربع الأول من عام 2025 على الأقل).

لم يتم تحديد buyerAndSellerReportingId أو buyerReportingId

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

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

بعد ذلك، ستتوفّر المجموعة المهتمة بموضوع معيّن name داخل reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

قبل أن يصبح اسم فئة الاهتمامات (interestGroupName) متاحًا reportWin()، يتم التحقّق من إخفاء هوية عدد معيّن من المستخدمين مع مالك فئة الاهتمامات وعنوان URL لبرنامج عروض الأسعار النصي وعنوان URL لعرض الإعلان وحجم الإعلان (يتم استبعاد حجم الإعلان من عملية التحقّق هذه حتى الربع الأول من عام 2025 على الأقل).

أرقام التعريف التي يمكن اختيارها لإعداد التقارير

تسمح معرّفات إعداد التقارير القابلة للاختيار للمشتري باختيار معرّف أثناء إنشاء عروض الأسعار، ويتيح المتصفّح القيمة المحدّدة لوظائف scoreAd() وإعداد التقارير. يتم توفير القيمة selectableBuyerAndSellerReportingIds، وهي عبارة عن مصفوفة من السلاسل، إلى generateBid()، ويمكن للمشتري عرض معرّف واحد محدّد كـ selectedBuyerAndSellerReportingId.

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

عند استخدام أرقام تعريف إعداد التقارير غير القابلة للاختيار مع أرقام تعريف إعداد التقارير القابلة للاختيار، يتغيّر سلوكها عن سير العمل الموضّح في القسم السابق. على عكس السلوك الأوّلي لمعرّفات إعداد التقارير غير القابلة للاختيار والتي لا تتوفّر إلا داخل وظائف إعداد التقارير، تتيح معرّفات إعداد التقارير القابلة للاختيار إتاحة معرّفات إعداد التقارير غير القابلة للاختيار داخل generateBid() وscoreAd() أيضًا.

مجموعة الاهتمامات

حقل معرّفات التقارير القابلة للاختيار - selectableBuyerAndSellerReportingIds - هو مجموعة من السلاسل التي يحدّدها المعلِن في مجموعة الاهتمامات لأحد الإعلانات. يمكن أيضًا تحديد معرّفات إعداد التقارير غير القابلة للاختيار إلى جانب معرّفات إعداد التقارير القابلة للاختيار:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

إنشاء عروض أسعار المشترين

إذا تم تحديد selectableBuyerAndSellerReportingIds في إعدادات مجموعة الاهتمامات، سيصبح متاحًا داخل generateBid() إلى جانب أرقام التعريف الأخرى لإعداد التقارير التي تم تحديدها.

function generateBid(interestGroup, ...) {
  const [{
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }] = interestGroup.ads;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

يمكن للمشتري اختيار أحد أرقام التعريف من مصفوفة selectableBuyerAndSellerReportingIds في generateBid() وعرض رقم التعريف المحدّد كـ selectedBuyerAndSellerReportingId. يتم رفض عرض السعر إذا لم تكن القيمة المحدّدة في مصفوفة selectableBuyerAndSellerReportingIds. إذا تم تحديد selectableBuyerAndSellerReportingIds في إعدادات مجموعة الاهتمامات، ولم يعرض المشتري selectedBuyerAndSellerReportingId من generateBid()، ستعود أرقام التعريف المستخدَمة في إعداد التقارير إلى السلوك الموضّح في أرقام التعريف غير القابلة للاختيار المستخدَمة في إعداد التقارير.

selectedbuyerAndSellerReportingId لا يمكن أن يفوز عرض السعر الذي تتضمّن قيمتهبالمزادselectedbuyerAndSellerReportingId إلا إذا كانت قيمة selectedbuyerAndSellerReportingId مجهولة الهوية بشكل مشترك مع buyerAndSellerReportingId (إذا كانت متوفّرة) وbuyerReportingId (إذا كانت متوفّرة) ومالك المجموعة المهتمة وعنوان URL لبرنامج عروض الأسعار وعنوان URL لعرض الإعلان وحجم الإعلان (يتم استبعاد حجم الإعلان من عملية التحقّق هذه حتى الربع الأول من عام 2025 على الأقل).

تسجيل نقاط إعلانات البائعين

بالنسبة إلى البائع، يصبح المعرّف selectedBuyerAndSellerReportingId الذي أرجعه المشتري من generateBid() متاحًا في scoreAd()، بالإضافة إلى buyerAndSellerReportingId إذا تم تحديده في إعدادات مجموعة الاهتمامات.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

إعداد تقارير البائعين

بالنسبة إلى تقارير البائعين، يصبح المعرّف selectedBuyerAndSellerReportingId الذي أرجعه المشتري من generateBid() متاحًا في reportResult()، بالإضافة إلى buyerAndSellerReportingId، إذا تم تحديده في مجموعة الاهتمامات.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

إذا تم تحديد selectableBuyerAndSellerReportingIds في إعدادات مجموعة الاهتمامات، وتم عرض selectedBuyerAndSellerReportingId من generateBid()، لا يمكن أن يفوز عرض السعر بالمزاد ما لم يكن selectedBuyerAndSellerReportingId وbuyerAndSellerReportingId (في حال توفّره) مجهولَين وفقًا لمعيار k مع مالك مجموعة الاهتمامات وعنوان URL لبرنامج نصي لعرض الأسعار وعنوان URL للعرض وحجم الإعلان (يتم استبعاد حجم الإعلان من عملية التحقّق هذه حتى الربع الأول من عام 2025 على الأقل)، ولن يتم تنفيذ reportResult() لعرض السعر هذا. لذلك، إذا تم استدعاء reportResult() بقيمة selectedBuyerAndSellerReportingId، يعني ذلك أنّ معرّفات إعداد التقارير اجتازت عملية التحقّق من عدم الكشف عن الهوية، وستتوفّر جميع معرّفات إعداد التقارير المحدّدة داخل reportResult().

إعداد تقارير المشترين

إذا تم تحديد selectableBuyerAndSellerReportingIds في إعدادات المجموعة ذات الاهتمامات المشتركة، وتم عرض selectedBuyerAndSellerReportingId من generateBid()، ستصبح جميع أرقام تعريف إعداد التقارير التي تم تحديدها في إعدادات المجموعة ذات الاهتمامات المشتركة متاحة. يُرجى العِلم أنّه على غرار تقارير البائعين، إذا لم تكن معرّفات التقارير مجهولة الهوية بمقدار k، لن تتمكّن من الفوز بالمزاد ولن يتم عرض reportWin() لهذا العرض.

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

قواعد الاستبدال

نلخّص هنا قواعد الكتابة فوق البيانات لكلّ من أرقام تعريف التقارير غير القابلة للاختيار وأرقام تعريف التقارير القابلة للاختيار. يحدّد المتصفّح أيّ من selectableBuyerAndSellerReportingIds وbuyerAndSellerReportingId وbuyerReportingId واسم مجموعة الاهتمامات سيتم تمريره إلى reportWin()، وذلك باستخدام المنطق التالي:

• إذا تم عرض selectedBuyerAndSellerReportingId من عرض سعر، ستكون selectedBuyerAndSellerReportingId وbuyerAndSellerReportingId (إذا تم تحديدهما في مجموعة الاهتمامات) وbuyerReportingId (إذا تم تحديدهما في مجموعة الاهتمامات) متاحة جميعًا لإعداد التقارير.
• بخلاف ذلك، إذا تم تحديد buyerAndSellerReportingId في مجموعة الاهتمامات، لن يتوفّر سوى buyerAndSellerReportingId لإعداد التقارير.
• بخلاف ذلك، إذا تم تحديد buyerReportingId في مجموعة الاهتمامات، لن يتوفّر سوى buyerReportingId لإعداد التقارير.
• في ما عدا ذلك، لا تتوفّر سوى المجموعة ذات الاهتمامات المشتركة name لإعداد التقارير.

يوضّح الجدول التالي سلوك الكتابة فوق البيانات:

التفاعل مع الملاحظات ومشاركتها

• لمزيد من المعلومات عن معرّفات إعداد التقارير، يُرجى الاطّلاع على قسم "معرّف إعداد التقارير" في شرح Protected Audience.
• ‫GitHub: طرح الأسئلة ومتابعة المناقشات في المشاكل على مستودع واجهة برمجة التطبيقات
• W3C: مناقشة حالات الاستخدام في المجال في اجتماع WICG
• الإشعارات: يمكنك الانضمام إلى القائمة البريدية أو الاطّلاع عليها.
• دعم المطوّرين في "مبادرة حماية الخصوصية": يمكنك طرح الأسئلة والانضمام إلى المناقشات في مستودع "دعم المطوّرين في مبادرة حماية الخصوصية".
• Chromium: إبلاغ فريق Chromium عن خطأ لطرح أسئلة حول التنفيذ المتاح للاختبار في Chrome.