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

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

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

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

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

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

בנוסף, צריך ליצור את 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 שעבר סריאליזציה כמחרוזת, ומכיל מידע שמשמש את לוגיקת הבידינג של הקונה במהלך תהליך בחירת המודעות.
  • מסנני מודעות: מחלקה שמכילה את כל המידע הנדרש לסינון מודעות להתקנת אפליקציות ולהגבלת תדירות הצגת המודעות במהלך בחירת המודעות.

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

ה-API של fetchAndJoinCustomAudience מאפשר לקונים להעביר את ההצטרפות לקהל מותאם אישית באמצעות הנוכחות במכשיר של שותפי ה-MMP או ה-SSP שלהם.

כדי שהתהליך הזה יפעל, המתקשר במכשיר (בין אם מדובר ב-SDK של MMP או SSP) יוצר fetchAndJoinCustomAudienceRequest שנראה כך:

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

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

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

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

מידע נוסף על אופן הפתרון בצד ה-API זמין בהצעה לעיצוב של הצטרפות להענקת הרשאות של CA.

בדיקה

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

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

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

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

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

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

// Minimal initialization of a CustomAudience object
val audience: 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()

// 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);

// Minimal initialization of a CustomAudience object
CustomAudience audience = 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();

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

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

טיפול בתוצאות של 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 מסתיימת, בין אם קהל מותאם שמתאים להסרה הוסר בהצלחה ובין אם לא.