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

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

نظرة عامة

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

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

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

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

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

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

ملاحظة مهمة: يتم التحقّق من أرقام تعريف إعداد التقارير للتأكّد من أنّها تتوافق مع مبدأ "المَعلمة k" قبل أن تصبح متاحة داخل دوال إعداد التقارير (reportResult() وreportWin()).

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

مدى توفّر أرقام تعريف إعداد التقارير القابلة للاختيار

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()، يتم التحقّق من ميزة "المعرّف المجهول بعامل k" مع مالك مجموعة الاهتمامات وعنوان 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() للتأكّد من أنّه يتوافق مع مبدأ "المجهوليّة من النوع k" مع مالك مجموعة الاهتمامات وعنوان 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 من أجل ضمان الحفاظ على خصوصية k-anonymity مع مالك مجموعة الاهتمامات وعنوان 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 من أجل التأكّد من أنّها تلتزم بمبدأ "المجانَبَة بعامل k" مع مالك مجموعة الاهتمامات وعنوان 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، يتم التحقّق من buyerAndSellerReportingId من أجل الحفاظ على خصوصية k-anonymity مع مالك مجموعة الاهتمامات وعنوان 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" مع مالك مجموعة الاهتمامات وعنوان URL لنصّ عروض الأسعار وعنوان URL لعرض الإعلان وحجم الإعلان (يتم استبعاد حجم الإعلان من هذا التحقّق حتى الربع الأول من العام 2025 على الأقل).

أرقام تعريف تتبُّع الأداء القابلة للاختيار

مدى توفّر أرقام تعريف إعداد التقارير مع رقم تعريف إعداد تقارير قابل للاختيار

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

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

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

ملاحظة: ستتوفّر معرّفات إعداد التقارير القابلة للاختيار في الإصدار الثابت من الإصدار 130. قبل أن تصل معرّفات إعداد التقارير القابلة للاختيار إلى الإصدار الثابت، يمكن اختبارها من خلال تشغيل Canary M130 من سطر الأوامر باستخدام العلامات --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport

.

مجموعة الاهتمامات المشتركة

حقل أرقام تعريف الإبلاغ القابلة للاختيار - 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 مشتركةً مع buyerAndSellerReportingId (في حال توفّرها) وbuyerReportingId (في حال توفّرها) وصاحب مجموعة الاهتمامات وعنوان URL لنص عروض الأسعار وعنوان URL لعرض الإعلان وحجم الإعلان (يتم استبعاد حجم الإعلان من هذا التحقّق حتى الربع الأول من عام 2025 على الأقل).selectedbuyerAndSellerReportingId

ملاحظة: في الحالات التي تتم فيها إعادة تشغيل generateBid() لأنّ الطلب الأوّلي لم ينتج أي عروض أسعار تتضمّن إعلانات اجتازت عمليات التحقّق من إخفاء الهوية بالعدد k، لن تكون أرقام تعريف تقارير المشترين والبائعين القابلة للاختيار التي لا تجتاز عملية التحقّق من إخفاء الهوية بالعدد k متوفّرة في مجموعة الاهتمامات عند إعادة التشغيل.

تقييم إعلانات البائعين

بالنسبة إلى البائع، يصبح 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 فقط لإعداد التقارير.

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

هل تمّ تحديد أرقام تعريف إعداد التقارير في إعداد مجموعة الاهتمامات؟			معرّفات إعداد التقارير المتاحة
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
نعم، واخترت في generateBid()	اختياري	اختياري	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (في حال تحديدها) 3) buyerReportingId (في حال تحديدها)	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (في حال تحديدها)
لا، أو لم يتم اختيار في generateBid()	نعم	تم تجاهلها	buyerAndSeller ReportingId	buyerAndSeller ReportingId
لا، أو لم يتم اختيار في generateBid()	لا	نعم	buyerReportingId	بدون
لا، أو لم يتم اختيار في generateBid()	لا	لا	interestGroupName	بدون

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

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