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

التعرّف على آلية عمل أرقام تعريف إعداد التقارير في مزاد Protected Audience

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

ملاحظة: ستتوفّر أرقام تعريف إعداد التقارير القابلة للاختيار في الإصدار الثابت من الإصدار M130. قبل وصول أرقام تعريف التقارير القابلة للاختيار إلى القناة الثابتة، يمكن اختبارها من خلال إطلاق إصدار 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(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  } = browserSignals;

  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 على الأقل).

ملاحظة: في الحالات التي تتم فيها إعادة عرض generateBid() لأنّ الاستدعاء الأوّلي لم ينتج عنه أي عروض أسعار تتضمن الإعلانات التي اجتازت عمليات التحقّق من عدم المجهولة المصدر، لن تظهر في مجموعة الاهتمام ضمن مجموعة الاهتمام أثناء إعادة عرضها.

نتيجة إعلانات البائع

بالنسبة إلى البائع، يصبح 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 (في حال توفّرهما) مع مالك مجموعة الاهتمامات وعنوان URL للنص البرمجي لعرض الأسعار وعنوان URL للعرض وحجم الإعلان (يتم استبعاد حجم الإعلان من عملية الفحص هذه حتى الربع الأول من عام 2025 على الأقل)، ولن يتم تنفيذ reportResult() لعرض السعر هذا. وبالتالي، إذا تم استدعاء reportResult() مع قيمة selectedBuyerAndSellerReportingId، يعني ذلك أنّ أرقام تعريف التقارير قد اجتازت فحص الكشف عن الهوية التصنيفية، وأن جميع أرقام تعريف إعداد التقارير المحدّدة ستكون متاحة داخل reportResult().

تقارير المشترين

إذا تم تحديد selectableBuyerAndSellerReportingIds في إعداد مجموعة الاهتمامات وتم عرض selectedBuyerAndSellerReportingId من generateBid()، ستصبح جميع أرقام تعريف إعداد التقارير التي تم تحديدها في إعدادات مجموعة الاهتمامات متاحة. تجدر الإشارة إلى أنّه كما هو الحال في تقارير البائعين، إذا لم تكن أرقام تعريف إعداد التقارير مجهولة الهوية، لن يتمكّنوا من الفوز بالمزاد ولن تُعرَض بطاقة 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) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (إذا كانت محدَّدة) 3) buyerReportingId (إذا كانت محدَّدة)	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (إذا كانت محدَّدة)
لا، أو لم يتم الاختيار في generateBid()	نعم	تم تجاهلها	buyerAndSeller ReportingId	buyerAndSeller ReportingId
لا، أو لم يتم الاختيار في generateBid()	لا	نعم	buyerReportingId	بدون تحديد نمط
لا، أو لم يتم الاختيار في generateBid()	لا	لا	interestGroupName	بدون تحديد نمط

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

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