בהמשך לקריאה על ארגז החול לפרטיות ב-Android תיעוד, השתמשו בלחצן תצוגה מקדימה למפתחים או בטא כדי לבחור בגרסת התוכנה שאיתה אתם עובדים, כי ההוראות עשויות להשתנות.
Protected Audience API ב-Android (לשעבר FLEDGE) כולל Custom Audience API ו-Ad Selection API. פלטפורמות ומפרסמים של טכנולוגיות פרסום יכול להשתמש בממשקי ה-API האלה כדי להציג מודעות מותאמות אישית על סמך אינטראקציות קודמות עם האפליקציה, מגבילה את השיתוף של המזהים בין אפליקציות ומגבילה את השיתוף של כל אפליקציה של משתמש על האינטראקציה עם צדדים שלישיים.
Custom Audience API מתמקד ב'קהל בהתאמה אישית' הפשטה, שמייצגת קבוצה של משתמשים עם כוונות משותפות. מפרסם יכול לרשום משתמש עם קהל מותאם אישית ולשייך מודעות רלוונטיות איתו. המידע הזה מאוחסן באופן מקומי ויכול לשמש כדי ליידע את המפרסם הצעות מחיר, סינון מודעות והצגת מודעות.
Ad Selection API מספקת מסגרת שמאפשרת למספר מפתחים: להפעיל מכרז מקומי עבור קהל מותאם אישית. כדי לעשות את זה, מביא בחשבון מודעות רלוונטיות שמשויכות לקהל המותאם אישית וביצועים עיבוד נוסף של מודעות שפלטפורמת פרסום דיגיטלי מחזירה למכשיר.
פלטפורמות פרסום דיגיטלי יכולות לשלב את ממשקי ה-API האלה כדי להטמיע רימרקטינג שומרת על פרטיות המשתמשים. תמיכה בתרחישים נוספים לדוגמה, כולל התקנת אפליקציה של מודעות מתוכננות להפצות עתידיות. מידע נוסף על Protected Audience API API ב-Android בהצעה לעיצוב.
במדריך הזה מוסבר איך לעבוד עם Protected Audience API ב-Android כדי לבצע את הפעולות הבאות:
לפני שמתחילים
לפני שמתחילים, צריך לבצע את הפעולות הבאות:
- מגדירים את סביבת הפיתוח לארגז החול לפרטיות ב-Android.
- מתקינים תמונת מערכת במכשיר נתמך או מגדירים אמולטור שכולל תמיכה בארגז החול לפרטיות ב-Android.
בטרמינל, מפעילים גישה ל-Protected Audience API (מושבת) כברירת מחדל) באמצעות פקודת adb הבאה.
adb shell device_config put adservices ppapi_app_allow_list \"*\"
צריך לכלול הרשאת
ACCESS_ADSERVICES_CUSTOM_AUDIENCE
באפליקציה מניפסט:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
להפנות להגדרה של שירותי מודעות ברכיב
<application>
של במניפסט:<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />
צריך לציין את משאב ה-XML של שירותי המודעות שיש אליו הפניה במניפסט, למשל
res/xml/ad_services_config.xml
מידע נוסף על הרשאות לשירותי מודעות ובקרת גישה ל-SDK.<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>
כברירת מחדל, Ad Selection API אוכפת מגבלות בניצול המקסימלי של הזיכרון שמדווחים על מכרזים או על חשיפות שהסקריפט יכול להקצות. לתכונה 'הגבלת זיכרון' נדרשת גרסת WebView 105.0.5195.58 ומעלה. הפלטפורמה אוכפת בדיקת גרסאות וקוראת ל- ממשקי ה-API של
selectAds
ושלreportImpression
ייכשלו. לא מרוצה. יש שתי אפשרויות להגדיר:אפשרות 1: מריצים את פקודת adb הבאה כדי להשבית את הבדיקה:
adb device_config put fledge_js_isolate_enforce_max_heap_size false
אפשרות 2: מתקינים את WebView בטא מחנות Google Play. חובה להיות שווה לגרסה שצוינה למעלה או גבוהה ממנה.
הצטרפות לקהל בהתאמה אישית
קהל בהתאמה אישית מייצג קבוצה של משתמשים עם כוונות נפוצות או תחומי עניין, כפי שנקבע על ידי האפליקציה של המפרסם. אפליקציה או SDK עשויים להשתמש בהתאמה אישית כדי לציין קהל מסוים, כמו מישהו שהשאיר פריטים בעגלת קניות. כדי ליצור קהל מותאם אישית או להצטרף אליו באופן אסינכרוני, מבצעים את הפעולות הבאות: הבאים:
- מאתחלים את האובייקט
CustomAudienceManager
. - יוצרים אובייקט
CustomAudience
על ידי ציון פרמטרים מרכזיים כמו החבילה של הקונה ושם רלוונטי. לאחר מכן מאתחלים את האובייקטJoinCustomAudienceRequest
עם הסמלCustomAudience
לאובייקט. - קוראים לפונקציה
joinCustomAudience()
האסינכרונית עם אובייקטJoinCustomAudienceRequest
ורלוונטיExecutor
וגםOutcomeReceiver
אובייקטים.
Kotlin
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)
Java
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) לתוכן מסוג B&A.
פרמטרים אופציונליים לאובייקט CustomAudience
יכולים לכלול:
- זמן הפעלה: קהל בהתאמה אישית יכול להשתתף רק בבחירת מודעות ועדכונים יומיים אחרי שעת ההפעלה. האפשרות הזו יכולה לעזור לעורר עניין משתמשים שאינם פעילים באפליקציה, לדוגמה.
- מועד תפוגה: מועד עתידי שאחריו הקהל בהתאמה אישית הוסר מהמכשיר.
- אותות לבידינג של משתמשים: מחרוזת JSON שמכילה אותות של משתמשים, כמו המיקום המועדף על המשתמש, ש-JavaScript של הלוגיקה של הקונה לבידינג כדי ליצור הצעות מחיר בתהליך בחירת המודעות. הפורמט הזה עוזר לשפר את טכנולוגיות הפרסום פלטפורמות עושים שימוש חוזר בקוד בפלטפורמות שונות ומקלות על השימוש ב-JavaScript למשימות ספציפיות.
- נתוני בידינג מהימנים: כתובת URL מסוג HTTPS ורשימת מחרוזות שנעשה בהן שימוש במהלך תהליך לבחירת מודעות, שמאחזר אותות לבידינג ממפתח/ערך מהימן לאחר השיפור.
- מודעות: רשימה של אובייקטים ב-
AdData
שתואמים למודעות להשתתף בבחירת מודעות. כל אובייקטAdData
מורכב מ:- כתובת URL לעיבוד: כתובת URL מסוג HTTPS שאליה נשלחת שאילתה להצגת המודעה הסופית.
- מטא-נתונים: אובייקט JSON שעבר סריאליזציה למחרוזת שמכילה מידע צריכה להתאים ללוגיקת הבידינג של הקונה במהלך תהליך בחירת המודעה.
- מסנני מודעות: מחלקה שמכילה את כל המידע הנדרש לאפליקציה להתקין סינון מודעות ומכסת תדירות במהלך בחירת המודעות.
דוגמה לייצוג אובייקט CustomAudience
:
Kotlin
// 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()
Java
// 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()
השיטה האסינכרונית joinCustomAudience()
משתמשת בOutcomeReceiver
לאותת התוצאה של הקריאה ל-API.
- הקריאה החוזרת (callback) של
onResult()
מציינת שהקהל בהתאמה אישית הצליח נוצרו או עודכנו. - הקריאה החוזרת (callback) של
onError()
מציינת שני תנאים אפשריים.- אם ה-
JoinCustomAudienceRequest
אותחל עם ערך לא חוקי ארגומנטים,AdServicesException
מצייןIllegalArgumentException
כהסיבה. - כל שאר השגיאות יקבלו
AdServicesException
עםIllegalStateException
הוא הגורם לבעיה.
- אם ה-
דוגמה לטיפול בתוצאה של joinCustomAudience()
:
Kotlin
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)
}
};
Java
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
על סמך המאפיין הייחודי שלו
מבצעים את הפעולות הבאות:
- מאתחלים את האובייקט
CustomAudienceManager
. - הפעלת
LeaveCustomAudienceRequest
עם הקהל בהתאמה אישיתbuyer
וגםname
. כדי לקבל מידע נוסף על השדות האלה להזנת קלט, אפשר לקרוא "הצטרפות לקהל בהתאמה אישית". - קריאה לשיטה
leaveCustomAudience()
האסינכרונית עם אובייקטLeaveCustomAudienceRequest
ורלוונטיExecutor
וגםOutcomeReceiver
אובייקטים.
Kotlin
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)
Java
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()
:
- מאתחלים אובייקט
AdSelectionManager
. - בונים אובייקט
AdSelectionConfig
. - קריאה לשיטה
selectAds()
האסינכרונית עם אובייקטAdSelectionConfig
ורלוונטיExecutor
וגםOutcomeReceiver
אובייקטים.
Kotlin
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
)
Java
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 נשלחה עם שאילתה כדי לקבל את כתובת ה-URL של רשת המודעות של בית העסק
לוגיקת JavaScript.
- כתובת URL מסוג HTTPS: נשלחה שאילתה כדי לקבל את לוגיקת ה-JavaScript של רשת המודעות של המוכר. כאן מפורטות הפעולות הנדרשות בחתימות של הפונקציות.
- URI מובנה: תואם לפורמט בחירת המודעות של FLEDGE.
אם הפורמט של
IllegalArgumentException
לא נתמך או שהוא שגוי עברת את ה-URI המובנה.
- קונים של קהלים בהתאמה אישית: רשימה מלאה של מזהים לרשתות המודעות של קונים
שמותרות על ידי המפיץ להשתתף בתהליך בחירת המודעות.
מזהי הקונים האלה תואמים ל-
CustomAudience.getBuyer()
מתוך בקהלים בהתאמה אישית שמשתתפים בתוכנית.
אפשר לציין את הפרמטרים הבאים כדי שההתאמה האישית של המודעות תהיה מדויקת יותר בחירה:
- אותות לבחירת מודעות: אובייקט JSON שעבר סריאליזציה למחרוזת, שמכיל
אותות שייעשה בהם שימוש על ידי לוגיקת הבידינג של הקונה, שאוחזרה מ-
CustomAudience.getBiddingLogicUrl()
. - אותות של בית עסק: אובייקט JSON שעבר סריאליזציה למחרוזת, ומכיל אותות
נעשה על ידי לוגיקת ההחלטה של בית העסק המאוחזרת באמצעות JavaScript,
AdSelectionConfig.getDecisionLogicUrl()
. - אותות לפי קונה: מפה של אובייקטים מסוג JSON, שעברו סריאליזציה למחרוזות,
שמכיל אותות לצריכה של קונים ספציפיים JavaScript של לוגיקת בידינג
אוחזרו מ-
CustomAudience.getBiddingLogicUrl()
, שמזוהים באמצעות שדות הקונה של קהלים בהתאמה אישית שמשתתפים. - מודעות לפי הקשר: אוסף של מועמדים למודעות שנאספים ישירות מקונים במהלך מכרז שמתרחש מחוץ ל-Protected Audience API. במכרז.
אחרי שבוחרים מודעה, התוצאות, הצעות המחיר והאותות נשמרים באופן פנימי
לצורכי דיווח. הקריאה החוזרת של OutcomeReceiver.onResult()
מחזירה
AdSelectionOutcome
שמכיל:
- כתובת URL לעיבוד של המודעה הזוכה, שהתקבלה מהכתובת
AdData.getRenderUrl()
. - מזהה ייחודי של בחירת מודעות למשתמש במכשיר. המזהה הזה משמש לדיווח החשיפה של המודעה.
אם לא ניתן להשלים את בחירת המודעה מסיבות כמו
ארגומנטים לא חוקיים, זמנים קצובים לתפוגה או צריכת משאבים מוגזמת,
קריאה חוזרת של OutcomeReceiver.onError()
מספקת AdServicesException
עם ההתנהגויות הבאות:
- אם בחירת המודעה מתחילה עם ארגומנטים לא חוקיים,
AdServicesException
מצייןIllegalArgumentException
בתור סיבה. - כל שאר השגיאות יקבלו
AdServicesException
עםIllegalStateException
הוא הגורם לבעיה.
מודעות לפי הקשר
Protected Audience API יכול לשלב מודעות לפי הקשר במכרז מוגן.
יש לבחור מודעות לפי הקשר בשרת הפרסום הדיגיטלי ולהחזיר אותן
המכשיר מחוץ לממשקי ה-API של Protected Audience API. לאחר מכן ניתן לכלול מודעות לפי הקשר
במכרז באמצעות AdSelectionConfig
, שבשלב שבו הן פועלות
זהות לאלה של מודעות במכשיר, כולל זכאות לסינון מודעות שליליות. אחרי ש
המכרז של Protected Audience הושלם. עליך להפעיל
reportImpression()
קריאה לפעולה זו מפעילה את reportWin()
במודעה ההקשרית הזוכה,
זהה לדפוס של דיווח על חשיפות, כדי לקבל את המודעה הזוכה
במכשיר. כל מודעה לפי הקשר זקוקה לקונה, להצעת מחיר, לקישור ללוגיקת דיווח,
לעבד את כתובת האתר ואת המטא-נתונים של המודעות.
כדי לפרוס מודעות לפי הקשר באפליקציה, אפליקציית היעד צריכה ליצור
אובייקט ContextualAds
:
Kotlin
val contextualAds: ContextualAds =
Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
//Pass in your valid app install ads
.setDecisionLogicUri(mContextualLogicUri)
.setAdsWithBid(appInstallAd)
.build()
Java
ContextualAds contextualAds = new ContextualAds.Builder()
.setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
.setDecisionLogicUri(mContextualLogicUri)
//Pass in your valid app install ads
.setAdsWithBid(appInstallAd)
.build();
לאחר מכן ניתן להעביר את אובייקט ContextualAds
שמתקבל במהלך היצירה
AdSelectionConfig
:
Kotlin
// 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)
Java
// 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);
סינון מודעות להתקנת אפליקציה
סינון מודעות להתקנת אפליקציות עוזר לסנן מודעות התקנה שמוצגות לאפליקציות שכבר מותקנים במכשיר.
השלב הראשון בתהליך הזה הוא להגדיר לאילו מפרסמים יש את היכולת כדי לסנן לפי החבילה המותקנת. הפעולה הזו צריכה להתבצע באפליקציה הרצויה כדי לטרגט באמצעות מודעה.
Kotlin
//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)
}
})
Java
//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
שלהם במידע לגבי המודעות
שקשורות לאפליקציות שהם רוצים לסנן:
Kotlin
// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
Builder().setPackageNames(setOf("example.target.app")).build()
).build()
Java
// 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
חדש
object:
Kotlin
// 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()
Java
// 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();
סינון של מכסת תדירות
סינון של מכסת תדירות מאפשר לטכנולוגיות של מודעות להגביל את מספר הפעמים שמודעה מוצגת. סינון של מכסת תדירות מפחית חשיפת יתר של מודעות ומבצע אופטימיזציה של חלופות בחירת מודעות לקמפיין מסוים.
במסנן של מכסת התדירות יש שני רכיבים עיקריים: סוג האירוע של המודעה, המפתח למונה המודעות. אלה הסוגים הזמינים של אירועי מודעות:
- זכייה (בקרוב): אירוע של זכייה מציין שהמודעה זכתה במכרז. אירועי Win מתעדכנים באופן אוטומטי על ידי 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
אובייקטים כפי שמוצג בהמשך:
Kotlin
// 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()
Java
// 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
.
Kotlin
val filters: AdFilters = Builder()
.setFrequencyCapFilters(
Builder()
.setKeyedFrequencyCapsForImpressionEvents(
ImmutableObject.of(keyedFrequencyCapForImpression)
)
.setKeyedFrequencyCapsForClickEvents(
ImmutableObject.of(keyedFrequencyCapForClick)
)
).build()
Java
AdFilters filters = new AdFilters.Builder()
.setFrequencyCapFilters(new FrequencyCapFilters.Builder()
.setKeyedFrequencyCapsForImpressionEvents(
ImmutableObject.of(keyedFrequencyCapForImpression)
)
.setKeyedFrequencyCapsForClickEvents(
ImmutableObject.of(keyedFrequencyCapForClick)
)
).build();
כשהאובייקט AdFilters
מאוכלס במסננים של מכסת תדירות, אפשר לבחור
מועברות כשקהל בהתאמה אישית נוצר:
Kotlin
// 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()
Java
// 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 יכול לאחר מכן להפעיל את אירועי הקליק, הצפייה או החשיפה הנדרשים.
Kotlin
val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()
val request: UpdateAdCounterHistogramRequest = Builder(
adSelectionId,
FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
callerAdTech
).build()
Java
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 מוכנים מראש לאותות דירוג. עיינו במאמרים נתמכים
קטע בנושא שמות ותרחישים לדוגמה מראש של URI לרשימה של scoreAds
בפועל.
כדי להציג בחירת מודעות ללא שיחות רשת:
- הגדרה של סינון מודעות
- יצירת מודעות לפי הקשר
יוצרים אובייקט
AdSelectionConfig
עם הפרטים הבאים:- רשימה ריקה של קונים
- URI מובנה מראש כדי לבחור את הצעת המחיר הגבוהה ביותר
- מודעות לפי הקשר
- 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();
הפעלת בחירת מודעות:
adSelectionManager.selectAds( adSelectionConfig, executor, outcomeReceiver);
הרצת JavaScript לדיווח משלכם תוך שימוש במזהי URI מוכנים מראש
כיום, לפלטפורמה של ארגז החול לפרטיות יש רק JavaScript בסיסי לדיווח
זמינה למזהי URI מוכנים מראש. אם רוצים לנהל
דיווח על JavaScript תוך שימוש במזהי URI מוכנים מראש למודעה עם זמן אחזור קצר
הבחירה הזו, אפשר לשנות את DecisionLogicUri
בין בחירת המודעה לבין
הדוחות.
- מפעילים את השלבים להפעלת בחירת מודעות עבור מודעות לפי הקשר באמצעות מזהי URI מוכנים מראש
לפני שמפעילים את הדיווח צריך ליצור עותק של
AdSelectionConfig
adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder() // Replace <urlToFetchYourReportingJS> with your own URL: .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>)) .build();
הפעלת דיווח על חשיפות
// adSelectionId is from the result of the previous selectAds run ReportImpressionRequest request = new ReportImpressionRequest( adSelectionId, adSelectionConfigWithYourReportingJS); adSelectionManager.reportImpression( request, executor, outcomeReceiver);
הפעלה של רשימת הרשתות בתהליך בחירת הרשת
כדי להשתמש בתהליך בחירת הרשת ב-Waterfall, צריך להגדיר כמה ערכות SDK של צד שלישי (רשתות צד שלישי) תוזמנה על ידי רשת לבחירת רשת (Mediation) SDK של צד ראשון. תהליך בחירת הרשת ב-Waterfall הוא באותה הדרך, ללא קשר למכרז שבו התנהלה במכשיר או התנהלה בידינג ו שירותי מכרזים (B&A).
רשתות של צד שלישי
רשתות הצד השלישי צריכות לספק מתאם שמאפשר לרשת תהליך בחירת הרשת (Mediation) להפעיל את השיטות הנדרשות להפעלת מכרז:
- הפעלת בחירת מודעות
- דיווח על חשיפות
דוגמה למתאם רשת בתהליך בחירת הרשת:
Kotlin
class NetworkAdaptor {
private val adSelectionManager : AdSelectionManager
init {
adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
}
fun selectAds() {...}
fun reportImpressions() {...}
}
Java
class NetworkAdaptor {
AdSelectionManager adSelectionManager;
public NetworkAdaptor() {
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
}
public void selectAds() {...}
public void reportImpressions() {...}
}
לכל SDK יש מנהלי שירות ולקוחות משלהם לבחירת מודעות,
הטמעה של selectAds
ו-reportImpressions
. ספקי SDK יכולים לעיין
לקטעים על הפעלת בחירת מודעות עבור מכרזים במכשיר או מודעות לקידום מלונות
הסברלמכרזי מלונות. הוראות לדיווח על מודעה
חשיפות (בהתאם לדיווח על חשיפות יחיד של SSP עבור
דיווח.
רשת תהליך בחירת הרשת (Mediation)
בדומה לרשתות של צד שלישי, לרשתות בתהליך בחירת הרשת צריך להגדיר selectAds
וגם
reportImpression
מוטמעים. מומלץ לעיין בקטעים בנושא הפעלת מודעה
בחירה ואיך לדווח על חשיפות של מודעות, כדי לקבל מידע נוסף.
הרשתות בתהליך בחירת הרשת אחראיות להפעלת שרשרת תהליך בחירת הרשת (Mediation) ולמיקום בשרשרת לבחירת רשת. בקטע הבא מוסבר איך מגדירים מפעילים את התהליך הזה.
אחזור של שרשרת תהליך בחירת הרשת וערכי סף תחתון להצעות מחיר
הרשת לבחירת רשת אחראית לאחזור הנתונים מהאינטראקציה הישירה (First-Party)
מודעות לפי הקשר, שרשרת לבחירת רשת ורשתות צד שלישי ערכי סף להצעות מחיר (צד ג'). הזה
יכול לקרות בבקשה לאחזור מודעות לפי הקשר שהופעלו על ידי הגישור
עמוקה מאוד, שרשרת תהליך בחירת הרשת קובעת איך לחזור על עצמן דרך הרשתות של הצד השלישי,
וניתן להעביר את ערכי הסף התחתון של הצעת המחיר לתהליך המכרז בתור adSelectionSignals
.
מיקום הרשת בשרשרת לבחירת רשת
ערכת SDK של תהליך בחירת הרשת יכולה למקם את עצמה בשרשרת לבחירת רשת על סמך העלות בפועל לאלף חשיפות (eCPM) שלה בזמן אמת
של הצעות מחיר למודעות מאינטראקציה ישירה. ב-Protected Audience API, הצעות המחיר למודעות הן אטומות. תהליך בחירת הרשת (Mediation)
ערכת ה-SDK צריכה להשתמש ב-AdSelectionFromOutcomesConfig
כדי להשוות בין נתונים מאינטראקציה ישירה
הצעת המחיר של המודעה לסף הצעת המחיר של הרשת הבאה של צד שלישי בשרשרת. אם הצעת המחיר מאינטראקציה ישירה היא
גבוהה מהסף התחתון להצעת המחיר, המשמעות היא שערכת ה-SDK של תהליך בחירת הרשת (Mediation) נמצאת בחזית
של רשת הצד השלישי הזאת.
הפעלת בחירת מודעות
כדי לאחזר אפשרות להצגת מודעות מאינטראקציה ישירה, הרשת בתהליך בחירת הרשת יכולה להפעיל במכשיר
במכרז על פי השלבים המפורטים בקטע הפעלת בחירת מודעות. הפעולה הזו יוצרת
מועמד למודעה מאינטראקציה ישירה, הצעת מחיר ו-AdSelectionId
שנמצאים בשימוש בתהליך בחירת הרשת
תהליך האימות.
יצירת AdSelectionFromresultsConfig
AdSelectionFromOutcomesConfig
מאפשר לרשת בתהליך בחירת הרשת להעביר רשימה
של AdSelectionIds
(תוצאות ממכרזים קודמים), אותות לבחירת מודעות ו
URI לאחזור JavaScript שבוחר מודעה מתוך מועמדים מרובים. הרשימה
של AdSelectionIds יחד עם הצעות המחיר שלהם והאותות מועברים אל
JavaScript שיכול להחזיר אחד מהערכים AdSelectionIds
אם הוא גבוה מהצעת המחיר
סף תחתון או כלל לא אם שרשרת בחירת הרשת אמורה להמשיך.
הרשתות בתהליך בחירת הרשת (Mediation) יוצרות AdSelectionFromOutcomesConfig
באמצעות הצד השלישי
AdSelectionId
מהקטע הקודם, והסף התחתון להצעת המחיר לרשת הצד השלישי
ואנחנו שוקלים אותם. צריך ליצור AdSelectionFromOutcomesConfig
חדש
לכל שלב בשרשרת לבחירת רשת.
Kotlin
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)
}
Java
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 של תהליך בחירת הרשת (Mediation) תהיה אפשרות לקצר את שרשרת תהליך בחירת הרשת כאשר מנצחת נמצא.
אחרי שה-AdSelectionOutcomesConfig
נוצר, מפעילים את ה-method selectAds()
של
ברשת הצד השלישי שנמצאת ראשונה בשרשרת.
Kotlin
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)
Java
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);
תזמור רשימת רשתות בתהליך בחירת הרשת
זהו סדר הפעולות לביצוע תהליך בחירת הרשת (Mediation) תהליך האימות.
- הפעלת בחירת מודעות מאינטראקציה ישירה.
- איטרציה לאורך שרשרת תהליך בחירת הרשת. בכל רשת של צד שלישי:
- Build
AdSelectionFromOutcomeConfig
, כוללoutcomeId
מאינטראקציה ישירה וגם הסף התחתון להצעת המחיר ל-SDK של צד שלישי. - קוראים לפונקציה
selectAds()
עם ההגדרות מהשלב הקודם. - אם לא מופיעה תוצאה ריקה, מחזירים את המודעה.
- קוראים לשיטה
selectAds()
של מתאם רשת ה-SDK הנוכחי. אם התוצאה לא ריק, החזר את המודעה.
- Build
- אם לא נמצא מנצח ברשת, מחזירים את המודעה מאינטראקציה ישירה.
Kotlin
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)
}
Java
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 אחד שמפעיל מכרז, יש לעיין בקטע הבא. אם המיקום שבכוונתכם להטמיע את רשימת הרשתות בתהליך בחירת הרשת, צריך לפעול לפי השלבים המפורטים בקטע 'דיווח על חשיפות בתהליך בחירת הרשת ב-Waterfall'.
דיווח על חשיפות SSP יחיד
אחרי שבוחרים מודעה מנצחת מתוך תהליך העבודה של בחירת המודעות, אפשר לבצע את הפעולות הבאות:
לדווח על החשיפה לפלטפורמות שמשתתפות בתוכנית בצד הקונה ובצד המוכר
באמצעות השיטה AdSelectionManager.reportImpression()
. איך מדווחים על מודעה
חשיפה:
- מאתחלים אובייקט
AdSelectionManager
. - יוצרים אובייקט
ReportImpressionRequest
עם המזהה של בחירת המודעות. - קריאה לשיטה
reportImpression()
האסינכרונית עם אובייקטReportImpressionRequest
ורלוונטיExecutor
וגםOutcomeReceiver
אובייקטים.
Java
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);
Kotlin
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
עם הדרישות הבאות
:
- מזהה בחירת מודעות: מזהה ייחודי למשתמש במכשיר שמזהה בחירה מוצלחת של המודעה.
- הגדרה של בחירת מודעות: אותה הגדרה ששימשה בשדה
selectAds()
קריאה מזוהה לפי המזהה שצוין לבחירת המודעה.
השיטה האסינכרונית reportImpression()
משתמשת בOutcomeReceiver
לאותת התוצאה של הקריאה ל-API.
- הקריאה החוזרת (callback) של
onResult()
מציינת אם כתובות ה-URL לדיווח על חשיפות נוצרה והבקשה תוזמנה. - הקריאה החוזרת של
onError()
מציינת את התנאים האפשריים הבאים:- אם הקריאה מאותחלת עם ארגומנט קלט לא חוקי,
AdServicesException
מצייןIllegalArgumentException
בתור הסיבה. - כל שאר השגיאות יקבלו
AdServicesException
עםIllegalStateException
הוא הגורם לבעיה.
- אם הקריאה מאותחלת עם ארגומנט קלט לא חוקי,
דיווח על חשיפות בתהליך בחירת הרשת (Mediation) ב-Waterfall
ערכת ה-SDK של תהליך בחירת הרשת (Mediation) צריכה לעקוב אחרי ערכת ה-SDK הזוכה כדי להפעיל את בדיווחים. ערכות ה-SDK שמשתתפות בשרשרת לבחירת רשת צריכות לספק כדי שהמגשר יוכל להפעיל את תהליך הדיווח שלו. SDK שמשתתפים במכרז של תהליך בחירת הרשת (Mediation) יכולים לפעול לפי השלבים שמפורטים למעלה כדי להטמיע, הדוחות שלהם.
ספקי SSP יכולים להשתמש בדוגמה הזו לקוד ה-SDK של צד שלישי בתור אב טיפוס של הדרך להצטרף תהליכי בחירת הרשת:
Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
mediationSdk.orchestrateMediation(mediationChain);
if (winner.first.hasOutcome()) {
winner.second.reportImpressions(winner.first.getAdSelectionId());
נקודות קצה לדיווח על חשיפות
הדוח 'ה-API של החשיפות' מנפיק בקשות מסוג HTTPS GET לנקודות קצה (endpoints) שסופקו על ידי הפלטפורמה בצד המוכר והפלטפורמה הזוכה בצד הקונה:
נקודת קצה בפלטפורמה בצד הקונה:
- ה-API משתמש בכתובת ה-URL של הלוגיקה לבידינג שצוינה בקהל בהתאמה אישית כדי לאחזר את ה-JavaScript שסופק על ידי הקונה וכולל לוגיקה להחזרת כתובת URL לדיווח על חשיפות.
- מפעילים את פונקציית ה-JavaScript
reportWin()
, שאמורה לחזור כתובת האתר לדיווח על חשיפות של הקונה.
נקודת קצה בפלטפורמה בצד המוכר:
- משתמשים בכתובת ה-URL של לוגיקת ההחלטה שצוינה ב-
AdSelectionConfig
כדי לאחזר את קוד ה-JavaScript של לוגיקת ההחלטה של בית העסק. - מפעילים את פונקציית ה-JavaScript
reportResult()
, שאמורה להחזיר את כתובת האתר לדיווח על חשיפות של בית העסק.
בידינג ו דיווח על שירותי מכרזים
מכרז שמופעל על ידי בידינג לשירותי המכרז יהיו כל מידע, כולל כתובות URL שנוצרות לדיווח על אינטראקציות עם מודעות, נכללות בתגובה המוצפנת מהמכרז בצד השרת. כאשר שהתשובה מפוענחת, כתובות ה-URL המתאימות רשומות בפלטפורמה, כך הדיווח על מודעות ועל חשיפות כולל את אותם השלבים שמפורטים למעלה.
הדיווח על חשיפות במאמץ הטוב ביותר
השיטה reportImpression()
נועדה להציע את ההשלמה הטובה ביותר של
דיווח.
דיווח על אינטראקציות עם מודעות
Protected Audience API תומך בדיווח על אינטראקציות מפורטות יותר עבור מודעה שעברה עיבוד. האינטראקציות האלה עשויות לכלול אינטראקציות כמו זמן צפייה, קליקים, העברות עכבר, או כל מדד שימושי אחר שניתן לאסוף. התהליך לקבלת נדרשים שני שלבים. ראשית, קונים ומוכרים חייבים להירשם כדי לקבל בדוחות האלה ב-JavaScript לדיווח. לאחר מכן הלקוח יצטרך לדווח על האירועים האלה.
הרשמה לקבלת אירועי אינטראקציה
הרשמה לאירועי אינטראקציה מתרחשת בreportWin()
של הקונה,
פונקציות JavaScript 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()
). כך מדווחים על אירוע מודעה:
- מאתחלים אובייקט
AdSelectionManager
. - יוצרים אובייקט
ReportInteractionRequest
עם המזהה של בחירת המודעות. מפתח אינטראקציה, נתוני אינטראקציה ויעד לדיווח. - קריאה לשיטה
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 של הדיווח.
- נתוני אינטראקציה: מחרוזת שמכילה נתונים שייכללו באירוע כדי להופיע חזרה לשרתי הדיווח.
- יעדי דיווח: מסכה קטנה שמציינת אם האירועים
ידווחו לקונה, למפיץ או לשניהם. הסימונים האלה מסופקים על ידי
ואת מסכת היעד הסופית ניתן ליצור באמצעות
ב-AI. כדי לדווח ליעד אחד, אפשר להשתמש בדגל שסופק על-ידי
ישירות בפלטפורמה. כדי לדווח ליעדים מרובים, אפשר להשתמש במאפיין הסיביות
או (
|
) כדי לשלב ערכי דגל.
השיטה האסינכרונית reportInteraction()
משתמשת בOutcomeReceiver
לאותת התוצאה של הקריאה ל-API.
- הקריאה החוזרת (callback) של
onResult()
מציינת שהקריאה לאינטראקציה בדוח חוקית. - הקריאה החוזרת של
onError()
מציינת את התנאים האפשריים הבאים:- אם השיחה מתבצעת כשהאפליקציה פועלת ברקע,
הפונקציה
IllegalStateException
עם תיאור של הכשל מוחזרת. - אם יש ויסות נתונים (throttle) של הלקוח מהתקשרות אל
reportInteraction()
, השדהLimitExceededException
הוחזר. - אם החבילה לא רשומה להפעלה של ממשקי ה-API לשמירה על פרטיות,
השדה
SecurityException()
הוחזר. - אם האינטראקציות לדיווח על האפליקציה שונות מהאפליקציה שנקראת
selectAds()
, מוחזרIllegalStateException
.
- אם השיחה מתבצעת כשהאפליקציה פועלת ברקע,
הפונקציה
- אם המשתמש לא הסכים להפעיל את ממשקי ה-API של ארגז החול לפרטיות, תתבצע קריאה תיכשל בשקט.
נקודות קצה לדיווח על אינטראקציות
ה-Reporting API מנפיק בקשות HTTPS POST לנקודות קצה (endpoints) שסופקו על ידי הפלטפורמה בצד המוכר והפלטפורמה המנצחת בצד הקונה. קהל מוגן יתאים בין מפתחות האינטראקציה למזהי ה-URI שהוצהרו ב-JavaScript לדיווח והם שולחים בקשת POST לכל נקודת קצה (endpoint) עבור כל אינטראקציה שמדווחת. סוג התוכן של הבקשה הוא טקסט פשוט שבו הגוף הוא נתוני אינטראקציה.
הדיווח על אינטראקציות עם הסיכוי הכי טוב
המטרה של reportInteraction()
היא לאפשר את הפעולה הטובה ביותר
דיווח באמצעות HTTP POST.
עדכון רקע יומי
כשיוצרים קהל בהתאמה אישית, האפליקציה או ה-SDK יכולים להפעיל קהל בהתאמה אישית מטא-נתונים. בנוסף, הפלטפורמה יכולה לעדכן את החלקים הבאים של מטא-נתונים של קהל עם תהליך עדכון יומי ברקע.
- אותות לבידינג של משתמשים
- נתוני בידינג מהימנים
- רשימה אחת (
AdData
)
בתהליך הזה נשלחות שאילתות לגבי כתובת ה-URL לעדכון יומי שהוגדרה בקהל בהתאמה אישית וכתובת ה-URL עשויה להחזיר תגובת JSON.
- תגובת JSON עשויה להכיל כל אחד משדות המטא-נתונים הנתמכים שנדרשים להם צריך להתעדכן.
- כל שדה JSON מאומת בנפרד. הלקוח מתעלם מכל אחד לשדות שגויים, וכתוצאה מכך לא יתקבלו עדכונים לשדה המסוים הזה את התשובה.
- תגובת HTTP ריקה או אובייקט JSON ריק "
{}
" לא התקבלו תוצאות ועדכוני מטא-נתונים. - הגודל של הודעת התשובה חייב להיות מוגבל ל-10KB.
- כל מזהי ה-URI נדרשים להשתמש ב-HTTPS.
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 שסופק על ידי הקונה מאוחזר מכתובת ה-URL של לוגיקת הבידינג שצוינה ב קהל בהתאמה אישית. קוד ה-JavaScript שמוחזר צריך לכלול את הפונקציות הבאות:
JavaScript שסופק על ידי בית העסק מאוחזר מכתובת ה-URL של לוגיקת ההחלטות שצוינה ב-
הפרמטר AdSelectionConfig
ל-API לבחירת מודעות. המוחזר
קוד JavaScript צריך לכלול את הפונקציות הבאות:
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" }
איפה:
owner
,buyer
ו-name
הם מחרוזת שנלקחה מהנכסים שיש להם את זהה לשם של הקהל בהתאמה אישית שמשתתף בבחירת המודעהactivation_time
ו-expiration_time
הם זמן ההפעלה ו של הקהל בהתאמה אישית, מבוטאת בשניות מאז ה-Unix תקופה של זמן מערכתca_user_bidding_signals
היא מחרוזת JSON שצוינה בקובץ השדהuserBiddingSignals
בCustomAudience
בזמן היצירהtrusted_bidding_signals, contextual_signals
ו-user_signals
הם JSON אובייקטים. הם יועברו כאובייקטים ריקים וימלאו אותם גרסאות עתידיות. הפלטפורמה לא אוכפת את הפורמט שלהן, והוא מנוהל על ידי טכנולוגיית הפרסום.
תוצאה:
ad
: המודעה שאליה מתייחסת הצעת המחיר. הסקריפט מורשה להחזיר עותק של את המודעה שהוא קיבל עם מטא-נתונים שונים. המאפייןrender_url
של לא צפויים שינויים.bid
: ערך צף שמייצג את ערך הצעת המחיר של המודעהstatus
: ערך של מספר שלם שיכול להיות:0
: לביצוע מוצלח1
: (או כל ערך שאינו אפס) במקרה שאחד מהאותות של הקלט לא חוקי. לחשבון במקרה שבו מוחזר ערך שאינו אפס על ידי יצירת הצעת מחיר, תהליך הבידינג לא תקף לכל מודעות ה-CA
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
של ה-APIselectAds
. הפורמט היא: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 שנקראים מהsellerSignals
AdSelectionConfig
פרמטר APItrusted_scoring_signal
: קריאה מהשדהadSelectionSignals
שבשדהAdSelectionConfig
פרמטר APIcontextual_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
להצלחה, לא אפס לכישלון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
הטמעת לוגיקה של קטיעת תהליך בחירת הרשת (Mediation) ב-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 סביבת בדיקה:
- מריצים שרת עם נקודות הקצה (endpoints) הנדרשות של HTTPS שמחזירות את ה-JavaScript.
- ביטול אחזור מרחוק על ידי אספקת הקוד הדרוש ממקור מקומי
בכל אחת מהשיטות צריך להגדיר נקודת קצה (endpoint) מסוג HTTPS כדי לטפל בחשיפות דיווח.
נקודות קצה ב-HTTPS
כדי לבדוק את בחירת המודעות ואת הדיווח על החשיפות, צריך להגדיר 7 HTTPS נקודות הקצה שמכשיר הבדיקה או האמולטור שלך יכולים לגשת אליהן:
- נקודת הקצה של הקונה שמציגה את ה-JavaScript של לוגיקת הבידינג.
- נקודת קצה (endpoint) שמספקת את האותות של הבידינג.
- נקודת הקצה של בית העסק שמציגה את ה-JavaScript של לוגיקת ההחלטות.
- נקודת קצה (endpoint) שמציגה אותות ניקוד.
- נקודת קצה לדיווח על חשיפות של קונה זוכה.
- נקודת קצה לדיווח על חשיפות של בית העסק.
- נקודת קצה להצגת העדכונים היומיים לקהל בהתאמה אישית.
לנוחיותכם, המאגר של GitHub מספק קוד JavaScript בסיסי לצורך בדיקה. למטרות. הוא כולל גם הגדרות של שירות OpenAPI שניתן לפרוס פלטפורמת הדמיה נתמכת או פלטפורמה מיקרו-שירותים (microservices). פרטים נוספים זמינים בפרויקט README.
ביטול אחזור מרחוק של JavaScript
התכונה הזו מיועדת לשימוש בבדיקת 'קצה-לקצה'. כדי לשנות את ההגדרות של השלט הרחוק אחזור, האפליקציה שלך חייבת לפעול במצב ניפוי באגים כשהאפשרויות למפתחים מופעלות.
כדי להפעיל את מצב ניפוי הבאגים באפליקציה, צריך להוסיף את השורה הבאה לקטע במאפיין האפליקציה בקובץ AndroidManifest.xml:
<application
android:debuggable="true">
לדוגמה, כיצד להשתמש בביטולים האלו, אפשר לעיין במדיניות 'Protected' אפליקציה לדוגמה של Audience API ב-GitHub.
עליך להוסיף JavaScript מותאם אישית משלך כדי לטפל בתרחישים של בחירת מודעות כמו כמו בידינג, דירוג, החלטות ודיווח. ניתן למצוא קוד JavaScript בסיסי דוגמאות לטיפול בכל הבקשות הנדרשות במאגר GitHub. האפליקציה לדוגמה של Protected Audience API מדגימה איך לקרוא קוד מ- את הקובץ ולהכין אותו לשימוש כשינוי מברירת המחדל.
אפשר לבטל אחזור JavaScript בצד המוכר ובצד הקונה בנפרד, אבל צריך נקודת קצה (endpoint) מסוג HTTPS כדי להציג כל JavaScript שלא הגדרת עבורם שינויים מברירת המחדל. אפשר לעיין בREADME של על ההגדרה של שרת שמטפל בבקשות האלה.
אפשר לבטל אחזור של JavaScript רק לקהלים מותאמים אישית הם בבעלות החבילה שלך.
שינוי JavaScript בצד המוכר
כדי להגדיר שינוי מברירת המחדל של JavaScript בצד המוכר, מבצעים את הפעולות הבאות כפי שמתואר בדוגמת הקוד הבאה:
- מאתחלים אובייקט
AdSelectionManager
. - אפשר לקבל הפניה אל
TestAdSelectionManager
מ אובייקטAdSelectionManager
. - בונים אובייקט
AdSelectionConfig
. - ליצור
AddAdSelectionOverrideRequest
עם אובייקטAdSelectionConfig
ו-String
שמייצג את ה-JavaScript שמתכוונים להשתמש בו בתור שינוי מברירת המחדל. - קריאה לשיטה
overrideAdSelectionConfigRemoteInfo()
האסינכרונית עם אובייקטAddAdSelectionOverrideRequest
ורלוונטיExecutor
ו-OutcomeReceiver
אובייקטים.
Kotlin
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)
Java
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.
השיטה האסינכרונית overrideAdSelectionConfigRemoteInfo()
משתמשת ב
אובייקט OutcomeReceiver
לציון תוצאת הקריאה ל-API.
הקריאה החוזרת onResult()
מציינת שהביטול הוחל בהצלחה.
שיחות עתידיות אל selectAds()
יתבססו על כל החלטה ודיווח
הלוגיקה שהעברתם כשינוי מברירת המחדל.
הקריאה החוזרת של onError()
מציינת שני תנאים אפשריים:
- אם יתבצע ניסיון לשנות מברירת המחדל עם ארגומנטים לא חוקיים,
AdServiceException
מצייןIllegalArgumentException
בתור סיבה. - אם נעשה ניסיון לשנות מברירת המחדל ואפליקציה שלא פועלת במצב ניפוי באגים עם
אפשרויות למפתחים מופעלות,
AdServiceException
מצייןIllegalStateException
הוא הגורם לבעיה.
איפוס השינויים מברירת המחדל בצד המוכר
הקטע הזה מניח שעקפתם את קוד ה-JavaScript בצד המוכר
יש לכם הפניה אל TestAdSelectionManager
AdSelectionConfig
היה בשימוש בקטע הקודם.
כדי לאפס את השינויים מברירת המחדל לכל הפריטים ב-AdSelectionConfigs
:
- הפעלה של שיטת
resetAllAdSelectionConfigRemoteOverrides()
האסינכרונית עם האובייקט הרלוונטיOutcomeReceiver
.
Kotlin
// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver)
Java
// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver);
לאחר איפוס השינויים בצד המוכר, קריאות ל-selectAds()
ישתמשו בכל
הפרמטר decisionLogicUrl מאוחסן ב-AdSelectionConfig
כדי לנסות
מאחזרת את ה-JavaScript הדרוש.
אם הקריאה ל-resetAllAdSelectionConfigRemoteOverrides()
תיכשל,
הקריאה החוזרת של OutComeReceiver.onError()
מספקת AdServiceException
.
אם נעשה ניסיון להסיר את השינויים מברירת המחדל ואפליקציה שלא פועלת במצב ניפוי באגים
כאשר האפשרויות למפתחים מופעלות, AdServiceException
מציין
IllegalStateException
הוא הגורם לבעיה.
ביטול JavaScript בצד הקונה
- פועלים לפי השלבים להצטרפות לקהל בהתאמה אישית.
- יצירת
AddCustomAudienceOverrideRequest
עם הקונה ושם הקהל בהתאמה אישית שרוצים לשנות, בנוסף הלוגיקה של הבידינג והנתונים שבהם רוצים להשתמש כשינוי מברירת המחדל - קריאה לשיטה
overrideCustomAudienceRemoteInfo()
האסינכרונית עם אובייקטAddCustomAudienceOverrideRequest
ורלוונטיExecutor
ו-OutcomeReceiver
אובייקטים
Kotlin
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)
Java
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
: האותות לבידינג שבהם צריך להשתמש במהלך בחירת המודעות. למטרות בדיקה, הערך הזה יכול להיות מחרוזת ריקה.
השיטה האסינכרונית overrideCustomAudienceRemoteInfo()
משתמשת ב
אובייקט OutcomeReceiver
כדי לאותת את תוצאת הקריאה ל-API.
הקריאה החוזרת onResult()
מציינת שהביטול הוחל בהצלחה.
הקריאות הבאות אל selectAds()
משתמשות בלוגיקת בידינג ובדיווח כלשהי
העברת כשינוי מברירת המחדל.
הקריאה החוזרת (callback) של onError()
מציינת שני תנאים אפשריים.
- אם יתבצע ניסיון לשנות מברירת המחדל עם ארגומנטים לא חוקיים,
AdServiceException
מצייןIllegalArgumentException
בתור סיבה. - אם נעשה ניסיון לשנות מברירת המחדל ואפליקציה שלא פועלת במצב ניפוי באגים עם
אפשרויות למפתחים מופעלות,
AdServiceException
מצייןIllegalStateException
הוא הגורם לבעיה.
איפוס שינויים מברירת המחדל בצד הקונה
קטע זה מתבסס על ההנחה ששינית את קוד ה-JavaScript בצד הקונה,
יש לך הפניה אל TestCustomAudienceManager
שנעשה בו שימוש
בקטע הקודם.
כדי לאפס את השינויים מברירת המחדל של כל הקהלים בהתאמה אישית:
- קריאה לשיטה
resetAllCustomAudienceOverrides()
האסינכרונית עם אובייקטים רלוונטיים מסוגExecutor
ו-OutcomeReceiver
.
Kotlin
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Java
// 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, צריך לחפש את הקובץ report-server.json.
הקובץ הזה מכיל נקודת קצה פשוטה שמחזירה את 200, שמייצגת HTTP
קוד תגובה. נקודת הקצה (endpoint) הזו נמצאת בשימוש במהלך selectAds()
ומציינת ל
Protected Audience API שדיווח על חשיפות הושלם בהצלחה.
פונקציונליות לבדיקה
- תרגיל הצטרפות או עזיבה והגדרת קהל בהתאמה אישית לפי פעולות משתמש.
- התחלת בחירת המודעות במכשיר באמצעות JavaScript שמתארחים מרחוק.
- לבדוק איך שיוך של אפליקציה להגדרות קהלים בהתאמה אישית עשוי להשפיע על המודעה או תוצאות בחירה.
- מקבלים דיווח על חשיפות אחרי בחירת המודעות.
מגבלות
בטבלה הבאה מפורטות המגבלות על עיבוד Protected Audience API. המגבלות שמוצגות עשויות להשתנות בהתאם למשוב. עבור יכולות בתהליך, יש לקרוא את נתוני הגרסה.
רכיב | תיאור המגבלה | ערך מגבלה |
---|---|---|
קהל בהתאמה אישית (CA) | מספר מודעות מקסימלי לכל CA | 100 |
המספר המקסימלי של רשויות אישורים לכל בקשה | 1000 | |
מספר האפליקציות המקסימלי שיכול ליצור רשות אישורים | 1000 | |
העיכוב המקסימלי בזמן ההפעלה של רשות אישורים ממועד היצירה שלה | 60 ימים | |
זמן התפוגה המקסימלי של רשות אישורים (CA) מזמן ההפעלה שלה | 60 ימים | |
המספר המקסימלי של רשויות אישורים במכשיר | 4000 | |
הגודל המקסימלי של שם ה-CA | 200 בייטים | |
הגודל המקסימלי של URI לאחזור יומי | 400 בייטים | |
הגודל המקסימלי של ה-URI של לוגיקת הבידינג | 400 בייטים | |
הגודל המקסימלי של נתוני בידינג מהימנים | 10 KB | |
הגודל המקסימלי של האותות לבידינג המשתמשים | 10 KB | |
שיעור שיחות מקסימלי ב-leaveCustomAudience לכל קונה |
1 לשנייה | |
שיעור שיחות מקסימלי עבור joinCustomAudience לכל קונה |
1 לשנייה | |
אחזור רקע של קליפורניה | פג הזמן הקצוב של החיבור | 5 שניות |
זמן קצוב לתפוגה של קריאת HTTP | 30 שניות | |
גודל הורדה כולל מקסימלי | 10 KB | |
משך זמן מקסימלי של איטרציה של אחזור | 5 דקות | |
המספר המקסימלי של רשויות אישורים שעודכנו לכל משימה | 1000 | |
בחירת מודעות | מספר קונים מקסימלי | טרם נקבע |
המספר המקסימלי של רשויות אישורים לכל קונה | טרם נקבע | |
המספר המקסימלי של מודעות במכרז | טרם נקבע | |
זמן קצוב ראשוני לתפוגת החיבור | 5 שניות | |
הזמן הקצוב לקריאת החיבור פג | 5 שניות | |
זמן ביצוע מקסימלי של AdSelection |
10 שניות | |
זמן ביצוע מקסימלי של בידינג לכל CA ב-AdSelection |
5 שניות | |
זמן ביצוע מקסימלי של ניקוד ב-AdSelection |
5 שניות | |
זמן ביצוע מקסימלי לכל קונה ב-AdSelection |
טרם נקבע | |
הגודל המקסימלי של אותות בחירת המודעה/אתר המכירה/לכל קונה | טרם נקבע | |
הגודל המקסימלי של סקריפטים של אתר מכירה/קונה | טרם נקבע | |
קצב שיחות מקסימלי ב-selectAds |
QPS אחד | |
דיווח על חשיפות | זמן מינימלי לפני הסרת המודעות שנבחרו מהתמיד | 24 שעות |
המספר המקסימלי של מודעות האחסון שייבחרו | טרם נקבע | |
הגודל המקסימלי של כתובת URL לפלט הדיווח | טרם נקבע | |
משך זמן מקסימלי לדיווח על חשיפות | טרם נקבע | |
המספר המרבי של ניסיונות חוזרים לשיחות התראה | טרם נקבע | |
תם פרק הזמן שהוקצב להתחברות | 5 שניות | |
זמן הביצוע הכולל המקסימלי של reportImpression |
2 שניות | |
קצב שיחות מקסימלי ב-reportImpressions |
QPS אחד | |
דיווח על אירועים | המספר המקסימלי של משׂואות רשת (beacon) לכל קונה בכל מכרז | 10 |
המספר המקסימלי של משׂואות רשת (beacon) לכל אתר מכירה בכל מכרז |
10 |
|
הגודל המקסימלי של מפתח האירוע |
40 בייטים |
|
הגודל המקסימלי של נתוני האירוע |
64KB |
|
מודעות | גודל מקסימלי של רשימת מודעות | 10KB משותפים לכולם
AdData
ברשות אישורים אחת לקבלת |
URLs | האורך המקסימלי של כל מחרוזת כתובת URL שנלקחה כקלט | טרם נקבע |
JavaScript | זמן ביצוע מקסימלי | שנייה אחת לבידינג ולציון בדוחות חשיפות |
נפח זיכרון מקסימלי | 10 MB |
דיווח על באגים ובעיות
המשוב שלכם הוא חלק חיוני בארגז החול לפרטיות ב-Android. נשמח לשמוע ממך על כל בעיות שמצאתם או רעיונות לשיפור ארגז החול לפרטיות ב-Android.
מומלץ עבורך
- הערה: טקסט הקישור מוצג כאשר JavaScript מושבת
- לתמוך בטירגוט לפי קהל בהתאמה אישית עם Protected Audience API
- נתוני גרסה
- Protected Audience: מדריך לשילוב