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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

التعرّف على طريقة عمل أرقام التعريف المخصّصة للإبلاغ في مزاد "الجمهور المحمي"

نظرة عامة

معرّفات إعداد التقارير هي معرّفات مرتبطة بإعلان وتكون متاحة للاستخدام في إنشاء عرض أسعار وتقييم عرض أسعار وإعداد التقارير. يقدّم المشتري أرقام تعريف إعداد التقارير في إعدادات مجموعة الاهتمامات، وتصبح متاحة في 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 على الأقل). إذا تعذّر اجتياز عملية التحقّق من إخفاء الهوية وفقًا لعدد k، سيستمر تنفيذ 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;
}

قبل أن تصبح reportWin() متاحة، يتم التحقّق من buyerReportingId من أجل إخفاء هوية عدد معيّن من المستخدِمين مع مالك مجموعة الاهتمامات وعنوان 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;
}

قبل أن تصبح reportWin() متاحة، يتم التحقّق من buyerAndSellerReportingId من أجل إخفاء هوية عدد معيّن من المستخدِمين مع مالك مجموعة الاهتمامات وعنوان 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;
}

قبل أن تصبح reportWin() متاحة، يتم التحقّق من buyerAndSellerReportingId من أجل إخفاء هوية عدد معيّن من المستخدِمين مع مالك مجموعة الاهتمامات وعنوان 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()، يتم التحقّق من إخفاء هوية عدد معيّن من المستخدِمين (k-anonymity) مع مالك مجموعة الاهتمامات وعنوان 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 مجهولة الهوية بشكلٍ مشترك مع 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، يعني ذلك أنّ معرّفات إعداد التقارير اجتازت عملية التحقّق من الخفيّة بدرجة k، وستكون جميع معرّفات إعداد التقارير المحدّدة متاحة داخل 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 فقط لإعداد التقارير.

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

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

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