במדריך הזה מפורט משאבים לפתרון בעיות ב-RTB, שמאפשרים לגשת באופן פרוגרמטי
של קמפיינים עם בידינג בזמן אמת, שנחשפים גם דרך
הכלי RTB Breakout נמצא בקטע
ממשק המשתמש של Authorized Buyers. למשל bidders.filterSets, bidders.accounts.filterSets
את כל המשאבים שנמצאים מתחת להיררכיה הזו באופן היררכי.
בעזרת מדדים מהמשאבים לפתרון בעיות ב-RTB, אפשר לקבל תובנות לגבי הזדמנויות שהוחמצו כדי לזכות בחשיפות, שיכולות לעזור לכם לבצע אופטימיזציה של קמפיין עם בידינג בזמן אמת.
התאמות במבנה ובסגנון של API
המשאבים לפתרון בעיות ב-RTB כוללים מספר שינויים שנועדו לציין במפורש בעלות גישה, לספק שליטה מפורטת יותר על הנתונים שמחזיר ה-API, ולהתאים טוב יותר שיטות תכנון ב-Google API.
משאבים ברמת מגיש הצעות המחיר וברמת החשבון
המשאבים בנויים גם ב-bidders וגם ב-bidders.accounts. הן מאפשרות לכם לציין
האם קריאה ל-API מטרגטת מגיש הצעות מחיר (שנקרא גם חשבון הורה) וכל
חשבונות צאצא או חשבונות Authorized Buyers פרטיים. בהקשר של הצעות מחיר בזמן אמת (RTB)
פתרון בעיות, משאבים המובנים בקטע bidders.filterSets יחזירו מדדים נצברים
של מגיש הצעות המחיר הנתון ושל כל חשבונות הצאצא המשויכים אליו. לעומת זאת, לקוחות שתחת
הפונקציה bidders.accounts.filterSets תחזיר מדדים רק לגבי החשבון שצוין, ללא קשר ל-
בין אם מדובר בחשבון של מגיש הצעות מחיר או בחשבון צאצא.
הערה: חשבונות שמעבירים את הבידינג שלהם לקונה אחר הם לא חשבונות של מגישי הצעות מחיר, וכן
ולכן לא יכולים לגשת למשאבים ברמת מגיש הצעות המחיר. כמו כן, חשבונות שאינם מגישי הצעות מחיר לא יכולים
גישה אל impressionMetrics, filteredBidResponses, bidResponseErrors וגם ברמת החשבון
bidResponsesWithoutBids משאבים.
חדש: שמות משאבים כמזהים ייחודיים
שמות המשאבים משמשים בתור מזהים ייחודיים ולא מזהים של מספרים שלמים או של מחרוזות. כשיוצרים מופע חדש של מופע נתון סוג המשאב, עכשיו צריך לציין יחסי שם המשאב באמצעות נתיב ה-URI של המשאב ואחריו מזהה המשאב המועדף. הנה דוגמאות לשמות שרלוונטיים למשאבים לפתרון בעיות ב-RTB:
| משאב | דוגמה לשם |
|---|---|
| bidders.filterSets | bidders/12345678/filterSets/fset_1 |
| bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
הערה: מזהה המשאב שצוין ל-bidders בשם חייב להיות של מגיש הצעות המחיר
מספר חשבון Authorized Buyers. ב-accounts, מזהה המשאב חייב להיות מספר חשבון של אחד או יותר
מגיש הצעות המחיר או חשבון צאצא שמנוהל על ידו. אם אתם לא יודעים אילו Authorized Buyers
שמשויכים לחשבון Google, אפשר להשתמש
accounts.list כדי למצוא אותם.
קבוצות מסננים
קבוצת מסננים היא ייצוג של אפשרויות הסינון הזמינות, וניתן ליצור אותן ברמת מגיש הצעות המחיר או ברמת החשבון. הוא משמש לסינון התוצאות ברשימה של פתרון בעיות ב-RTB משאבים שמאחזרים מדדים של קמפיינים עם בידינג בזמן אמת.
המסנן שמיושם באחזור המדדים מייצג את חתך של כל מסנן במאפיין שצוין
קבוצת מסננים. מסננים של רשימה, כמו platforms, מפורשים כאיחוד של כל פריט ברשימה.
קבוצות המסננים של מגיש הצעות המחיר ושל ברמת החשבון הן נפרדות ונגישות רק מהרמה שבה הם נוצרו - בלי קשר לחשבון שדרכו הם נוצרו. מגיש הצעות המחיר חולק חשבון עם חשבון צאצא של מסננים שנוצרו ברמת החשבון. לעומת זאת, רק מגיש הצעות מחיר יכול לגשת למשאבים ברמת מגיש הצעות המחיר. הטבלה הבאה מסכמת את האופן שבו מגישי הצעות מחיר וחשבונות צאצא יכולים לגשת למשאבים בכל אחת מהרמות:
| bidders.filterSets | bidders.accounts.filterSets | |
|---|---|---|
| חשבון מגיש הצעות המחיר | קריאה ל-API שמשפיעה רק על קבוצות מסננים ברמת מגיש הצעות המחיר. | קריאה ל-API שמשפיעה רק על קבוצות מסננים ברמת החשבון. |
| חשבון צאצא | הקריאה הזו ל-API תחזיר תגובת שגיאה. | קריאה ל-API שמשפיעה רק על קבוצות מסננים ברמת החשבון. |
יצירה של קבוצת מסננים
כשיוצרים קבוצת מסננים, צריך לציין טווח זמן בתור relativeDateRange,
absoluteDateRange או realtimeTimeRange. במהלך אחזור המדדים,
פעולת ברירת המחדל היא שכל הנתונים יסופקו לכל טווח הזמן. אם רוצים לקבל
פירוט של סדרת זמנים לאורך טווח הזמן, אפשר לציין timeSeriesGranularity
כדי לציין אינטרוולים של HOURLY או DAILY.
אם דרושה לך קבוצת מסננים רק לפרק זמן קצר, אפשר להגדיר את isTransient
של השאילתה ל-true. הסטטוס הזה מציין שקבוצת המסננים היא זמנית, כלומר היא לא תישאר בתוקף לזמן בלתי מוגבל. קבוצות מסננים זמניות יהיו זמינות למשך שעה לפחות לאחר היצירה שלהן, אבל בסופו של דבר הן יימחקו. כברירת מחדל, קבוצות מסננים הן לא זמניות.
דוגמה ברמת מגיש הצעות המחיר
כדי ליצור קבוצת מסננים חדשה ברמת מגיש הצעות המחיר, צריך לשלוח בקשת POST ל-URI של המשאב bidders.filterSets, בפורמט הבא:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSetsאזהרה: אי אפשר לסנן קבוצות מסננים ברמת מגיש הצעות המחיר לפי מזהי קריאייטיב או מזהי עסקאות. אם מציינים את המסננים האלה כשיוצרים קבוצת מסננים ברמת מגיש הצעות המחיר, תתקבל הודעת שגיאה.
שליחת בקשהדוגמה לבקשת POST שיוצרת קבוצת מסננים חדשה ברמת מגיש הצעות המחיר שאינה זמנית:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets
Authorization: Bearer access token here
Content-Type: application/json
{
"name": "bidders/12345678/filterSets/bidder-fs",
"format": "DISPLAY",
"environment": "APP",
"platforms": ["TABLET", "MOBILE"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
אם הבקשה מצליחה, השרת ישיב עם קוד סטטוס 200 OK. גוף התשובה יכלול את המשאב של קבוצת המסננים שנוצרה, שיהיה זהה לקבוצת המסננים שנשלחה בבקשה.
דוגמה ברמת החשבון
כדי ליצור קבוצת מסננים חדשה ברמת החשבון, צריך לשלוח בקשת POST אל
ה-URI של המשאב bidders.accounts.filterSets בפורמט הבא:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSetsהערה: מזהה המשאב שצוין ל-accounts יכול
להיות מספר החשבון של כל חשבון Authorized Buyers שיש לו גישה למגיש הצעות המחיר.
שצוין ב-URI, כולל החשבון של מגיש הצעות המחיר עצמו.
דוגמה לבקשת POST שיוצרת קבוצת מסננים חדשה ברמת החשבון שאינה זמנית:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets
Authorization: Bearer access token here
Content-Type: application/json
{
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"format": "VIDEO",
"environment": "WEB",
"platforms": ["DESKTOP"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
אם הבקשה מצליחה, השרת ישיב עם קוד סטטוס 200 OK. גוף התשובה כוללים את המשאב של קבוצת המסננים שנוצרה, שיהיה זהה לקבוצת המסננים שנשלחה לבקשה.
אחזור של קבוצת מסננים
שיטת get יכולה לקבל קבוצת מסננים רק באותה רמה שבה היא נוצרה. לדוגמה, מגיש הצעות מחיר
החשבון צריך להשתמש ב-bidders.accounts.filterSets.get כדי לאחזר קבוצת מסננים שנוצרה בחשבון
ברמה ולא בשיטה bidders.filterSets.get.
ברמת מגיש הצעות המחיר
כדי לאחזר מסנן ברמת מגיש הצעות המחיר, אפשר לשלוח בקשת HTTP GET ל-URI של המשאב bidders.filterSets, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}לדוגמה:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs
אם הבקשה מצליחה, השרת ישיב עם קוד סטטוס HTTP 200 OK והמסננים שאוחזרו:
{
"name": "bidders/12345678/filterSets/bidder-fs",
"format": "DISPLAY",
"environment": "APP",
"platforms": ["TABLET", "MOBILE"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
ברמת החשבון
כדי לאחזר מסנן ברמת החשבון, אפשר לשלוח בקשת GET מסוג HTTP ל-URI של המשאב bidders.accounts.filterSets, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}לדוגמה:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs
אם הבקשה מצליחה, השרת ישיב עם קוד סטטוס HTTP 200 OK והמסננים שאוחזרו:
{
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"format": "VIDEO",
"environment": "WEB",
"platforms": ["DESKTOP"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
קבוצות מסננים של רשימות
שיטת הרשימה תחזיר רק קבוצות מסננים שניתן לגשת אליהן מהרמה שהוגדרה לה.
לדוגמה, חשבון של מגיש הצעות מחיר לא יראה קבוצות מסננים שנוצרו עבורו באמצעות
bidders.accounts.filterSets.create כשמתקשרים אל bidders.filterSets.list.
ברמת מגיש הצעות המחיר
אפשר לאחזר את כל קבוצות המסננים ברמת מגיש הצעות המחיר למגיש הצעות מחיר נתון על ידי שליחת קוד HTTP GET.
בקשה ל-URI של המשאב bidders.filtersets, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSetsדוגמה להצגת כל קבוצות המסננים ברמת מגיש הצעות המחיר שמזהה החשבון שלו הוא 12345678:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets
{
"filterSets": [{
"filterSetId": "99994",
"name": "bidders/12345678/filterSets/test-b-1",
"relativeDateRange": {
"durationDays": 30
}
},
{
"realtimeTimeRange": {
"startTimeStamp": "2017-11-15T12:30:30.072831583Z"
},
"filterSetId": "99995",
"name": "bidders/12345678/filterSets/test-b-2",
"timeSeriesGranularity": "HOURLY"
},
{
"absoluteDateRange": {
"endDate": {
"day": 12,
"month": 3,
"year": 2017
},
"startDate": {
"day": 26,
"month": 11,
"year": 2017
}
},
"filterSetId": "99996",
"name": "bidders/12345678/filterSets/bidder-fs",
"timeSeriesGranularity": "DAILY",
"platforms": ["TABLET", "MOBILE"],
"environment": "APP",
"format": "DISPLAY"
}
]
}
ברמת החשבון
אפשר לאחזר את כל קבוצות המסננים ברמת החשבון לחשבון נתון על ידי שליחת קוד השגיאה GET ב-HTTP
בקשה ל-URI של המשאב bidders.accounts.filtersets, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSetsהנה דוגמה שבה מפורטות כל קבוצות המסננים ברמת החשבון לחשבון צאצא שמספר החשבון שלו הוא 87654321:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets
{
"filterSets": [{
"realtimeTimeRange": {
"startTimeStamp": "2017-11-19T04:24:43.252893487Z"
},
"filterSetId": "99997",
"name": "bidders/12345678/accounts/87654321/filterSets/test-a-1",
"timeSeriesGranularity": "DAILY"
},
{
"absoluteDateRange": {
"endDate": {
"day": 3,
"month": 12,
"year": 2017
},
"startDate": {
"day": 26,
"month": 11,
"year": 2017
}
},
"filterSetId": "99998",
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"timeSeriesGranularity": "DAILY",
"platforms": ["DESKTOP"],
"environment": "WEB",
"format": "VIDEO"
}
]
}
מחיקה של קבוצת מסננים
אפשר להשתמש בשיטה delete כדי להסיר קבוצות מסננים לא זמניות שלא מכילות
לזמן ממושך יותר. הוא יכול להסיר קבוצות מסננים שניתן לגשת אליהן רק מהרמה שבה היא נקראת.
לדוגמה, חשבון מגיש הצעות מחיר לא יכול למחוק קבוצת מסננים שנוצרה עם bidders.accounts.filterSets.create
עם bidders.filterSets.delete.
ברמת מגיש הצעות המחיר
אפשר למחוק קבוצת מסננים ברמת מגיש הצעות המחיר לחשבון נתון על ידי שליחת בקשת DELETE מסוג HTTP
ל-URI של המשאב bidders.filtersets, בפורמט הבא:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}דוגמה למחיקה של קבוצת מסננים ברמת מגיש הצעות המחיר:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2
אם הביצוע יהיה תקין, גוף הבקשה יהיה ריק. לא תהיה יותר גישה לקבוצת המסננים שצוינה.
ברמת החשבון
אפשר למחוק קבוצת מסננים ברמת החשבון לחשבון נתון על ידי שליחת קוד HTTP DELETE
בקשה ל-URI של המשאב bidders.accounts.filtersets, בפורמט הבא:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}דוגמה למחיקה של קבוצת מסננים ברמת החשבון:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1
אם הביצוע יהיה תקין, גוף הבקשה יהיה ריק. לא תהיה יותר גישה לקבוצת המסננים שצוינה.
אחזור מדדים לפתרון בעיות ב-RTB
כל המשאבים לפתרון בעיות ב-RTB שמשמשים לקבלת מדדים פועלים באופן דומה – יש להם
שיטה אחת לרישום מדדים עבור קבוצת המסננים שצוינה דרך נתיב filterSetName
הפרמטר. קבוצת המסננים שצוינה תקבע אילו מסננים והגדרות יחולו כאשר
להריץ שאילתות על המדדים. קריאה למשאבים האלה ברמת מגיש הצעות המחיר תחזיר מדדים נצברים
מהחשבון של מגיש הצעות המחיר ומכל חשבונות הצאצא שמשויכים אליו, ואילו שיחה ברמת החשבון
יחזירו מדדים של חשבון פרטי בלבד.
ערכים של הצעות מחיר
המשאב bidMetrics משמש לאחזור מדדים שנמדדים
מספר הצעות המחיר. לדוגמה, ניתן להשתמש כך כדי לקבוע את המספר הכולל של הצעות מחיר על פני
בטווח זמן נתון, וכמה מתוכם לא סוננו מהמכרז, זכו בחשיפה,
וכו'. כמו בכל שאר המשאבים לפתרון בעיות ב-RTB שמשמשים לאיסוף מדדים, יש בו רק שיטת list.
הצגת רשימה של מדדי הצעות מחיר ברמת מגיש הצעות המחיר
אפשר להציג רשימה של מדדי הצעות מחיר ברמת מגיש הצעות המחיר לפי קבוצת מסנן נתונה. לשם כך, צריך לשלוח HTTP GET
בקשה ל-URI של המשאב bidders.filtersets.bidMetrics, בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetricsלפניכם דוגמה לפירוט מדדי הצעות מחיר ברמת מגיש הצעות המחיר:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetrics
אם הבקשה מצליחה, השרת מגיב עם קוד סטטוס 200 OK וגוף שמכיל שורות של מדדים עבור המאפיינים ורמת הפירוט שצוינו.
{
"bidMetricsRows": [{
"bids": {
"value": "6160"
},
"bidsInAuction": {
"value": "5698"
},
"billedImpressions": {
"value": "1196"
},
"impressionsWon": {
"value": "2920"
},
"measurableImpressions": {
"value": "1160"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-11-29T08:00:00Z",
"startTime": "2017-11-28T08:00:00Z"
}
},
"viewableImpressions": {
"value": "683"
}
},
{
"bids": {
"value": "104288"
},
"bidsInAuction": {
"value": "94016"
},
"billedImpressions": {
"value": "99"
},
"impressionsWon": {
"value": "125"
},
"measurableImpressions": {
"value": "94"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-11-30T08:00:00Z",
"startTime": "2017-11-29T08:00:00Z"
}
},
"viewableImpressions": {
"value": "87"
}
},
{
"bids": {
"value": "3999"
},
"bidsInAuction": {
"value": "3631"
},
"billedImpressions": {
"value": "618"
},
"impressionsWon": {
"value": "1819"
},
"measurableImpressions": {
"value": "604"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-01T08:00:00Z",
"startTime": "2017-11-30T08:00:00Z"
}
},
"viewableImpressions": {
"value": "369"
}
},
{
"bids": {
"value": "15"
},
"bidsInAuction": {
"value": "3"
},
"billedImpressions": {},
"impressionsWon": {
"value": "3"
},
"measurableImpressions": {},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-02T08:00:00Z",
"startTime": "2017-12-01T08:00:00Z"
}
},
"viewableImpressions": {}
}
]
}
הערה: שדות שמוגדרים ל-0 עבור מדד נתון לא יופיעו בתשובה.
המדדים הריקים billedImpressions ו-measurableImpressions שלמעלה
לציין שגם הערך וגם השונות של הערכים האלה מוגדרים ל-0.
אזהרה: לגבי פירוט הנתונים בתשובה, התשובה לא תכלול
אפשר לכלול שורות אם הן לא מכילות לפחות מדד אחד שאינו אפס. לדוגמה, כאשר
ציינת timeSeriesGranularity, התגובה לא תכלול שורות
timeInterval בטווח הזמן שצוין בקבוצת המסננים, שבו כל המדדים הם אפס.
הצגת רשימה של מדדי הצעות מחיר ברמת החשבון
ניתן לרשום את מדדי הצעות המחיר ברמת החשבון לפי קבוצת מסננים נתונה על ידי שליחת קוד HTTP GET
ל-URI של המשאב bidders.accounts.filtersets.bidMetrics, שכולל את
בפורמט הבא:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetricsהנה דוגמה לפירוט ערכים של הצעות מחיר ברמת החשבון:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetrics
אם הבקשה מצליחה, השרת מגיב עם קוד סטטוס 200 OK וגוף שמכיל שורות של מדדים עבור המאפיינים ורמת הפירוט שצוינו.
{
"bidMetricsRows": [{
"bids": {
"value": "1748"
},
"bidsInAuction": {
"value": "1421"
},
"billedImpressions": {
"value": "301"
},
"impressionsWon": {
"value": "915"
},
"measurableImpressions": {
"value": "298"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-01T08:00:00Z",
"startTime": "2017-11-30T08:00:00Z"
}
},
"viewableImpressions": {
"value": "172"
}
},
{
"bids": {
"value": "6"
},
"bidsInAuction": {
"value": "2"
},
"billedImpressions": {},
"impressionsWon": {
"value": "1"
},
"measurableImpressions": {},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-02T08:00:00Z",
"startTime": "2017-12-01T08:00:00Z"
}
},
"viewableImpressions": {}
}
]
}
הערה: שדות שמוגדרים ל-0 עבור מדד נתון לא יופיעו בתשובה.
הערכים billedImpressions ו-measurableImpressions ריקים למעלה מציינים
שגם הערך וגם השונות של הערכים האלה מוגדרים ל-0.
אזהרה: התשובה לא תכלול פירוט נתונים כלשהו בתשובה
שורות, אם הן לא מכילות לפחות מדד אחד שאינו אפס. לדוגמה, כאשר
ציינת timeSeriesGranularity, התגובה לא תכלול שורות
timeInterval בטווח הזמן שצוין בקבוצת המסננים, שבו כל המדדים הם אפס.