יצירת תגובה

אחרי שהאפליקציה מעבדת את בקשת הצעת המחיר מ-Google, היא צריכה ליצור ולשלוח תגובה. במדריך הזה מוסבר איך לכתוב את הקוד של האפליקציה כדי ליצור את התגובה.

יצירת הודעה מסוג BidResponse

כדי לשלוח הצעת מחיר, אפליקציית הבידינג צריכה להגיב לבקשה להצעת מחיר עם BidResponse שמכיל Bid בפורמט שהגדרתם. אם משתמשים בפורמט JSON, התגובה צריכה להגדיר את הכותרת Content-Type לערך application/json; charset=utf-8 ולכלול את ה-JSON BidResponse בגוף התגובה. אם אתם משתמשים בפורמט Protobuf, האפליקציה צריכה להגדיר את הכותרת Content-Type לערך application/octet-stream ולכלול את ה-BidResponse שסודר בגוף.

כדי ליצור סריאליזציה של BidResponse בפורמט Protobuf, צריך ליצור ולהשתמש בספריות Protobuf שמבוססות על openrtb.proto ועל openrtb-adx.proto, שמטמיעות את השדות הרגילים של OpenRTB BidResponse ואת התוספים של Google ב-Protobuf, בהתאמה. אפשר למצוא אותם בפרוטוקולים ונתוני עזר.

אם אתם לא רוצים להגיש הצעת מחיר על חשיפה, אתם צריכים להחזיר תגובה ריקה מסוג HTTP 204. האפליקציה חייבת להחזיר תגובה לכל BidRequest. פסק זמן ותשובות שלא ניתן לנתח נחשבים לשגיאות, ו-Google מגבילה את מספר הבקשות של מגישי הצעות מחיר עם שיעורי שגיאה גבוהים.

מזהה הקריאייטיב

בBidResponse מצוין קריאייטיב באמצעות השדה BidResponse.seatbid.bid.crid (מגבלה של 128 בייט). גם אם מדובר בנכסי קריאייטיב דומים, צריך להזין ערכים ייחודיים בשדה הזה אם יש הבדלים משמעותיים בין נכסי הקריאייטיב, כולל, בין היתר: גודל, כתובת URL מוצהרת, מאפייני קריאייטיב וסוגי ספקים. במילים אחרות, אתם צריכים להקצות מזהים שונים של קריאייטיב לכל שתי מודעות:

• נראים או מתנהגים בצורה שונה.
• רינדור לתמונות שונות.
• הצגה באמצעים שונים (לדוגמה, מודעה אחת מורכבת מתמונה ומודעה אחרת היא סרטון).

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

מאפייני מודעה

‫Google ממליצה להצהיר על מאפייני קריאייטיב כדי לתאר את המאפיינים של המודעה ואת הטירגוט שלה באמצעות שילוב של BidResponse.seatbid.bid.apis ו-BidResponse.seatbid.bid.attr, או באמצעות התוסף BidResponse.seatbid.bid.ext.attribute. בהמשך מוסבר איך אפשר להצהיר על מאפיינים:

• VPAID
  מגדירים את BidResponse.seatbid.bid.apis לערך VPAID_1 או VPAID_2. בפורמט JSON, אפשר להגדיר את הערך הזה ל-1 או ל-2, בהתאמה.
• MRAID
  מגדירים את BidResponse.seatbid.bid.apis ל-MRAID_1 או ל-3 לפורמט JSON.
• SIZELESS
  מגדירים את BidResponse.seatbid.bid.attr ל-RESPONSIVE או ל-18 לפורמט JSON.
• PLAYABLE
  כדי לציין את זה, מגדירים את BidResponse.seatbid.bid.attr לערך USER_INTERACTIVE או 13 בפורמט JSON.

במשאב בנושא קריאייטיב מוסבר איך לקבל משוב על המאפיינים שזוהו בקריאייטיב.

שדות Open Bidding

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

המלצות

• מפעילים בשרתים חיבורי HTTPS מתמשכים (שנקראים גם keep-alive או שימוש חוזר בחיבור). מגדירים את הזמן הקצוב לתפוגה ל-10 שניות לפחות. במקרים רבים, ערכים גבוהים יותר מועילים. ‫Google מאמתת את זה במהלך בדיקות ההשהיה הראשוניות של האפליקציה, כי Authorized Buyers שולח בקשות בקצב גבוה וצריך להימנע מהשהיה שנובעת מהקמת חיבור TCP נפרד לכל בקשה.

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

• חשוב לוודא שקוד הבידינג לא תלוי בשדות שהוצאו משימוש, כי זה עלול לגרום לכך שהצעות המחיר ייכשלו עם שגיאות.
• כוללים את BidResponse.seatbid.bid.w ואת BidResponse.seatbid.bid.h ב-BidResponse. תגובה BidResponse לבקשה שכוללת כמה גדלים של מודעות צריכה לכלול את השדות האלה, אחרת היא תיפסל במכרז.
• הגודל של התשובה צריך להיות פחות מ-8K. תשובות גדולות מאוד עלולות להגדיל את זמן האחזור ברשת ולגרום לפסק זמן.
• פועלים לפי ההנחיות בנושא הצעות מחיר למלאי שטחי פרסום ב-iOS שנדרש להם שיוך ב-SKAdNetwork.

דוגמה לתגובה לבקשה להצעת מחיר

בדוגמאות הבאות מוצגות דוגמאות קריאות של בקשות Protobuf ו-JSON.

id: "Z40x0v53721142nd3J1E07"
seatbid {
  bid {
    id: "25lvG8gXKV0GEcaQE67"
    impid: "1"
    price: 0.01176087612355106
    adm: "<iframe marginwidth=0 marginheight=0 height=600 frameborder=0 width=160 scrolling=no src=\"https://test.com/ads?id=123456&curl=%%CLICK_URL_ESC%%&wprice=%%WINNING_PRICE_ESC%%\"></iframe>"
    adomain: "google.com"
    crid: "test_creative_id_656889"
    w: 395
    h: 62
    burl: "https://test.com/imp?id=123456"
    [com.google.doubleclick.bid] {
      exchange_deal_type: OPEN_AUCTION
      attribute: 21
      event_notification_token {
        payload: "token"
      }
      billing_id: 40355106859
      clickurl: "google.com"
    }
  }
  seat: "7877:1572:891547"
}
bidid: "A7j5NZRS-vA5H1033-4084-459j7H7Gn614"
[com.google.doubleclick.bid_response] {
  processing_time_ms: 54
}

{
  "id": "Z40x0v53721142nd3J1E07",
  "seatbid": [
    {
      "bid": [
        {
          "id": "25lvG8gXKV0GEcaQE67",
          "impid": "1",
          "price": 0.01176087612355106,
          "adm": "<iframe marginwidth=0 marginheight=0 height=600 frameborder=0 width=160 scrolling=no src=\"https://test.com/ads?id=123456&curl=%%CLICK_URL_ESC%%&wprice=%%WINNING_PRICE_ESC%%\"></iframe>",
          "adomain": [
            "google.com"
          ],
          "crid": "test_creative_id_656889",
          "w": 395,
          "h": 62,
          "burl": "https://test.com/imp?id=123456",
          "ext": {
            "exchange_deal_type": 0,
            "attribute": [
              21
            ],
            "event_notification_token": {
              "payload": "token"
            },
            "billing_id": "40355106859",
            "clickurl": [
              "google.com"
            ]
          }
        }
      ],
      "seat": "7877:1572:891547"
    }
  ],
  "bidid": "A7j5NZRS-vA5H1033-4084-459j7H7Gn614",
  "ext": {
    "processing_time_ms": 54
  }
}

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

אפשר ליצור ולסדר הודעת BidResponse באמצעות קוד C++ הבא:

BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
  // respond to the POST with post_response as the content
} else {
  // return an error to the POST
}

ציון קריאייטיב

תגובת הבידינג מציינת את הקריאייטיב שיוצג אם הבידינג יזכה. הצעת המחיר שלכם צריכה לכלול אחד מהפורמטים הנתמכים של מודעות (AMP, וידאו, מותאמות). בדוגמה הזו, אנחנו מציינים את הקריאייטיב באמצעות השדה html_snippet.

אפשרות אחרת היא לציין את הקריאייטיב באמצעות אחד מהשדות הבאים, בהתאם לפורמט המודעה:

• מודעה שמוצגת באמצעות SDK
  • BidResponse.seatbid.bid.ext.sdk_rendered_ad
• AMP
  • BidResponse.seatbid.bid.amp_ad_url
• סרטון
  • BidResponse.seatbid.bid.adm
• מודעות מותאמות
  • BidResponse.seatbid.bid.adm_native

מציינים מודעה שמארחים בשרתים שלכם באמצעות קטע קוד HTML בשדה BidResponse.seatbid.bid.adm. הקוד של התקציר מוכנס למסגרת iframe שמוטמעת בדף האינטרנט, וכתוצאה מכך המודעה מאוחזרת ומוצגת כשהדף נטען. צריך ליצור את קטע ה-HTML כך שהמודעה (באנר או מעברון) תוצג בצורה תקינה בתוך iFrame, ובגודל מתאים למיקום המודעה שמוגשת עליו הצעת מחיר.

בנוסף, גודל המודעה שמוצהר בתגובה לבקשה להצעת מחיר חייב להתאים בדיוק לאחד משילובי הגדלים בבקשה להצעת מחיר במקרים הבאים:

• מודעה רגילה מסוג באנר (לא מודעת וידאו, לא מודעה מותאמת ולא מודעת מעברון).
• מגיש הצעת המחיר הצהיר על הגודל בתגובה להצעת המחיר. חובה להצהיר על גודל אם בבקשה מופיעים כמה גדלים.
• יש חריג למודעות מעברון. במודעות מעברון, הרוחב צריך להיות לפחות 50% מרוחב המסך והגובה לפחות 40% מגובה המסך.

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

רוב כללי המדיניות לגבי קטעי HTML שמוחזרים בתגובות להצעות מחיר זהים לאלה שחלים על מודעות של צד שלישי. מידע נוסף זמין במאמרים הנחיות לתוכנית Authorized Buyers, דרישות להצגת מודעות של צד שלישי והצהרה על כתובות URL למעקב המרות במודעות.

ציון פקודות מאקרו

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

אפשר לכלול פקודות מאקרו בשדות הבאים:

• BidResponse.seatbid.bid.adm

  יש תמיכה בפקודות מאקרו בקטעי HTML, בפורמטים מקוריים, בכתובות URL של סרטונים ובפורמטים של XML של סרטוני VAST.

• BidResponse.seatbid.bid.adm_native.eventtrackers.url

• BidResponse.seatbid.bid.adm_native.imptrackers

• BidResponse.seatbid.bid.ext.amp_ad_url

  רק פקודות המאקרו WINNING_PRICE ו-WINNING_PRICE_ESC הספציפיות ל-Google נתמכות בנכסי קריאייטיב ב-AMP.

• BidResponse.seatbid.bid.burl

• BidResponse.seatbid.bid.ext.impression_tracking_url

  משתמשים בשיטה הזו במקום בשיטה BidResponse.seatbid.bid.burl אם נדרשת יותר מכתובת URL אחת לחיוב.

לדוגמה, אפשר לכלול פקודת מאקרו כחלק מקטע HTML על ידי הטמעה של ${MACRO} בכתובת ה-URL שמשמשת לאחזור הקריאייטיב, כאשר MACRO היא אחת מפקודות המאקרו הנתמכות שמתוארות במפרט OpenRTB.

פקודות מאקרו של Google

‫Google תומכת בפקודות מאקרו נוספות מעבר לאלה שמופיעות במפרט OpenRTB. הפורמט שלהן שונה, והן יופיעו כ-%%MACRO%% אם הן מוטמעות בכתובת URL. בטבלה הבאה מתוארות פקודות המאקרו האלה:

<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a>

<a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a>

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a>

<a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a>

‫Google דורשת להשתמש בפקודת המאקרו CLICK_URL_UNESC או CLICK_URL_ESC בנכס הקריאייטיב של המודעה שמוצגת על ידי צד שלישי. ‫Google משתמשת בפקודות מאקרו CLICK_URL למעקב אחרי קליקים.

הסכימה הבאה משמשת להסרת תווים מיוחדים מכתובות URL בפקודות מאקרו:

• תו הרווח מוחלף בסימן פלוס (+).
• תווים אלפאנומריים (0-9, ‏ a-z, ‏ A-Z) ותווים מהקבוצה !()*,-./:_~ נשארים ללא שינוי.
• כל שאר התווים מוחלפים ב-%XX, כאשר %XX הוא המספר ההקסדצימלי שמייצג את התו.XX

הגבלות ודרישות לבעלי תוכן דיגיטלי

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

• BidRequest.bcat
  • אתם יכולים להשוות בין הקטגוריות החסומות שצוינו בשדה הזה לבין הקטגוריות שזוהו בנכסי הקריאייטיב ששלחתם באמצעות שדה detectedCategories של Real-time Bidding API.
• BidRequest.imp.ext.allowed_vendor_type
• BidRequest.imp.secure
  • בפועל, הערך הזה תמיד יהיה true כי Google דורשת תמיכה ב-SSL בכל הקריאייטיבים.
• BidRequest.imp.{audio/banner/native/video}
• BidRequest.imp.{audio/banner/native/video}.api
• BidRequest.imp.{audio/banner/native/video}.battr
• BidRequest.imp.{audio/banner/video}.mimes

אל תגישו הצעות מחיר על מודעות שמכילות תכונה מוגבלת. לגבי תכונות מותרות, כמו סוג הספק, מחזירים מודעה רק אם סוג הספק שלה מופיע ברשימה allowed_vendor_type ב-BidRequest. הצעת המחיר שלכם צריכה לכלול רק פורמטים של מודעות שצוינו בבקשת הצעת המחיר על ידי מילוי שדות כמו BidRequest.imp.banner. פרטים נוספים על השדות האלה מופיעים בהערות בהגדרה של BidRequest protocol buffer.

אם מודעה מוחזרת ב-BidResponse, צריך להגדיר בצורה מדויקת את השדות BidResponse.seatbid.bid.attr,‏ BidResponse.seatbid.bid.cat ואת השדה BidResponse.seatbid.bid.adomain או BidResponse.seatbid.bid.adm_native.link.url ב-BidResponse. אם למודעה יש כמה ערכים רלוונטיים בשדות האלה, צריך לכלול את כל הערכים. פרטים נוספים על השדות האלה מופיעים בהערות בBidResponseהגדרת מאגר הפרוטוקולים. תשובות שלא מוגדרים בהן השדות האלה נפסלות.

מדידה פתוחה

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

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

דוגמאות לתגובות לבקשות להצעת מחיר

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

באנר לקידום אפליקציה

id: "1i4fAl37oW6u51H59WmQdF"
seatbid {
  bid {
    id: "F5660t9N52c4972XV8n"
    impid: "1"
    price: 0.037953998893499374
    adm: "<iframe marginwidth=0 marginheight=0 height=600 frameborder=0 width=160 scrolling=no src=\"https://test.com/ads?id=123456&curl=%%CLICK_URL_ESC%%&wprice=%%WINNING_PRICE_ESC%%\"></iframe>"
    adomain: "google.com"
    crid: "test_creative_id_257354"
    w: 390
    h: 60
    burl: "https://test.com/imp?id=123456"
    [com.google.doubleclick.bid] {
      impression_tracking_url: "https://test.com/impression?id=123456"
      billing_id: 61131625086
      app_promotion_type: INSTALLS
    }
  }
  seat: "7091:5573:967460"
}
cur: "USD"
[com.google.doubleclick.bid_response] {
  processing_time_ms: 35
}

{
  "id": "1i4fAl37oW6u51H59WmQdF",
  "seatbid": [
    {
      "bid": [
        {
          "id": "F5660t9N52c4972XV8n",
          "impid": "1",
          "price": 0.037953998893499374,
          "adm": "<iframe marginwidth=0 marginheight=0 height=600 frameborder=0 width=160 scrolling=no src=\"https://test.com/ads?id=123456&curl=%%CLICK_URL_ESC%%&wprice=%%WINNING_PRICE_ESC%%\"></iframe>",
          "adomain": [
            "google.com"
          ],
          "crid": "test_creative_id_257354",
          "w": 390,
          "h": 60,
          "burl": "https://test.com/imp?id=123456",
          "ext": {
            "impression_tracking_url": [
              "https://test.com/impression?id=123456"
            ],
            "billing_id": "61131625086",
            "app_promotion_type": 1
          }
        }
      ],
      "seat": "7091:5573:967460"
    }
  ],
  "cur": "USD",
  "ext": {
    "processing_time_ms": 35
  }
}

מודעת מעברון באפליקציה

id: "dg1TCUK23g082jPm629jR4"
seatbid {
  bid {
    id: "20zw8j0dszO6vCpE92e"
    impid: "1"
    price: 0.058042
    adm: "<iframe marginwidth=0 marginheight=0 height=600 frameborder=0 width=160 scrolling=no src=\"https://test.com/ads?id=123456&curl=%%CLICK_URL_ESC%%&wprice=%%WINNING_PRICE_ESC%%\"></iframe>"
    adomain: "google.com"
    crid: "test_creative_id_372958"
    w: 375
    h: 667
    cattax: GOOGLE_CATEGORIES
    [com.google.doubleclick.bid] {
      impression_tracking_url: "https://test.com/impression?id=123456"
      attribute: 47
      attribute: 50
      billing_id: 20458168637
      skadn {
        version: "4.0"
        network: "jLL135hf"
        itunesitem: "139608598"
        sourceapp: "1457468797"
        fidelities {
          fidelity: STOREKIT_RENDERED_ADS
          nonce: "7a865cdd-b631-4922-bc32-602bb21f6174"
          timestamp: "1779161129271"
          signature: "X0EjfovnY011fF0EV07i2ZonI3vLDkY0t19jN6812iz434D2fh4296m8AB637t1W1K61Uo933l1o6l76Wua644r3034c5284"
        }
        fidelities {
          fidelity: VIEW_THROUGH_ADS
          nonce: "c5dc78b7-e4ad-45c2-96da-f8f5d77c4488"
          timestamp: "1779161129271"
          signature: "RN05E0A663CzUNgI33EK9O1CG19473uvp1b8Lh740keuvhb2vj01e4F7x60L2br3C1rtFczp75E7718O7974i98800o8in61"
        }
        sourceidentifier: "5945"
      }
      app_promotion_type: INSTALLS
      clickurl: "google.com"
    }
  }
}
[com.google.doubleclick.bid_response] {
  processing_time_ms: 26
}

{
  "id": "dg1TCUK23g082jPm629jR4",
  "seatbid": [
    {
      "bid": [
        {
          "id": "20zw8j0dszO6vCpE92e",
          "impid": "1",
          "price": 0.058042,
          "adm": "<iframe marginwidth=0 marginheight=0 height=600 frameborder=0 width=160 scrolling=no src=\"https://test.com/ads?id=123456&curl=%%CLICK_URL_ESC%%&wprice=%%WINNING_PRICE_ESC%%\"></iframe>",
          "adomain": [
            "google.com"
          ],
          "crid": "test_creative_id_372958",
          "w": 375,
          "h": 667,
          "cattax": 500,
          "ext": {
            "impression_tracking_url": [
              "https://test.com/impression?id=123456"
            ],
            "attribute": [
              47,
              50
            ],
            "billing_id": "20458168637",
            "skadn": {
              "version": "4.0",
              "network": "jLL135hf",