מדריך למפתחים בנושא Protected Audience API

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

‫Protected Audience API ב-Android (לשעבר FLEDGE) כולל את Custom Audience API ואת Ad Selection API. פלטפורמות של טכנולוגיות פרסום ומפרסמים יכולים להשתמש בממשקי ה-API האלה כדי להציג מודעות מותאמות אישית על סמך אינטראקציות קודמות עם האפליקציה, שמגבילות את שיתוף המזהים בין האפליקציות ואת שיתוף המידע על האינטראקציות של המשתמש עם האפליקציה עם צדדים שלישיים.

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

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

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

במדריך הזה מוסבר איך להשתמש ב-Protected Audience API ב-Android כדי לבצע את הפעולות הבאות:

1. ניהול קהלים בהתאמה אישית
2. הגדרה והפעלה של בחירת מודעות במכשיר
3. דיווח על חשיפות של מודעות

לפני שמתחילים

לפני שמתחילים, צריך לבצע את הפעולות הבאות:

1. מגדירים את סביבת הפיתוח לארגז החול לפרטיות ב-Android.
2. מתקינים תמונת מערכת במכשיר נתמך או מגדירים אמולטור שכולל תמיכה בארגז החול לפרטיות ב-Android.

3. בטרמינל, מפעילים את הגישה ל-Protected Audience API (מושבת כברירת מחדל) באמצעות פקודת adb הבאה.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. בטרמינל, מפעילים את הדיווח על משואות באמצעות פקודות ה-adb הבאות.

    adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
    adb shell device_config put adservices fledge_register_ad_beacon_enabled true
   

5. צריך לכלול את ההרשאה ACCESS_ADSERVICES_CUSTOM_AUDIENCE במניפסט של האפליקציה:

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

6. מפנים להגדרת שירותי מודעות ברכיב <application> של קובץ המניפסט:

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

7. מציינים את משאב ה-XML של שירותי המודעות שאליו יש הפניה במניפסט, כמו res/xml/ad_services_config.xml. מידע נוסף על הרשאות של שירותי מודעות ובקרת גישה ל-SDK

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

8. כברירת מחדל, Ad Selection API אוכף מגבלות על כמות הזיכרון המקסימלית שסקריפט של מכרז או של דיווח על חשיפה יכול להקצות. כדי להשתמש בתכונה של הגבלת הזיכרון, צריך WebView בגרסה 105.0.5195.58 ומעלה. הפלטפורמה מבצעת בדיקת גרסה, והקריאות ל-API‏ selectAds ול-API‏ reportImpression נכשלות אם התנאי הזה לא מתקיים. יש שתי אפשרויות להגדרת התכונה הזו:

   • אפשרות 1: מריצים את פקודת adb הבאה כדי להשבית את הבדיקה הזו:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • אפשרות 2: התקנה של WebView בטא מחנות Google Play. המספר הזה צריך להיות שווה לגרסה שצוינה קודם או גבוה ממנה.

הצטרפות לקהל בהתאמה אישית

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

1. מאתחלים את האובייקט CustomAudienceManager.
2. יוצרים אובייקט CustomAudience על ידי ציון פרמטרים מרכזיים כמו חבילת הקונה ושם רלוונטי. לאחר מכן, מאתחלים את אובייקט JoinCustomAudienceRequest באמצעות אובייקט CustomAudience.
3. קוראים לפונקציה האסינכרונית joinCustomAudience() עם האובייקט JoinCustomAudienceRequest והאובייקטים הרלוונטיים Executor ו-OutcomeReceiver.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

השילוב של הפרמטרים הבאים מזהה באופן ייחודי כל אובייקט CustomAudience במכשיר:

• ‫owner: שם החבילה של האפליקציה הבעלים. הערך הזה מוגדר באופן מרומז כשם החבילה של האפליקציה שקוראת לפונקציה.
• ‫buyer: מזהה של רשת המודעות של הקונה שמנהלת את המודעות לקהל המותאם אישית הזה.
• ‫name: שם או מזהה שרירותי של קהל בהתאמה אישית.

קריאה חוזרת לפונקציה joinCustomAudience() עם מופע שונה של CustomAudience מעדכנת כל CustomAudience קיים עם פרמטרים תואמים של owner, buyer ו-name. כדי לשמור על הפרטיות, התוצאה של ה-API לא מבחינה בין 'יצירה' לבין 'עדכון'.

בנוסף, צריך ליצור את CustomAudience עם הפרמטרים הנדרשים האלה:

• כתובת URL לעדכון יומי: כתובת URL ב-HTTPS שמתבצעת לגביה שאילתה מדי יום ברקע כדי לעדכן את אותות הבידינג של המשתמשים בקהל מותאם אישית, נתוני בידינג מהימנים, כתובות URL ונתוני מטא-נתונים של מודעות.
• כתובת URL של לוגיקת בידינג: כתובת URL מסוג HTTPS שמתבצעת לגביה שאילתה במהלך בחירת המודעה כדי לאחזר לוגיקת בידינג של קונה ב-JavaScript. אפשר לראות את חתימות הפונקציות הנדרשות ב-JavaScript הזה.
• מזהים של הצגת מודעות: מזהה שרירותי שמוגדר על ידי טכנולוגיית הפרסום של הקונה. זהו אמצעי אופטימיזציה ליצירת מטען הייעודי (payload) של נתונים לניתוח מודעות.

פרמטרים אופציונליים לאובייקט CustomAudience יכולים לכלול:

• זמן ההפעלה: קהל בהתאמה אישית יכול להשתתף בתהליך בחירת המודעות ובעדכונים יומיים רק אחרי זמן ההפעלה שלו. לדוגמה, אפשר להשתמש בזה כדי לעודד משתמשים לא פעילים לחזור לאפליקציה.
• מועד התפוגה: מועד עתידי שאחריו קהל היעד המותאם אישית יוסר מהמכשיר.
• אותות בידינג של משתמשים: מחרוזת JSON שמכילה אותות של משתמשים, כמו הלוקאל המועדף של המשתמש, שקוד JavaScript של לוגיקת הבידינג של הקונה צורך כדי ליצור הצעות מחיר במהלך תהליך בחירת המודעות. הפורמט הזה עוזר לפלטפורמות טכנולוגיות פרסום לעשות שימוש חוזר בקוד בפלטפורמות שונות, ומקל על השימוש בפונקציות JavaScript.
• נתוני בידינג מהימנים: כתובת URL של HTTPS ורשימה של מחרוזות שמשמשות במהלך תהליך בחירת המודעות, שבאמצעותן מתבצעת אחזור של אותות בידינג משירות מהימן של זוגות מפתח/ערך.
• Ads: רשימה של אובייקטים מסוג AdData שמתאימים למודעות שמשתתפות בתהליך בחירת המודעות. כל אובייקט AdData מורכב מהפרטים הבאים:
  • כתובת URL של רכיב ה-Render: כתובת URL מסוג HTTPS שמתבצעת לגביה שאילתה כדי להציג את המודעה הסופית.
  • מטא-נתונים: אובייקט JSON שעבר סריאליזציה כמחרוזת, ומכיל מידע שמשמש את לוגיקת הבידינג של הקונה במהלך תהליך בחירת המודעות.
  • מסנני מודעות: מחלקה שמכילה את כל המידע הנדרש לסינון מודעות להתקנת אפליקציות ולהגבלת תדירות הצגת המודעות במהלך בחירת המודעות.

דוגמה ליצירת מופע של אובייקט CustomAudience:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

טיפול בתוצאות של joinCustomAudience()

ה-method האסינכרוני joinCustomAudience() משתמש באובייקט OutcomeReceiver כדי לסמן את התוצאה של הקריאה ל-API.

• הקריאה החוזרת (callback) onResult() מציינת שהקהל בהתאמה אישית נוצר או עודכן בהצלחה.
• הקריאה החוזרת (callback) ‏onError() מציינת שני תנאים אפשריים.
  • אם JoinCustomAudienceRequest מאותחל עם ארגומנטים לא תקינים, AdServicesException מציין את IllegalArgumentException כסיבה.
  • כל שאר השגיאות מקבלות את הקוד AdServicesException עם IllegalStateException כסיבה.

דוגמה לטיפול בתוצאה של joinCustomAudience():

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

יציאה מקהל בהתאמה אישית

אם המשתמש כבר לא עומד בקריטריונים העסקיים של קהל מותאם אישית מסוים, אפליקציה או SDK יכולים להפעיל את הפונקציה leaveCustomAudience() כדי להסיר את הקהל המותאם אישית מהמכשיר. כדי להסיר CustomAudience על סמך הפרמטרים הייחודיים שלו:

1. מאתחלים את האובייקט CustomAudienceManager.
2. מאתחלים את LeaveCustomAudienceRequest עם buyer ו-name של הקהל בהתאמה אישית. מידע נוסף על השדות האלה להזנת קלט זמין במאמר בנושא הצטרפות לקהל בהתאמה אישית.
3. קוראים לשיטה האסינכרונית leaveCustomAudience() עם האובייקט LeaveCustomAudienceRequest והאובייקטים הרלוונטיים Executor ו-OutcomeReceiver.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

בדומה לקריאה ל-joinCustomAudience(), התג OutcomeReceiver מסמן את סוף הקריאה ל-API. כדי להגן על הפרטיות, תוצאת שגיאה לא מבחינה בין שגיאות פנימיות לבין ארגומנטים לא חוקיים. הפונקציה onResult() callback מופעלת כשקריאת ה-API מסתיימת, בין אם קהל מותאם שמתאים להסרה הוסר בהצלחה ובין אם לא.

הפעלת בחירת מודעות

כדי להשתמש ב-Protected Audience API לבחירת מודעות, מפעילים את שיטת selectAds():

1. מאתחלים אובייקט AdSelectionManager.
2. הרכבת אובייקט AdSelectionConfig.
3. קוראים לשיטה האסינכרונית selectAds() עם האובייקט AdSelectionConfig והאובייקטים הרלוונטיים Executor ו-OutcomeReceiver.

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

השיטה selectAds() דורשת קלט של AdSelectionConfig, שבו צריך לציין את הפרמטרים הנדרשים הבאים:

• המוכר: מזהה של רשת המודעות של המוכר שיזמה את בחירת המודעה.
• כתובת URL של לוגיקת ההחלטה: כתובת URL מסוג HTTPS שמתבצעת אליה שאילתה כדי לקבל את לוגיקת ה-JavaScript של רשת המודעות של המוכר.
  • כתובת URL מסוג HTTPS: מתבצעת שאילתה כדי לקבל את הלוגיקה של JavaScript ברשת המודעות של המוכר. חתימות הפונקציות הנדרשות
  • מזהה URI מוכן מראש: שמתאים לפורמט בחירת המודעות של FLEDGE. השגיאה IllegalArgumentException מופיעה אם מועבר URI מוכן מראש לא נתמך או לא תקין.
• קונים של קהלים בהתאמה אישית: רשימה מלאה של מזהים של רשתות מודעות של קונים שהמוכר מאפשר להם להשתתף בתהליך בחירת המודעות. המזהים האלה של הקונים תואמים לCustomAudience.getBuyer() של קהלים מותאמים אישית משתתפים.

אפשר לציין את הפרמטרים הבאים כדי להתאים אישית את בחירת המודעות:

• אותות לבחירת מודעות: אובייקט JSON שעבר סריאליזציה למחרוזת, ומכיל אותות שצריכים לשמש את לוגיקת הבידינג של הקונה ב-JavaScript, שנשלפה מ-CustomAudience.getBiddingLogicUrl().
• אותות של מוֹכרים: אובייקט JSON שעבר סריאליזציה למחרוזת, ומכיל אותות שנצרכים על ידי לוגיקת ההחלטות של JavaScript שאוחזרה על ידי המוכר מ-AdSelectionConfig.getDecisionLogicUrl().
• אותות לכל קונה: מיפוי של אובייקטים מסוג JSON שעברו סריאליזציה כמחרוזות, שמכילים אותות שצריכים לשמש את הלוגיקה של הצעות המחיר של קונים ספציפיים. קוד ה-JavaScript של הלוגיקה הזו מאוחזר מ-CustomAudience.getBiddingLogicUrl(), שמזוהה על ידי שדות הקונה של קהלים מותאמים אישית משתתפים.
• מודעות קונטקסטואליות: אוסף של מועמדים למודעות שנאספים ישירות מקונים במהלך מכרז שמתקיים מחוץ למכרז של קהלים מוגנים.

אחרי שבוחרים מודעה, התוצאות, הצעות המחיר והאותות נשמרים באופן פנימי לצורך דיווח. הקריאה החוזרת OutcomeReceiver.onResult() מחזירה AdSelectionOutcome שמכיל:

• כתובת URL להצגת המודעה הזוכה, שהתקבלה מ-AdData.getRenderUrl().
• מזהה לבחירת מודעות שייחודי למשתמש במכשיר. המזהה הזה משמש לדיווח על חשיפת המודעה.

אם בחירת המודעה לא יכולה להסתיים בהצלחה בגלל סיבות כמו ארגומנטים לא תקינים, פסק זמן או צריכת משאבים מוגזמת, OutcomeReceiver.onError()callback מספק AdServicesException עם ההתנהגויות הבאות:

• אם בחירת המודעה מתחילה עם ארגומנטים לא תקינים, AdServicesException מציין IllegalArgumentException כסיבה.
• כל שאר השגיאות מקבלות את הקוד AdServicesException עם IllegalStateException כסיבה.

מודעות לפי הקשר

עם Protected Audience API, אפשר לשלב מודעות קונטקסטואליות במכרז מוגן. צריך לבחור מודעות קונטקסטואליות בשרת של טכנולוגיית הפרסום ולהחזיר אותן למכשיר מחוץ ל-Protected Audience APIs. אחרי כן, אפשר לכלול מודעות קונטקסטואליות במכרז באמצעות AdSelectionConfig. בשלב הזה, המודעות האלה פועלות כמו מודעות במכשיר, כולל עמידה בדרישות לסינון מודעות שלילי. אחרי שמכרז Protected Audience מסתיים, צריך להפעיל את reportImpression(). הקריאה reportWin() מתבצעת במודעה ההקשרית הזוכה, באותו דפוס כמו דיווח על חשיפות, כדי לקבל את המודעה הזוכה במכשיר. לכל מודעה קונטקסטואלית צריך להיות קונה, הצעת מחיר, קישור ללוגיקת הדיווח, כתובת URL של רכיב ה-Render ומטא-נתונים של המודעה.

כדי להטמיע מודעות בהקשר באפליקציה, אפליקציית היעד צריכה ליצור אובייקט ContextualAds:

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

אפשר להעביר את אובייקט ContextualAds שנוצר כשיוצרים את AdSelectionConfig:

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

סינון מודעות להתקנת אפליקציות

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

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

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

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

השלב הבא הוא להגדיר סינון מודעות באפליקציה של בעל התוכן הדיגיטלי. הגורם שמציג את המודעה באפליקציה של בעל התוכן הדיגיטלי (בדרך כלל ערכת SDK בצד ההיצע) צריך לאתחל את אובייקט AdFilters עם מידע על המודעות שקשורות לאפליקציות שהוא רוצה לסנן:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

בעלי תוכן דיגיטלי בצד הביקוש יכולים גם להגדיר AdFilter למודעות שמוצגות בתוך הקהלים המותאמים שלהם.

אפשר להעביר את AdFilters גם בנקודת יצירת מופע של אובייקט AdData חדש:

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

סינון לפי מכסת תדירות

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

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

• זכייה: אירוע זכייה מציין שהמודעה זכתה במכרז. אירועי זכייה מתעדכנים אוטומטית על ידי Protected Audience API, והמפתח לא יכול לקרוא להם ישירות. נתוני הזכייה גלויים רק למודעות בתוך קהל מותאם אישית נתון.
• חשיפה: בנפרד מ-reportImpression, מתקשר במכשיר (SSP או MMP) משתמש ב-updateAdCounterHistogram() כדי להפעיל אירועי חשיפה בנקודה בקוד שהוא בוחר. אירועי חשיפה גלויים לכל המודעות ששייכות ל-DSP מסוים, והם לא מוגבלים למודעות באותו קהל מותאם אישית.
• תצוגה: האירוע מופעל על ידי המתקשר במכשיר (SSP או MMP) בנקודה בקוד שהוא בוחר באמצעות קריאה ל-updateAdCounterHistogram(). אירועי צפייה גלויים לכל המודעות ששייכות ל-DSP מסוים, ולא רק למודעות באותו קהל מותאם אישית.
• קליק: האירוע מופעל על ידי המתקשר במכשיר (SSP או MMP) בנקודה בקוד שהוא בוחר באמצעות קריאה ל-updateAdCounterHistogram(). אירועי קליקים גלויים לכל המודעות ששייכות ל-DSP מסוים, ולא רק למודעות שנכללות באותו קהל מותאם אישית.

באפליקציית בעל האתר, פלטפורמת SSP או MMP שקיימת במכשיר מפעילה אירועים של מודעות. כשמפעילים את updateAdCounterHistogram(), המונה של מסנן מכסת התדירות גדל, כך שבמכרזים עתידיים יהיה מידע עדכני על החשיפה של משתמש למודעה נתונה. סוגי אירועי המודעות לא קשורים באופן מחייב לפעולת המשתמש המתאימה, והם משמשים כהנחיות כדי לעזור למתקשרים לבנות את מערכת האירועים שלהם. כדי להגדיל את מוני המודעות בזמן אירוע, הגורם הפעיל במכשיר מספק את מזהה בחירת המודעה של המודעה שזכתה במכירה הפומבית.

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

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

כדי להשתמש במכסת תדירות במכרז, צריך קודם ליצור אובייקטים של KeyedFrequencyCap:

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

אחרי שיוצרים את האובייקטים KeyedFrequencyCap, אפשר להעביר אותם לאובייקט AdFilters.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

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

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

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

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

מודעות שהגיעו למכסת התדירות שהוגדרה להן מסוננות מהמכרז. הסינון מתבצע לפני ההפעלה של לוגיקת הבידינג במכרזים במכשיר, ובזמן יצירת מטען הייעודי (payload) במכרזים של שירותי הבידינג והמכרז.ערכת הכלים הזו מאפשרת לטכנולוגיות פרסום להשתמש באינטראקציות בין המשתמשים לבין המודעות בקהלים המותאמים אישית שלהן כדי להתמקד בטירגוט מודעות, תוך צמצום החשיפה המוגזמת למודעות.

סינון מודעות לפי הקשר בלי קריאות לרשת

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

כדי לשפר את זמן האחזור, טכנולוגיות פרסום יכולות להריץ תהליך בחירת מודעות שכולל רק מודעות קונטקסטואליות עם פונקציונליות של סינון מודעות, בלי לבצע קריאות לרשת. ההגדרה הזו מתבצעת באמצעות שימוש ב-URI מוכן מראש לאותות ניקוד. בקטע Supported prebuilt URI use cases and names (תרחישי שימוש ושמות של URI מובנים מראש שנתמכים) מפורטת רשימה של scoreAds הטמעות.

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

1. הגדרה של סינון מודעות
2. יצירת מודעות קונטקסטואליות

3. יוצרים אובייקט AdSelectionConfig עם הפרטים הבאים:

   1. רשימה ריקה של קונים
   2. מזהה URI מוכן מראש לבחירת הצעת המחיר הגבוהה ביותר
   3. מודעות לפי הקשר
   4. URI ריק לאותות הניקוד. מותר להשתמש ב-URI ריק כדי לציין שלא רוצים להשתמש באחזור של אותות מהימנים לצורך ניקוד:

   Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
   // Initialize AdSelectionConfig
   AdSelectionConfig adSelectionConfig =
     new AdSelectionConfig.Builder()
       .setSeller(seller)
       .setDecisionLogicUri(prebuiltURIScoringUri)
       .setCustomAudienceBuyers(Collections.emptyList())
       .setAdSelectionSignals(adSelectionSignals)
       .setSellerSignals(sellerSignals)
       .setPerBuyerSignals(perBuyerSignals)
       .setBuyerContextualAds(buyerContextualAds)
       .setTrustedScoringSignalsUri(Uri.EMPTY)
       .build();
   

4. הפעלת בחירת המודעה:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

הפעלת JavaScript משלכם לדיווח כשמשתמשים ב-URI מוכנים מראש

נכון לעכשיו, בפלטפורמת ארגז החול לפרטיות יש רק הטמעה בסיסית של JavaScript לדיווח, שזמינה לכתובות URI מוכנות מראש. אם רוצים להפעיל JavaScript משלכם לדיווח, ועדיין להשתמש בכתובות URI מוכנות מראש לבחירת מודעות עם זמן אחזור נמוך, אפשר לבטל את DecisionLogicUri בין בחירת המודעות לבין הפעלת הדיווח.

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

2. לפני שמריצים דוחות, צריך ליצור עותק של AdSelectionConfig

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. הפעלת דיווח על חשיפות

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

הפעלת רשימת רשתות בתהליך בחירת רשת

תהליך בחירת הרשת מסוג Waterfall מחייב שימוש בכמה ערכות SDK של צד שלישי (רשתות צד שלישי) שמופעלות על ידי רשת בחירת רשת שמבוססת על SDK של צד ראשון. תהליך הגישור בשיטת Waterfall מתבצע באותו אופן, בין אם המכרז התקיים במכשיר או באמצעות שירותי בידינג ומכרזים (B&A).

רשתות 3P

רשתות צד שלישי צריכות לספק מתאם שמאפשר לרשת הגישור להפעיל את השיטות הדרושות להרצת מכרז:

• הפעלת בחירת מודעות
• חשיפות בדוח

דוגמה למתאם של רשת גישור:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

לכל SDK יש מנהלים ולקוחות משלו של שירות בחירת המודעות, ויישום משלו של selectAds ושל reportImpressions. ספקי SDK יכולים לעיין בקטעים בנושא הפעלת בחירת מודעות למכרזים במכשיר או בהסבר על B&A למכרזי B&A. פועלים לפי ההוראות לדיווח על חשיפות של מודעות (בהתאם לדיווח על חשיפות של SSP יחיד).

רשת בתהליך בחירת הרשת

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

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

אחזור של שרשרת לבחירת רשת ומחירי מינימום להצעת מחיר

רשת התיווך אחראית לאחזור מודעות קונטקסטואליות מצד ראשון (1P), שרשרת התיווך ורצפות המחיר של רשתות צד שלישי (3P). זה יכול לקרות בבקשה לאחזור מודעות בהתאם להקשר, שמופעלת על ידי רשת התיווך. שרשרת תהליך בחירת הרשת קובעת איך לבצע איטרציה ברשתות של צד שלישי, ואפשר להעביר את מחירי המינימום להצעת מחיר לתהליך המכרז כ-adSelectionSignals.

מיקום הרשת בשרשרת לבחירת רשת

ערכת SDK של תהליך בחירת הרשת יכולה למקם את עצמה בשרשרת של תהליך בחירת הרשת על סמך העלות בפועל לאלף חשיפות בזמן אמת של הצעות מחיר למודעות של צד ראשון. ב-Protected Audience API, הצעות המחיר למודעות הן אטומות. ערכת SDK לבחירת רשת (Mediation) צריכה להשתמש ב-AdSelectionFromOutcomesConfig כדי להשוות בין הצעת המחיר של מודעה מסוימת של צד ראשון לבין מחיר המינימום לבידינג של הרשת הבאה של צד שלישי בשרשרת. אם הצעת המחיר של הצד הראשון גבוהה ממחיר המינימום, המשמעות היא שערכת ה-SDK של תהליך בחירת הרשת ממוקמת לפני הרשת של הצד השלישי.

הפעלת בחירת מודעות

כדי לאחזר מועמד למודעה מצד ראשון, הרשת לבחירת רשת יכולה להריץ מכרז במכשיר לפי השלבים שמפורטים בקטע הפעלת בחירת מודעות. הפעולה הזו יוצרת מועמד למודעה מצד ראשון, הצעת מחיר וערך AdSelectionId שמשמש בתהליך בחירת הרשת.

יצירת AdSelectionFromOutcomesConfig

AdSelectionFromOutcomesConfig מאפשרת לרשת המתווכת להעביר רשימה של AdSelectionIds (תוצאות ממכרזים קודמים), אותות לבחירת מודעות ו-URI לאחזור JavaScript שבוחר מודעה מתוך כמה מועמדות. הרשימה של מזהי AdSelectionId יחד עם הצעות המחיר והאותות שלהם מועברת אל קוד ה-JavaScript, שיכול להחזיר את אחד מתוך AdSelectionIds אם הוא עומד בדרישות של הצעת המחיר המינימלית, או לא להחזיר כלום אם שרשרת הגישור צריכה להימשך.

רשתות לבחירת רשת יוצרות AdSelectionFromOutcomesConfig באמצעות ה-1P AdSelectionId מהקטע הקודם, ורף המחיר המינימלי להצעת מחיר עבור רשת צד שלישי שנבדקת. צריך ליצור AdSelectionFromOutcomesConfig חדש לכל שלב בשרשרת בחירת הרשת.

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

השיטה selectAds() לביטול ברירת המחדל של שיטת המכרז במפלסות דורשת קלט AdSelectionFromOutcomesConfig, שבו צריך לציין את הפרמטרים הנדרשים הבאים:

• המוכר: מזהה של רשת המודעות של המוכר שיזמה את בחירת המודעה.
• ‫AdSelectionIds: רשימה יחידה של הפעלה קודמת של selectAds() עבור מודעה של צד ראשון.
• אותות לבחירת מודעות: אובייקט JSON שעבר סריאליזציה למחרוזת, ומכיל אותות לשימוש בלוגיקת הבידינג של הקונה. במקרה כזה, צריך לכלול את מחיר המינימום להצעה שנשלף עבור רשת הצד השלישי הנתונה.
• URI של לוגיקת הבחירה: כתובת URL של HTTPS שמתבצעת לגביה שאילתה במהלך בחירת המודעה כדי לאחזר את קוד ה-JavaScript של רשת הגישור לבחירת המודעה המניבה ביותר. אפשר לראות את חתימות הפונקציות הנדרשות ב-JavaScript הזה. קוד ה-JavaScript צריך להחזיר את המודעה של הצד השלישי אם הצעת המחיר גבוהה מהסף המינימלי להצעת המחיר, אחרת הוא צריך להחזיר null. ההגדרה הזו מאפשרת ל-SDK של תהליך בחירת הרשת לקטוע את השרשרת של תהליך בחירת הרשת כשנמצאת רשת מנצחת.

אחרי שיוצרים את AdSelectionOutcomesConfig, קוראים למתודה selectAds() של רשת הצד השלישי הראשונה בשרשרת.

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

תזמור של רשימת רשתות בתהליך בחירת רשת

זהו סדר הפעולות בתהליך בחירת הרשת.

1. הפעלת בחירת מודעות מנתונים ממקור ראשון.
2. חזרה על התהליך בשרשרת לבחירת רשת. לכל רשת צד שלישי, מבצעים את הפעולות הבאות:
   1. בונים את AdSelectionFromOutcomeConfig כולל outcomeId מאינטראקציה ישירה וערך הסף התחתון לבידינג של SDK חיצוני.
   2. קוראים ל-selectAds() עם ההגדרה מהשלב הקודם.
   3. אם התוצאה לא ריקה, מחזירים את המודעה.
   4. מפעילים את השיטה selectAds() של מתאם הרשת הנוכחי של ה-SDK. אם התוצאה לא ריקה, מחזירים את המודעה.
3. אם לא נמצא מנצח בשרשרת, המערכת מחזירה את המודעה של הצד הראשון.

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

דיווח על חשיפות של מודעות

יש שני תהליכים לדיווח על חשיפה של מודעה, בהתאם לאופן שבו מתנהל המכרז. אם אתם פלטפורמת SSP יחידה שמפעילה מכרז, אתם צריכים לפעול לפי ההוראות שבקטע הזה. אם אתם מתכוונים להטמיע תהליך בחירת רשת (Mediation) מסוג מפל מים, אתם צריכים לפעול לפי השלבים שמפורטים בקטע בנושא דיווח על חשיפות בתהליך בחירת רשת (Mediation) מסוג מפל מים.

דיווח על חשיפות בפלטפורמת SSP יחידה

אחרי שנבחרה מודעה מנצחת מתוך תהליך העבודה של בחירת המודעה, אפשר לדווח על החשיפה בחזרה לפלטפורמות משתתפות בצד הקונה ובצד המוכר באמצעות השיטה AdSelectionManager.reportImpression(). כדי לדווח על צפייה במודעה:

1. מאתחלים אובייקט AdSelectionManager.
2. יוצרים אובייקט ReportImpressionRequest עם מזהה בחירת המודעה.
3. קוראים לשיטה האסינכרונית reportImpression() עם האובייקט ReportImpressionRequest והאובייקטים הרלוונטיים Executor ו-OutcomeReceiver.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

מאתחלים את ReportImpressionRequest עם הפרמטרים הנדרשים הבאים:

• מזהה בחירת מודעה: מזהה ייחודי למשתמש במכשיר שמציין בחירת מודעה מוצלחת.
• ‫Ad selection config: אותה הגדרה שנעשה בה שימוש בקריאה selectAds() שמזוהה על ידי מזהה בחירת המודעות שסופק.

ה-method האסינכרוני reportImpression() משתמש באובייקט OutcomeReceiver כדי לסמן את התוצאה של הקריאה ל-API.

• הקריאה החוזרת onResult() מציינת אם נוצרו כתובות URL לדיווח על חשיפות והאם הבקשה נכללה בתזמון.
• הקריאה החוזרת onError() מציינת את התנאים האפשריים הבאים:
  • אם השיחה מאותחלת עם ארגומנט קלט לא תקין, AdServicesException מציין IllegalArgumentException כסיבה.
  • כל שאר השגיאות מקבלות את הקוד AdServicesException עם IllegalStateException כסיבה.

דיווח על חשיפות ב-Waterfall של תהליך בחירת הרשת (Mediation)

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

פלטפורמות SSP יכולות להשתמש בדוגמה הזו של קוד SDK של צד שלישי כפרוטוטייפ כדי להבין איך להצטרף לתהליכי בחירת רשתות (mediation):

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

נקודות קצה לדיווח על חשיפות

ה-API של דוחות החשיפות שולח בקשות HTTPS GET לנקודות קצה שסופקו על ידי הפלטפורמה בצד המוכר והפלטפורמה המנצחת בצד הקונה:

נקודת הקצה של הפלטפורמה בצד הקונה:

• ה-API משתמש בכתובת ה-URL של לוגיקת הבידינג שצוינה בקהל המותאם אישית כדי לאחזר את קוד ה-JavaScript שסופק על ידי הקונה, שכולל לוגיקה להחזרת כתובת URL לדיווח על חשיפה.
• מפעילים את פונקציית JavaScript‏ reportWin(), שאמורה להחזיר את כתובת ה-URL של הקונה לדיווח על חשיפות.

נקודת הקצה (endpoint) של הפלטפורמה בצד המוכר:

• משתמשים בכתובת ה-URL של לוגיקת ההחלטה שצוינה באובייקט AdSelectionConfig כדי לאחזר את ה-JavaScript של לוגיקת ההחלטה של המוכר.
• מפעילים את פונקציית ה-JavaScript‏ reportResult(), שאמורה להחזיר את כתובת ה-URL של הדוח על החשיפות של המוכר.

דיווח על שירותי בידינג ומכרזים

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

דיווח על חשיפות בהקדם האפשרי

השיטה reportImpression() נועדה להשלים את הדיווח על בסיס המאמץ הטוב ביותר.

דיווח על אינטראקציות עם מודעות

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

הרשמה לקבלת אירועי אינטראקציה

ההרשמה לאירועי אינטראקציה מתבצעת בפונקציות JavaScript של הקונה reportWin() ושל המוכר reportResult() באמצעות פונקציית JavaScript שסופקה על ידי הפלטפורמה: registerAdBeacon. כדי להירשם לקבלת דוח אירועים, צריך להפעיל את פונקציית JavaScript של הפלטפורמה מתוך JavaScript של הדיווח. בקטע הקוד הבא נעשה שימוש ב-reportWin() של הקונה, אבל אותה גישה חלה על reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

דיווח על אירועי אינטראקציה

אחרי דיווח על חשיפה, לקוחות יכולים לדווח על האינטראקציות בחזרה לפלטפורמות קנייה ומכירה שזכו במכרז ושנרשמו קודם לכן, באמצעות השיטה AdSelectionManager.reportInteraction(). כדי לדווח על אירוע שקשור למודעה:

1. מאתחלים אובייקט AdSelectionManager.
2. יוצרים אובייקט ReportInteractionRequest עם מזהה בחירת המודעה, מפתח האינטראקציה, נתוני האינטראקציה ויעד הדיווח.
3. מבצעים קריאה לשיטה האסינכרונית reportInteraction() עם האובייקט request והאובייקטים הרלוונטיים Executor ו-OutcomeReceiver.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

מאתחלים את ReportInteractionRequest עם הפרמטרים הנדרשים הבאים:

• מזהה בחירת מודעה: מזהה בחירת מודעה שאוחזר מ-AdSelectionOutcome שהוחזר קודם.
• מפתח האינטראקציה: מפתח מחרוזת שהוגדר על ידי הלקוח ומתאר את הפעולה שמדווחת. הערך הזה צריך להיות זהה למפתח שנרשם על ידי המוכר או הקונה בפונקציות ה-JavaScript של הדיווח.
• נתוני אינטראקציה: מחרוזת שמכילה נתונים שייכללו בדוח האירועים, שיישלח חזרה לשרתי הדיווח באמצעות POST.
• יעדי הדיווח: מסכת ביטים שמציינת אם האירועים צריכים להיות מדווחים לקונה, למוכר או לשניהם. הפלטפורמה מספקת את הדגלים האלה, ואפשר ליצור את מסכת היעד הסופית באמצעות פעולות ברמת הביט. כדי לדווח ליעד אחד, אפשר להשתמש ישירות בדגל שמספקת הפלטפורמה. כדי לדווח לכמה יעדים, אפשר להשתמש בפעולה bitwise OR ‏ (|) כדי לשלב ערכי דגלים.

ה-method האסינכרוני reportInteraction() משתמש באובייקט OutcomeReceiver כדי לסמן את התוצאה של הקריאה ל-API.

• הקריאה החוזרת onResult() מציינת שהקריאה של אינטראקציית הדוח חוקית.
• הקריאה החוזרת onError() מציינת את התנאים האפשריים הבאים:
  • אם השיחה מתבצעת כשהאפליקציה פועלת ברקע, מוחזר IllegalStateException עם תיאור של הכשל.
  • אם הלקוח מוגבל בשיחות אל reportInteraction(), מוחזרת LimitExceededException.
  • אם החבילה לא רשומה לקריאה לממשקי ה-API לשמירה על הפרטיות, מוחזר SecurityException().
  • אם האפליקציה שמדווחת על האינטראקציות שונה מהאפליקציה שקראה ל-selectAds(), מוחזר IllegalStateException.
• אם המשתמש לא הביע הסכמה להפעלת ממשקי Privacy Sandbox API, הקריאה תיכשל בלי להציג הודעה.

נקודות קצה לדיווח על אינטראקציות

ה-API של אינטראקציות עם דוחות שולח בקשות HTTPS POST לנקודות קצה שסופקו על ידי פלטפורמת המוכר ופלטפורמת הקונה המנצחת. Protected Audience ישווה את מפתחות האינטראקציה לכתובות ה-URI שהוצהרו ב-JavaScript של הדיווח, וינפיק בקשת POST לכל נקודת קצה עבור כל אינטראקציה שמדווחת. ה-Content-Type של הבקשה הוא טקסט פשוט, והגוף הוא נתוני האינטראקציה.

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

ה-reportInteraction() מיועד להשלמת הדיווח כמיטב היכולת באמצעות HTTP POST.

עדכון יומי ברקע

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

• אותות בידינג של משתמשים
• נתוני בידינג מהימנים
• רשימה אחת (AdData)

במהלך התהליך הזה מתבצעת שאילתה לגבי כתובת ה-URL של העדכון היומי שהוגדרה בקהל המותאם אישית, וכתובת ה-URL עשויה להחזיר תגובת JSON.

• תגובת ה-JSON עשויה להכיל כל אחד משדות המטא-נתונים הנתמכים שצריך לעדכן.
• כל שדה JSON מאומת בנפרד. הלקוח מתעלם משדות שכתובים בתבנית שגויה, ולכן לא מתבצעים עדכונים בשדה הספציפי הזה בתשובה.
• תגובת HTTP ריקה או אובייקט JSON ריק '{}' לא יגרמו לעדכוני מטא-נתונים.
• גודל הודעת התגובה צריך להיות מוגבל ל-10KB.
• חובה להשתמש ב-HTTPS בכל מזהי ה-URI.
• הדומיין trusted_bidding_uri חייב להיות באותו ETLD+1 כמו הדומיין של הקונה.

דוגמה: תגובת JSON לעדכון יומי ברקע

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

‫JavaScript לבחירת מודעות

תהליך העבודה של בחירת המודעות מתזמן את ההרצה של JavaScript שסופק על ידי הקונה ו-JavaScript שסופק על ידי המוכר.

קוד JavaScript שסופק על ידי הקונה מאוחזר מכתובת ה-URL של לוגיקת הבידינג שצוינה בקהל המותאם אישית. קוד ה-JavaScript שמוחזר צריך לכלול את הפונקציות הבאות:

• generateBid()
• reportWin()

קוד JavaScript שסופק על ידי המוכר מאוחזר מכתובת ה-URL של לוגיקת ההחלטה שצוינה בפרמטר AdSelectionConfig של Ad Selection API. קוד ה-JavaScript שמוחזר צריך לכלול את הפונקציות הבאות:

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

פרמטרים של קלט:

• ‫ad: אובייקט JSON בפורמט var ad = { 'render_url': url, 'metadata': json_metadata };
• ‫auction_signals, per_buyer_signals: אובייקטים מסוג JSON שצוינו באובייקט ההגדרה של המכרז

• ‫custom_audience_bidding_signals: אובייקט JSON שנוצר על ידי הפלטפורמה. הפורמט של אובייקט ה-JSON הזה הוא:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  where:‎

  • ‫owner, ‏buyer ו-name הם מחרוזות שנלקחות מהמאפיינים עם אותו שם של הקהל בהתאמה אישית שמשתתף בבחירת המודעה
  • ‫activation_time ו-expiration_time הם זמן ההפעלה ותפוגת התוקף של קהל מותאם אישית, בשניות מאז ראשית זמן יוניקס (Unix epoch)
  • ‫ca_user_bidding_signals היא מחרוזת JSON שמוגדרת בשדה userBiddingSignals של CustomAudience בזמן היצירה
  • ‫trusted_bidding_signals, contextual_signals ו-user_signals הם אובייקטים ב-JSON. הם מועברים כאובייקטים ריקים וימולאו במהדורות עתידיות. הפלטפורמה לא אוכפת את הפורמט שלהם, והם מנוהלים על ידי טכנולוגיית הפרסום.

תוצאה:

• ‫ad: המודעה שאליה מתייחסת הצעת המחיר. לסקריפט מותר להחזיר עותק של המודעה שהוא קיבל עם מטא-נתונים שונים. המאפיין render_url של המודעה לא אמור להשתנות.
• ‫bid: ערך מסוג float שמייצג את ערך הצעת המחיר למודעה הזו
• ‫status: ערך מספרי שלם שיכול להיות:
  • ‫0: להרצה מוצלחת
  • ‫1: (או כל ערך שאינו אפס) אם אחד מאותות הקלט לא תקין. אם הפונקציה generate-bid מחזירה ערך שאינו אפס, תהליך הבידינג נפסל לכל המודעות של קמפיין האפליקציות

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

פרמטרים של קלט:

• ad: generateBidלעיון במסמכי התיעוד
• ‫bid: ערך הצעת המחיר למודעה

• ‫ad_selection_config: אובייקט JSON שמייצג את הפרמטר AdSelectionConfig של selectAds API. הפורמט הוא:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• ‫seller_signals: אובייקטים בפורמט JSON שנקראו מפרמטר ה-API‏ sellerSignals AdSelectionConfig

• ‫trusted_scoring_signal: קריאה מהשדה adSelectionSignals בפרמטר ה-API‏ AdSelectionConfig

• ‫contextual_signals, user_signals: אובייקטים מסוג JSON. הם מועברים כאובייקטים ריקים וימולאו בגרסאות עתידיות. הפלטפורמה לא אוכפת את הפורמט שלה, והוא מנוהל על ידי טכנולוגיית הפרסום.

• ‫per_buyer_signals: אובייקט JSON שנקרא מהמיפוי perBuyerSignal בפרמטר של AdSelectionConfig API, באמצעות מפתח שהוא הקונה הנוכחי של קהל מותאם אישית. השדה ריק אם המיפוי לא מכיל רשומה עבור הקונה הנתון.

פלט:

• ‫score: ערך מסוג float שמייצג את ערך הציון של המודעה הזו
• ‫status: ערך מספרי שלם שיכול להיות:
  • ‫0: אם ההרצה הסתיימה בהצלחה
  • ‫1: אם הערכים של customAudienceSignals לא תקינים
  • ‫2: אם הערך של AdSelectionConfig לא תקין
  • ‫3: אם אחד מהאותות האחרים לא תקף
  • כל ערך שאינו אפס גורם לכשל בתהליך, והערך קובע את סוג החריגה שנוצרת

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

פרמטרים של קלט:

• ‫outcomes: אובייקט JSON {"id": id_string, "bid": bid_double}
• ‫selection_signals: אובייקטים מסוג JSON שצוינו באובייקט של הגדרת המכרז

פלט:

• ‫status: 0 אם הפעולה הצליחה, הערך הוא 0. אם הפעולה נכשלה, הערך הוא מספר שאינו 0.
• ‫result: אחת מהתוצאות שהועברו או null

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

פרמטרים של קלט:

• ‫ad_selection_config: אפשר לעיין במסמכי התיעוד של scoreAds
• ‫render_url: כתובת ה-URL של המודעה המנצחת
• ‫bid: הצעת המחיר שהוגשה עבור המודעה הזוכה
• ‫contextual_signals: אפשר לעיין במסמכי התיעוד של generateBid

פלט:

• ‫status: 0 אם הפעולה הצליחה, ואם היא נכשלה
• ‫results: אובייקט JSON שמכיל:
  • ‫signals_for_buyer: אובייקט JSON שמועבר לפונקציה reportWin
  • ‫reporting_url: כתובת URL שמשמשת את הפלטפורמה כדי להודיע לקונה על החשיפה

reportWin()‎

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

פרמטרים של קלט:

• ‫ad_selection_signals, per_buyer_signals: אפשר לעיין בתיעוד של scoreAd
• ‫signals_for_buyer: אובייקט JSON שמוחזר על ידי reportResult
• ‫contextual_signals, custom_audience_signals: אפשר לעיין בתיעוד של generateBid

פלט:

• ‫status: 0 אם הפעולה הצליחה, ואם היא נכשלה
• ‫results: אובייקט JSON שמכיל:
  • ‫reporting_url: כתובת URL שמשמשת את הפלטפורמה כדי להודיע למוכר על החשיפה

registerAdBeacon()

function registerAdBeacon(
  beacons
)

פרמטרים של קלט:

• ‫beacons: אובייקט שמכיל צמדי מפתח/ערך של מפתחות אינטראקציה וכתובות URI של דיווח. הפורמט הוא:

  let beacons = {
    'interaction_key': 'reporting_uri',
    'interaction_key': 'reporting_uri',
    ...
  }
  

  • ‫interaction_key: מחרוזת שמייצגת את האירוע. הפלטפורמה משתמשת בערך הזה בהמשך, כשמדווחים על אינטראקציות עם אירועים, כדי לחפש את reporting_uri שצריך לשלוח לו התראה. המפתח הזה צריך להיות זהה למה שהקונה או המוכר רושמים ולמה שהמוכר מדווח.
  • ‫reporting_uri: URI לקבלת דוחות אירועים. התיאור צריך להיות ספציפי לסוג האירוע שמדווח. הוא צריך לקבל בקשת POST כדי לטפל בכל הנתונים שמדווחים יחד עם האירוע.

  לדוגמה:

    let beacons = {
      'click': 'https://reporting.example.com/click_event',
      'view': 'https://reporting.example.com/view_event'
    }
  

מזהי URI מוכנים מראש של בחירת מודעות

כתובות URI מוכנות מראש מאפשרות לטכנולוגיות פרסום להקצות פונקציות JavaScript ללוגיקה של החלטות לבחירת מודעות במחלקות AdSelectionConfig ו-AdSelectionFromOutcomesConfig. מזהי URI מוכנים מראש לא דורשים קריאות לרשת כדי להוריד את ה-JavaScript המתאים. טכנולוגיות פרסום יכולות להשתמש במזהי URI מוכנים מראש בלי להגדיר דומיין רשום לאירוח של JavaScript.

פורמט ה-URI המובנה מראש הוא:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

פלטפורמת ארגז החול לפרטיות מספקת JavaScript באמצעות המידע מ-URI זה בזמן הריצה.

שגיאת IllegalArgumentException מופיעה אם:

• אחד מהפרמטרים הנדרשים לא מופיע ב-URI
• יש פרמטרים לא מזוהים ב-URI

תרחישים נתמכים לדוגמה ושמות של URI מוכנים מראש

תרחיש לדוגמה 1: בחירת מודעות

כתובות URI מוכנות מראש בתרחיש השימוש ad-selection נתמכות בתהליך selectAds(AdSelectionConfig).

שם ה-URI המובנה מראש: highest-bid-wins

ה-URI הזה שנוצר מראש מספק JavaScript שבוחר את המודעה עם הצעת המחיר הגבוהה ביותר אחרי הבידינג. הוא גם מספק פונקציית דיווח בסיסית לדיווח על render_uri וbid של המודעה המנצחת.

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

‫reportingUrl: כתובת ה-URL הבסיסית של הדיווח שמוגדרים בה הפרמטרים render_uri ו-bid של המודעה הזוכה:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

שימוש

אם כתובת ה-URL הבסיסית של הדוחות היא https://www.ssp.com/reporting, אז ה-URI המובנה מראש יהיה:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

תרחיש שימוש 2: בחירת מודעות על סמך תוצאות

כתובות URI מוכנות מראש במסגרת תרחיש השימוש ad-selection-from-outcomes תומכות בתהליך העבודה selectAds(AdSelectionFromOutcomesConfig).

שם ה-URI המובנה מראש: waterfall-mediation-truncation

ה-URI המובנה מראש waterfall-mediation-truncation מספק JavaScript שמטמיע לוגיקה של קיטוע תהליך בחירת הרשת בשיטת Waterfall, שבה ה-JavaScript מחזיר מודעה מצד ראשון אם bid גבוה מ-bid floor או שווה לו, ואחרת מחזיר null.

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

‫bidFloor: המפתח של ערך הסף התחתון לבידינג שמועבר ב-getSelectionSignals() שמושוואה למודעה של ה-SDK לניהול תהליך בחירת הרשת.

שימוש

אם האותות לבחירת המודעה נראים כך: {"bid_floor": 10}, אז ה-URI המובנה מראש שיתקבל יהיה:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

בדיקה

כדי לעזור לכם להתחיל להשתמש ב-Protected Audience API, יצרנו אפליקציות לדוגמה ב-Kotlin וב-Java, שאפשר למצוא ב-GitHub.

דרישות מוקדמות

כדי להשתמש ב-Protected Audience API, צריך להשתמש ב-JavaScript במהלך בחירת המודעות ובדיווח על חשיפות. יש שתי שיטות להוספת קוד ה-JavaScript הזה בסביבת בדיקה:

• מריצים שרת עם נקודות הקצה הנדרשות מסוג HTTPS שמחזיר את ה-JavaScript
• שינוי ברירת המחדל של אחזור מרחוק על ידי הוספת הקוד הנדרש ממקור מקומי

בשתי הגישות צריך להגדיר נקודת קצה מסוג HTTPS כדי לטפל בדיווח על חשיפות.

נקודות קצה של HTTPS

כדי לבדוק את בחירת המודעות ואת דיווח החשיפות, צריך להגדיר 7 נקודות קצה של HTTPS שאפשר לגשת אליהן ממכשיר הבדיקה או מהאמולטור:

1. נקודת קצה של הקונה שמציגה את קוד ה-JavaScript של לוגיקת הבידינג.
2. נקודת קצה שמציגה את אותות הבידינג.
3. נקודת קצה של המוכר שמשרתת את ה-JavaScript של לוגיקת ההחלטה.
4. נקודת קצה שמספקת אותות ניקוד.
5. נקודת הקצה (endpoint) של דוחות החשיפות של הקונה המנצח.
6. נקודת הקצה (endpoint) של הדיווח על חשיפות של בית העסק.
7. נקודת קצה (endpoint) להצגת העדכונים היומיים של קהל מותאם אישית.

לנוחיותכם, במאגר GitHub יש קוד JavaScript בסיסי למטרות בדיקה. הוא כולל גם הגדרות שירות של OpenAPI שאפשר לפרוס בפלטפורמת מיקרו-שירותים או בפלטפורמת מוקאפ נתמכת. פרטים נוספים זמינים בREADME של הפרויקט.

ביטול אחזור מרחוק של JavaScript

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

כדי להפעיל מצב ניפוי באגים באפליקציה, מוסיפים את השורה הבאה למאפיין application בקובץ AndroidManifest.xml:

<application
  android:debuggable="true">

דוגמה לאופן השימוש בהגדרות ברירת המחדל האלה מופיעה באפליקציה לדוגמה של Protected Audience API ב-GitHub.

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

אפשר לבטל את אחזור ה-JavaScript בצד המוכר ובצד הקונה בנפרד, אבל צריך נקודת קצה (endpoint) של HTTPS כדי להציג JavaScript שלא מסופק לביטול. בREADME מוסבר איך להגדיר שרת שמטפל במקרים האלה.

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

ביטול של JavaScript בצד המוכר

כדי להגדיר החלפה של JavaScript בצד המוכר, מבצעים את הפעולות הבאות כמו בדוגמת הקוד הבאה:

1. מאתחלים אובייקט AdSelectionManager.
2. אחזור הפניה אל TestAdSelectionManager מהאובייקט AdSelectionManager.
3. הרכבת אובייקט AdSelectionConfig.
4. יוצרים AddAdSelectionOverrideRequest באמצעות האובייקט AdSelectionConfig ו-String שמייצג את ה-JavaScript שרוצים להשתמש בו כהחלפה.
5. קוראים לשיטה האסינכרונית overrideAdSelectionConfigRemoteInfo() עם האובייקט AddAdSelectionOverrideRequest והאובייקטים הרלוונטיים Executor ו-OutcomeReceiver.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

מידע נוסף על המשמעות של כל אחד מהשדות ב-AdSelectionConfig זמין בקטע הפעלת בחירת מודעות. ההבדל העיקרי הוא שאפשר להגדיר את decisionLogicUrl כערך placeholder כי הוא יתעלם ממנו.

כדי לשנות את הגדרות ה-JavaScript שמשמשות לבחירת מודעות, התג decisionLogicJs צריך להכיל את חתימות הפונקציות המתאימות בצד המוכר. דוגמה לקריאת קובץ JavaScript כמחרוזת מופיעה באפליקציה לדוגמה של Protected Audience API ב-GitHub.

ה-method האסינכרוני overrideAdSelectionConfigRemoteInfo() משתמש באובייקט OutcomeReceiver כדי לסמן את התוצאה של הקריאה ל-API.

הקריאה החוזרת onResult() מציינת שההחלפה בוצעה בהצלחה. בשיחות עתידיות עם selectAds(), המערכת תשתמש בכל לוגיקת ההחלטות והדיווח שהעברתם כהחלפה.

הקריאה החוזרת onError() מסמלת שני תנאים אפשריים:

• אם מנסים לבצע את ההחלפה עם ארגומנטים לא תקינים, AdServiceException מציין את IllegalArgumentException כסיבה.
• אם מנסים לבצע את ההחלפה באפליקציה שלא פועלת במצב ניפוי באגים עם אפשרויות למפתחים מופעלות, AdServiceException מציין את IllegalStateException כסיבה.

איפוס שינויים שבוצעו בצד המוכר

בקטע הזה מניחים שביטלתם את ברירת המחדל של JavaScript בצד המוכר, ושיש לכם הפניה ל-TestAdSelectionManager ול-AdSelectionConfig שבהם נעשה שימוש בקטע הקודם.

כדי לאפס את ההגדרות ששונו לכל AdSelectionConfigs:

1. מבצעים קריאה ל-method האסינכרונית resetAllAdSelectionConfigRemoteOverrides() עם אובייקט OutcomeReceiver הרלוונטי.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

אחרי איפוס ההגדרות לביטול בצד המוכר, קריאות אל selectAds() משתמשות בערך של decisionLogicUrl שמאוחסן ב-AdSelectionConfig כדי לנסות לאחזר את ה-JavaScript הנדרש.

אם הקריאה ל-resetAllAdSelectionConfigRemoteOverrides() נכשלת, הקריאה החוזרת OutComeReceiver.onError() מספקת AdServiceException. אם מנסים להסיר חריגים באפליקציה שלא פועלת במצב ניפוי באגים עם אפשרויות למפתחים מופעלות, AdServiceException מציין את IllegalStateException כסיבה.

ביטול של JavaScript בצד הקונה

1. פועלים לפי השלבים כדי להצטרף לקהל בהתאמה אישית.
2. יוצרים AddCustomAudienceOverrideRequest עם הקונה והשם של הקהל בהתאמה אישית שרוצים לבטל, בנוסף ללוגיקת הבידינג ולנתונים שרוצים להשתמש בהם כביטול.
3. קוראים לשיטה האסינכרונית overrideCustomAudienceRemoteInfo() עם האובייקט AddCustomAudienceOverrideRequest והאובייקטים הרלוונטיים Executor ו-OutcomeReceiver.

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

הערכים של buyer ושל name הם אותם ערכים ששימשו ליצירת הקהל המותאם אישית. מידע נוסף על השדות האלה

בנוסף, אפשר לציין עוד שני פרמטרים:

• ‫biddingLogicJs: קוד JavaScript שמכיל את הלוגיקה של הקונה שמשמשת במהלך בחירת המודעה. אפשר לראות את חתימות הפונקציות הנדרשות בקוד JavaScript הזה.
• ‫trustedBiddingSignals: אותות בידינג לשימוש במהלך בחירת המודעות. למטרות בדיקה, אפשר להזין מחרוזת ריקה.

ה-method האסינכרוני overrideCustomAudienceRemoteInfo() משתמש באובייקט OutcomeReceiver כדי לסמן את התוצאה של הקריאה ל-API.

הקריאה החוזרת onResult() מציינת שההחלפה בוצעה בהצלחה. קריאות עוקבות ל-selectAds() ישתמשו בכל לוגיקת בידינג ודיווח שהעברתם כהחלפה.

הקריאה החוזרת (callback) ‏onError() מציינת שני תנאים אפשריים.

• אם מנסים לבצע את ההחלפה עם ארגומנטים לא תקינים, AdServiceException מציין את IllegalArgumentException כסיבה.
• אם מנסים לבצע את ההחלפה באפליקציה שלא פועלת במצב ניפוי באגים עם אפשרויות למפתחים מופעלות, AdServiceException מציין את IllegalStateException כסיבה.

איפוס שינויים בצד הקונה

בקטע הזה מניחים שביצעתם שינוי ב-JavaScript בצד הקונה ושיש לכם הפניה אל TestCustomAudienceManager שנעשה בו שימוש בקטע הקודם.

כדי לאפס את ההגדרות ששונו לכל הקהלים המותאמים אישית:

1. מבצעים קריאה לשיטה האסינכרונית resetAllCustomAudienceOverrides() עם אובייקטים רלוונטיים של Executor ושל OutcomeReceiver.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

אחרי איפוס ההגדרות שמוגדרות בצד הקונה, קריאות עתידיות ל-selectAds() ישתמשו בכל biddingLogicUrl ו-trustedBiddingData שמאוחסנים ב-CustomAudience כדי לנסות לאחזר את ה-JavaScript הנדרש.

אם הקריאה ל-resetCustomAudienceRemoteInfoOverride() נכשלת, הקריאה החוזרת OutComeReceiver.onError() מספקת AdServiceException. אם מנסים להסיר חריגות באפליקציה שלא פועלת במצב ניפוי באגים עם אפשרויות למפתחים מופעלות, AdServiceException מציין את IllegalStateException כסיבה.

הגדרת שרת דיווח

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

כשמחפשים את הגדרות OpenAPI, מחפשים את הקובץ reporting-server.json. הקובץ הזה מכיל נקודת קצה שמחזירה 200, שמייצגת קוד תגובה של HTTP. נקודת הקצה הזו משמשת במהלך selectAds() ומאותתת ל-Protected Audience API שדיווח החשיפות הושלם בהצלחה.

פונקציונליות לבדיקה

• תרגול הצטרפות או יציאה והגדרת קהל בהתאמה אישית על סמך פעולות קודמות של משתמשים.
• הפעלת תהליך בחירת המודעות במכשיר באמצעות קובצי JavaScript שמתארחים מרחוק.
• בודקים איך השיוך של אפליקציה להגדרות של קהלים בהתאמה אישית משפיע על תוצאות בחירת המודעות.
• הפעלת דיווח על חשיפות אחרי בחירת המודעה.

מגבלות

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

דיווח על באגים ובעיות

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