Attribution Reporting API: מדריך השילוב

תצוגה מקדימה למפתחים בטא

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

---

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

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

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

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

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

איור 1. תהליך השילוב של השיוך (Attribution).

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

כדי להבין טוב יותר את Attribution Reporting API, כדאי לבצע את השלבים שמפורטים בקטע הזה. בעזרת השלבים האלה תוכלו לאסוף תוצאות משמעותיות כשאתם משתמשים ב-API בסביבת ה-AdTech.

היכרות עם ה-API

1. מומלץ לקרוא את הצעת העיצוב כדי להכיר את Attribution Reporting API ואת היכולות שלו.
2. במדריך למפתחים מוסבר איך לשלב את הקוד ואת קריאות ה-API שנדרשים לתרחישי לדוגמה.
3. נרשמים כדי לקבל עדכונים על Attribution Reporting API. כך תוכלו להתעדכן בתכונות החדשות שיושקו בגרסאות עתידיות.

הגדרה ובדיקה של האפליקציה לדוגמה

1. כשתהיו מוכנים להתחיל את השילוב, תוכלו להיעזר בגרסת Developer Preview האחרונה ב-Android Studio.
2. הגדרת נקודות קצה של שרת מדומה לרישום אירועים ולשליחת דוחות. סיפקנו מודלים לדוגמה שאפשר להשתמש בהם בשילוב עם כלים שזמינים באינטרנט.
3. כדי להתנסות ברישום של מקורות וטריגרים, אפשר להוריד את הקוד ולהריץ אותו באפליקציה לדוגמה.
1. מגדירים את חלון הזמן לשליחת דוחות. ה-API תומך בחלונות של 2 ימים, 7 ימים או תקופה מותאמת אישית של בין 2 ל-30 ימים.
2. אחרי שתירשמו מקורות וטריגרים על ידי הפעלת האפליקציה לדוגמה ושימוש בה, ושהפרק הזמן שהוגדר חלף, עליכם לוודא שקיבלת דוח ברמת האירוע ודוח מוצפן שניתן לצבור. אם אתם צריכים לנפות באגים בדוחות, תוכלו ליצור אותם מהר יותר על ידי הפעלה בכוח של משימות הדיווח.
3. בודקים את התוצאות של שיוך (Attribution) מאפליקציה לאפליקציה. מוודאים שהנתונים בתוצאות האלה תואמים לציפיות, גם במקרים של נקודת המגע האחרונה וגם במקרים של אירועים לאחר ההתקנה.
4. אחרי שתקבלו מושג איך ה-API של הלקוח והשרת פועלים יחד, תוכלו להשתמש באפליקציית הדוגמה כמדריך לשילוב שלכם. מגדירים שרת ייצור משלכם ומוסיפים לאפליקציות קריאות לרישום אירועים.

שילוב מראש

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

מעורבות של שותפים

שותפי טכנולוגיות הפרסום (MMP/‏SSP/‏DSP) יוצרים לרוב פתרונות משולבים של שיוך (Attribution). השלבים שבקטע הזה יעזרו לכם להתכונן לעבודה מוצלחת עם שותפי ה-AdTech שלכם.

1. כדאי לקבוע פגישה עם שותפי המדידה המובילים שלכם כדי לדון בבדיקה ובשימוש ב-Attribution Reporting API. שותפי מדידה יכולים להיות רשתות של טכנולוגיות פרסום, פלטפורמות SSP, פלטפורמות DSP, מפרסמים או כל שותף אחר שאיתו אתם עובדים כרגע או שאתם רוצים לעבוד איתו.
2. כדאי לשתף פעולה עם שותפי המדידה כדי לקבוע לוחות זמנים לשילוב, מהבדיקה הראשונית ועד להטמעה.
3. חשוב להבהיר לשותפי המדידה אילו תחומים כל אחד מהם יטפל בהם בתכנון השיוך.
4. יצירת ערוצי תקשורת בין שותפי המדידה כדי לסנכרן לוחות זמנים ובדיקות מקצה לקצה.
5. תכנון תעבורת נתונים ברמה גבוהה בין שותפי המדידה. בין השיקולים החשובים:
   • איך שותפי המדידה יירשמו מקורות שיוך באמצעות Attribution Reporting API?
   • איך רשתות טכנולוגיית הפרסום יירשמו טריגרים ב-Attribution Reporting API?
   • איך כל פתרון טכנולוגיה לפרסום יאמץ בקשות API ויחזיר תשובות כדי להשלים את הרישום של המקור ולהפעיל אותו?
   • האם יש דוחות שצריך לשתף עם שותפים מחוץ ל-Attribution Reporting API?
   • האם יש נקודות שילוב או התאמה אחרות שנדרשות בין השותפים? לדוגמה, האם אתם והשותפים שלכם צריכים לעבוד על הסרת כפילויות של המרות, או להתאים את מפתחות הצבירה?
6. אם השיוך (Attribution) מהאפליקציה לאתר רלוונטי, כדאי לקבוע פגישה עם שותפי המדידה באינטרנט כדי לדון בתכנון, בבדיקות ובשימוש ב-Attribution Reporting API. כשמתחילים לנהל שיחות עם שותפי האינטרנט, כדאי להיעזר בשאלות מהשלב הקודם.

אב טיפוס של שיוך (Attribution) ברמת האירוע מאפליקציה לאפליקציה

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

1. הגדרת שרת איסוף לרשומות אירועים. כדי לעשות זאת, אפשר להשתמש במפרט שסופק כדי ליצור שרת מדומה, או להגדיר שרת משלכם באמצעות קוד השרת לדוגמה.
2. מוסיפים קריאות לאירועי רישום מקור ל-SDK או לאפליקציה כשמודעות מוצגות.
   • שיקולים קריטיים כוללים את הדברים הבאים:
     • מוודאים שמזהי האירועים של המקור זמינים ומועברים בצורה נכונה לשיחות ה-API של רישום המקור.
     • חשוב לוודא שאפשר גם להעביר אירוע InputEvent כדי לרשום מקורות קליקים.
     • קובעים איך להגדיר את תעדוף המקור לסוגי אירועים שונים. לדוגמה, אפשר להקצות עדיפות גבוהה לאירועים שנחשבים לחשובים, כמו קליקים מול צפיות.
     • ערך ברירת המחדל לתאריך התפוגה מתאים לבדיקה. לחלופין, אפשר להגדיר חלונות תפוגה שונים.
     • אפשר להשאיר את המסננים וחלונות השיוך כברירת המחדל לצורך בדיקה.
   • שיקולים אופציונליים נוספים:
     • אם אתם מוכנים, תוכלו לתכנן מפתחות צבירת נתונים.
     • כדאי להביא בחשבון את שיטת ההפניה האוטומטית כשמגדירים את אופן העבודה עם שותפי מדידה אחרים.
3. מוסיפים אירועי טריגר לרישום ל-SDK או לאפליקציה כדי לתעד אירועי המרה.
   • שיקולים קריטיים כוללים את הדברים הבאים:
     • מגדירים את נתוני הטריגר, תוך התחשבות ברמת הנאמנות המוגבלת של הנתונים שמוחזרים: איך תוכלו לצמצם את מספר סוגי ההמרות שהמפרסמים שלכם צריכים, בהתאם ל-3 הביטים שזמינים לקליקים ולביט אחד שזמין לצפיות?
     • מגבלות על הטריגרים הזמינים בדוחות אירועים: איך מתכוונים לצמצם את מספר ההמרות הכולל לכל מקור שאפשר לקבל בדוחות האירועים?
   • שיקולים אופציונליים נוספים:
     • כדאי לדלג על יצירת מפתחות למניעת כפילויות עד שמבצעים בדיקות של דיוק.
     • כדאי לדלג על יצירת מפתחות וערכי צבירת נתונים עד שהתמיכה בבדיקת סימולציות תהיה מוכנה.
     • כדאי לדלג על ההפניות האוטומטיות עד שתבחרו איך תרצו לעבוד עם שותפי מדידה אחרים.
     • עדיפות הטריגר לא חיונית לבדיקה.
     • סביר להניח שאפשר להתעלם מהמסננים בבדיקה הראשונית.
4. בודקים אם מתבצעת יצירת אירועי מקור למודעות, ואם הטריגרים מובילים ליצירת דוחות אירועים.

בדיקת סימולציה

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

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

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

1. מגדירים את ספריית הדמיית המדידה במחשב המקומי.
2. במפרט מוסבר איך צריך לעצב את נתוני ההמרות כדי שיתואמו ליצירת הדוחות המדומים.
3. תכנון מפתחות הסיכום על סמך הדרישות העסקיות.
   • שיקולים קריטיים כוללים את הדברים הבאים:
     • כדאי להביא בחשבון את המאפיינים הקריטיים שהלקוחות או השותפים שלכם צריכים לצבור, ולהתמקד בהם במסגרת הבדיקה.
     • קובעים את המספר המינימלי של מאפיינים מצטברים ושל עוצמות (cardinalities) שנדרשים כדי לעמוד בדרישות.
     • חשוב לוודא שחלקי המפתח בצד המקור ובצד הטריגר לא חורגים מ-128 ביט.
     • אם הפתרונות שלכם כוללים תרומה לכמה ערכים לכל אירוע מפעיל, חשוב לשנות את היקף הערכים בהתאם לתקציב התרומה המקסימלי, L1. כך תוכלו לצמצם את ההשפעה של הרעש.
     • כאן מופיעה דוגמה להגדרת מפתח לאיסוף נתונים מצטברים של מספר ההמרות ברמת הקמפיין, ומפתח לאיסוף נתונים מצטברים של ערכי הרכישות ברמת המיקום הגיאוגרפי.
4. מריצים את הכלי ליצירת דוחות כדי ליצור דוחות של אירועים ודוחות שאפשר לצבור.
5. מריצים את הדוחות שאפשר לצבור דרך שרתי הצבירה המדומים כדי לקבל דוחות סיכום.
6. לבצע ניסויים לבחירת כלי:
   • כדי לבדוק את הדיוק של דיווח ההמרות, אפשר להשוות בין סכומי ההמרות הכוללים בדוחות ברמת האירוע ובדוחות הסיכום לבין נתוני ההמרות ההיסטוריים. כדי לקבל את התוצאות הטובות ביותר, מומלץ להריץ את הבדיקות וההשוואות של הדיווח על קבוצה רחבה ודוגמנית של המפרסמים.
   • אימון מחדש של המודלים על סמך נתוני דוחות ברמת האירוע, וייתכן גם נתוני דוחות סיכום. השוואת רמת הדיוק למודלים שנוצרו על סמך נתוני אימון היסטוריים.
   • נסו אסטרטגיות שונות של קיבוץ מודעות כדי לראות איך הן משפיעות על התוצאות.
     • שיקולים קריטיים כוללים את הדברים הבאים:
     • עדכניות הדוחות הסיכומיים לצורך התאמת הצעות מחיר.
     • התדירויות הממוצעות של אירועים שניתנים לשיוך במכשיר. לדוגמה, משתמשים שהפסיקו להשתמש בשירות וחוזרים אליו על סמך נתונים היסטוריים של אירועי רכישה.
     • רמת הרעש. ככל שיש יותר קבוצות, כך הצבירה קטנה יותר, וככל שהצבירה קטנה יותר, כך יתווספו יותר רעשים.

שיוך של שרת צבירת נתונים לפרוטוטיפ: הגדרה

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

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

שיוך של שרת צבירה לאב טיפוס: שילוב

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

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

שיפור העיצוב באמצעות תכונות אופציונליות

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

שימוש ב-Debug API ליצירת מפתחות ניפוי באגים (מומלץ מאוד)

הערה: התכונה הזו תהיה זמינה בגרסת הבטא הציבורית.

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

התאמה אישית של התנהגויות השיוך

1. שיוך לטריגרים לאחר ההתקנה
   • אפשר להשתמש בתכונה הזו במקרים שבהם צריך לשייך טריגרים שלאחר ההתקנה לאותו מקור שיוך שהניב את ההתקנה, גם אם יש מקורות שיוך אחרים שעומדים בדרישות ושקרו לאחרונה יותר.
   • לדוגמה, יכול להיות מצב שבו משתמש לוחץ על מודעה שמובילה להתקנה. לאחר ההתקנה, המשתמש לוחץ על מודעה אחרת ומבצע רכישה. במקרה כזה, יכול להיות שחברת טכנולוגיית הפרסום תרצה שהרכישה תשויך לקליק הראשון ולא לקליק של יצירת העניין מחדש.
2. שימוש במסננים כדי לשפר את הנתונים בדוחות ברמת האירוע
   • אפשר להגדיר מסנני המרות כך שיתעלמו מטריגרים נבחרים ויחרגו אותם מדוחות האירועים. יש מגבלות על מספר הטריגרים לכל מקור שיוך, ולכן המסננים מאפשרים לכם לכלול בדוחות האירועים רק את הטריגרים שמספקים את המידע הכי שימושי.
   • אפשר גם להשתמש במסננים כדי לסנן באופן סלקטיבי טריגרים מסוימים, כלומר להתעלם מהם. לדוגמה, אם יש לכם קמפיין שמטרגט התקנות של אפליקציה, מומלץ לסנן את הטריגרים שלאחר ההתקנה כדי שלא ישויכו למקורות מהקמפיין הזה.
   • אפשר גם להשתמש במסננים כדי להתאים אישית את נתוני הטריגר על סמך נתוני המקור. לדוגמה, מקור יכול לציין את הערך "product" : ["1234"], כאשר product הוא מפתח המסנן ו-1234 הוא הערך. המערכת תתעלם מכל טריגר עם מפתח מסנן מסוג 'product' שיש לו ערך שאינו '1234'.
3. התאמה אישית של תעדוף המקור והטריגר
   • אם אפשר לשייך כמה מקורות שיוך לטריגר, או אם אפשר לשייך כמה טריגרים למקור, אפשר להשתמש במספר שלם 64 ביט עם סימן כדי לתת עדיפות לשיוכים מסוימים של מקורות או טריגרים על פני אחרים.

עבודה עם פלטפורמות ניהול רשתות (MMP) וגורמים אחרים

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

עבודה עם מדידה בפלטפורמות שונות

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