הגדרה של נתוני קהל

כאן מוסבר איך להגדיר קהל על ידי יצירה של קבוצת תחומי עניין באמצעות Protected Audience API. אתם יכולים לקרוא את המדריך למפתחים על מחזור החיים המלא של Protected Audience API. אפשר גם לקרוא הסבר מפורט על Protected Audience API כדי לקבל הצעה מפורטת לגבי תיעוד של קבוצות של תחומי עניין על ידי הדפדפנים.

אין לך מפתחים? כדאי לעיין בסקירה הכללית על Protected Audience API.

קבוצות אינטרס של Protected Audience API

קבוצת תחומי עניין של Protected Audience API מייצגת קבוצה של אנשים עם תחום עניין משותף, שתואמת לרשימת רימרקטינג. לכל קבוצת אינטרס של Protected Audience API יש בעלים.

הבעלים של קבוצות תחומי עניין משמשים כקונים במכרז של מודעות Protected Audience API. חברות בקבוצת תחומי עניין נשמרת על ידי הדפדפן, במכשיר של המשתמש, ולא משותפת עם ספק הדפדפן או עם אף אחד אחר.

פונקציות API

joinAdInterestGroup()

הפלטפורמה למפרסמים (DSP) או המפרסם עצמו מתקשרים ל-navigator.joinAdInterestGroup() כדי לבקש מהדפדפן להוסיף קבוצת תחומי עניין לרשימת החברות של הדפדפן.

המקור של הקשר הקריאה עבור joinAdInterestGroup() חייב להתאים למקור של הבעלים של קבוצת האינטרס, כך שיהיה צורך להפעיל את joinAdInterestGroup() מ-iframe (לדוגמה, מ-DSP), אלא אם המקור של הבעלים של קבוצת האינטרס תואם למקור של המסמך הנוכחי (לדוגמה, אתר עם קבוצות אינטרס משלו).

לאפליקציה joinAdInterestGroup() נדרשת הרשאה מ:

• האתר שבו מבקרים
• הבעלים של קבוצת תחומי העניין

פירוש הדבר הוא שלא ניתן להפעיל על ידי malicious.example קריאה לפעולה מסוג joinAdInterestGroup() לקבוצת אינטרס שנמצאת בבעלות dsp.example.com, מבלי להעניק הרשאה על ידי dsp.example.com.

הרשאה מהאתר שביקרו בו

אפשר להעניק את ההרשאה מאותו מקור או מאותו מקורות. כברירת מחדל, ההרשאה ניתנת לקריאות joinAdInterestGroup() מאותו המקור שבו הגיע האתר שבו ביקרתם (במילים אחרות, מאותו המקור של המסגרת ברמה העליונה של הדף הנוכחי).

שימוש לדוגמה

הדוגמה הבאה ממחישה איך אפשר להגדיר קבוצת תחומי עניין ולבקש מהדפדפן להצטרף לקבוצה.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

הגודל של האובייקט interestGroup שמועבר לפונקציה לא יכול להיות יותר מ-50KiB, אחרת הקריאה תיכשל. הפרמטר השני מציין את משך הזמן של קבוצת תחומי העניין, שמוגבל ל-30 יום. קריאות עוקבות מבטלות ערכים שאוחסנו בעבר.

מאפיינים נדרשים

המאפיינים היחידים הנדרשים לקבוצות של תחומי עניין הם owner ו-name:

מאפיינים אופציונליים

שאר המאפיינים הם אופציונליים:

biddingLogicUrl^{1, 2}

לדוגמה: https://dsp.example/bid/custom-bikes/bid.js

תפקיד: כתובת URL לבידינג ב-JavaScript, מופעלת ב-worklet.

biddingWasmHelperUrl^{1, 2}

לדוגמה: https://dsp.example/bid/custom-bikes/bid.wasm

תפקיד: כתובת URL לקוד WebAssembly שנוצרה מ-biddingLogicUrl.

updateUrl²

לדוגמה: https://dsp.example/bid/custom-bikes/update

תפקיד: כתובת URL שמחזירה קובץ JSON לצורך עדכון מאפיינים של קבוצת תחומי עניין. (מידע נוסף זמין בקטע עדכון נתוני הקהל ורענון מודעות).

trustedBiddingSignalsUrl²

לדוגמה: https://dsp.example/trusted/bidding-signals

תפקיד: כתובת URL בסיסית עבור בקשות מפתח/ערך שנשלחות לשירות המפתח/ערך המהימן של מגיש הצעות המחיר.

trustedBiddingSignalsKeys

לדוגמה: ['key1', 'key2' ...]

תפקיד: מפתחות לבקשות לשירות מפתח/ערך מהימן-ערך.

userBiddingSignals

לדוגמה: {...}

תפקיד: מטא-נתונים נוספים שהבעלים יכולים להשתמש בהם במהלך הבידינג.

ads¹

לדוגמה: [bikeAd1, bikeAd2, bikeAd3]

התפקיד: מודעות שייתכן שיוצגו בקבוצת תחומי העניין הזו.

adComponents

לדוגמה: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]

תפקיד: רכיבים של מודעות שמורכבות מכמה חלקים.

¹ הנכסים biddingLogicUrl ו-ads הם אופציונליים, אבל הם נדרשים להשתתף במכרז. במקרים מסוימים, כדאי ליצור קבוצת תחומי עניין ללא הנכסים האלה: לדוגמה, יכול להיות שהבעלים של קבוצת תחומי העניין ירצה להוסיף דפדפן לקבוצה של תחומי עניין לקמפיין שלא פועל עדיין, או לשימוש אחר בעתיד, או שתקציב הפרסום שלו נגמר באופן זמני.

² בהטמעה הנוכחית של Protected Audience API, המקור של biddingLogicUrl, biddingWasmHelperUrl, updateUrl ו-trustedBiddingSignalsUrl צריך להיות זהה לזה של הבעלים. יכול להיות שזה לא אילוץ לטווח ארוך, וכתובות ה-URL ads ו-adComponents לא כוללות מגבלה כזו.

ציון מודעות לקבוצת אינטרס

האובייקטים ads ו-adComponents כוללים כתובת URL של קריאייטיב של מודעה, ובאופן אופציונלי, מטא-נתונים שרירותיים שאפשר להשתמש בהם בזמן הבידינג.

לדוגמה:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

leaveAdInterestGroup()

הבעלים של קבוצת תחומי העניין יכול לבקש הסרה של דפדפן מקבוצת תחומי עניין. הדפדפן מסיר את קבוצת האינטרס מרשימת החברות שלו.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

אם משתמש חוזר לאתר שבו ביקש מהדפדפן להוסיף קבוצת תחומי עניין, הבעלים של קבוצת תחומי העניין יכול להפעיל את הפונקציה navigator.leaveAdInterestGroup() כדי לבקש מהדפדפן להסיר את קבוצת תחומי העניין.

קוד של מודעה יכול לקרוא לפונקציה הזו גם עבור קבוצת תחומי העניין שלה.

שאלות נפוצות

מהו המספר המרבי של קבוצות אינטרס לכל בעלים של קבוצה למשתמש יחיד?

ב-Chrome יכולים להיות עד 1,000 קבוצות אינטרס לכל בעלים, ועד 1,000 בעלים של קבוצות אינטרס. המגבלות האלה נועדו לשמש כרכבות הגנה, ולא ניתן לנצל אותן בפעולה רגילה.

איך אפשר למקסם את המודעות של קבוצות תחומי עניין שעומדות בדרישות סף של k-anon?

כפי שצוין בהסבר ציבורי, קבוצה אחת של תחומי עניין יכולה לכלול מספר מודעות אפשריות שהיא עשויה להציג, לכן לקבוצה תהיה אפשרות להגיש הצעת מחיר מחדש על מודעה אחרת שתוגדר כ'מודעה חלופית' בכל פעם שהבחירה המועדפת עליו היא מתחת לסף. פירוש הדבר הוא שמודעה קטנה וייחודית שעדיין נמוכה מהסף של k-אנונימיות עדיין יכולה לבחור להשתתף במכרזים, ולקבוצת תחומי העניין שלה יש דרך לחזור למודעה כללית יותר, עד שלמודעה הספציפית יותר יהיה קהל גדול מספיק.

מבחינה טקטית, כדאי לשקול את הדברים הבאים:

• כדי להפעיל מודעה חדשה, פשוט מתחילים להגיש איתה הצעות מחיר במקרים שבהם אתם רוצים שהיא תוצג. אין צורך לבצע פעולה נוספת.
• אתם יכולים להשתמש במודעה חלופית במקרים שבהם מודעות חדשות הן לא k-anon. יש סיכון מסוים שהמודעה החלופית עצמה לא תהיה k-anon, לכן כדאי לפעמים להגיש הצעות מחיר רק עם המודעה החלופית. כדאי לעשות זאת ב-1% מהפעמים, לדוגמה, אם זו רמה טובה, כדי לוודא שהחלופה צפויה להיות גבוהה מהסף.

לאחרונה שוחחנו על דרכים אחרות שבהן דברים יכולים לפעול, לכן אם יש לכם תרחיש לדוגמה שבו המנגנון הזה עלול ליצור בעיה, המשיכו לשוחח באופן ציבורי על דרכים שבהן ה-API יכול להשתפר.

כל ההפניות ל-Protected Audience API

API reference guides are available:

• Developer guide for the Protected Audience API.
• Ad buyer guide to Protected Audience interest groups and bid generation.
• Ad seller guide to Protected Audience ad auctions.
• Guide to reporting auction results
• Best practices for Protected Audience ad auction latency
• Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.