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

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

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

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

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

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

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

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

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

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

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

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

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

כדי שהפעולה הזו תפעל, מבצע הקריאה במכשיר (בין אם מדובר ב-MMP או ב-SSP SDK) יוצר 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 זמין במאמר Design Proposal for Join CA Delegation.

בדיקה

אחרי שמטמיעים את קריאת האחזור בקוד הלקוח ומגדירים נקודת קצה בצד ה-DSP כדי להחזיר את נתוני הקהל המותאם אישית, אפשר לבדוק את הענקת הגישה להצטרפות לקהל מותאם אישית. לפני שמפעילים את האפליקציה, צריך להריץ את הפקודות בדף Testing setup. אחרי שתפעילו את הפקודות האלה, תוכלו להתחיל לבצע קריאות באמצעות 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()

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

• הקריאה החוזרת (callback) onResult() מציינת שהקהל בהתאמה אישית נוצר או עודכן בהצלחה.
• קריאת החזרה (callback) של onError() מציינת שני תנאים אפשריים.
  • אם JoinCustomAudienceRequest מופעל עם ארגומנטים לא חוקיים, הערך IllegalArgumentException יופיע כגורם ב-AdServicesException.
  • כל שאר השגיאות מקבלות את הערך 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. קוראים ל-method 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. כדי להגן על הפרטיות, תוצאת השגיאה לא מבדילה בין שגיאות פנימיות לבין ארגומנטים לא חוקיים. פונקציית ה-callback‏ onResult() מופעלת בסיום קריאת ה-API, גם אם קהל מותאם אישית תואם הושמט בהצלחה וגם אם לא.