הממשק הקודם של Search Ads 360 Reporting API יוצא משימוש ב-30 ביוני 2024. חשוב לדעת ש-Search Ads 360 Conversion API לא מושפע מכך, ונמשיך לתמוך בו. בכל פיתוח הדוחות החדש יש להשתמש ב-Search Ads 360 Reporting API החדש.

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

מומלץ מאוד להעביר את כל ההטמעות הקיימות של Search Ads 360 ל-API החדש. מידע נוסף זמין במדריך לתחילת העבודה ובמדריך להעברת נתונים של Search Ads 360 Reporting API.

דף זה תורגם על ידי Cloud Translation API.

הוספת המרות חדשות

קוראים לConversion.insert(). כדי להוסיף המרה אחת או יותר. כדי לשייך את ההמרה בצורה נכונה, הבקשה צריך לציין את השם של פעילות ב-Floodlight שהמפרסם משתמש בה לדיווח המרות אופליין, יחד עם המזהה של מילת המפתח, המודעה, ואולי גם הקליק שהוביל להמרה. עבור למידע על השגת מזהים של Search Ads 360, אפשר לעיין במאמר מזהים של Search Ads 360 המרות.

מידע על ההגבלות על העלאת המרות היסטוריות זמין בקטע מרכז העזרה של Search Ads 360

אם בבקשת Conversion.insert() צוינו מספר המרות, מערכת Search Ads 360 מנסה להעלות כל המרה בשיטה הטובה ביותר, במקום להעלות את כל הקבצים כעסקה של 'הכול או כלום'. אם חלק מההמרות העלאת כל הקבצים נכשלה, אחרים עדיין עשויים להעלות בהצלחה. העלאות של המרות עלולות להיכשל בגלל בקשה לא תקינה או כשלים זמניים ברשת או במערכת. לכן אנחנו מומלץ לקרוא את התגובה לגבי כל המרה שהוכנסה אל צריך לוודא שההעלאה בוצעה בהצלחה.

תוך כמה זמן אפשר להשתמש בנתונים שהועלו?

אם מציינים conversionTimestamp מהיום או אתמול, מדדים של ההמרה תופיע בממשק המשתמש של Search Ads 360 תוך שעה ממועד ההעלאה. אם לציין conversionTimestamp מלפני יותר מאתמול, המדדים יעודכנו כמה שעות.

ממירים את כל חותמות הזמן של ההמרות לתקופה של זמן מערכת (שנקרא גם 'זמן יוניקס').

אפשר ליצור פעילויות Floodlight מה-API?

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

מומלץ אחרי שמשתמשים ב-API כדי ליצור Floodlight פעילות, משתמש ב-Search Ads 360 נכנס ל-Search Ads 360 ומשנה את הפעילות לציין שהמקור הראשי של המרות היא פעילות אופליין.

שיטות מומלצות להוספת המרות

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

אפשר לבקש ממשתמש ב-Search Ads 360 להיכנס ל-Search Ads 360 ולשנות את ההגדרות עבור כל פעילות ב-Floodlight שבה אתם משתמשים לדיווח על המרות אופליין. ההגדרות צריכות לציין שהמקור העיקרי של ההמרות הוא פעילות אופליין. לצפייה מרכז העזרה של Search Ads 360 לקבלת הוראות.
מעלים המרות ברגע שהן זמינות. אם אתה שיוך המרות לביקורים ספציפיים, צריך להמתין לפחות 30 דקות אחרי הביקור לפני שמעלים את ההמרה. ייתכן שמערכת Search Ads 360 לא תזהה את מזהה הקליק של הביקור אם מעלים את הקובץ פחות מ-30 דקות אחרי הביקור. במקרים נדירים, ייתכן שתצטרכו ממתינים עד 4 שעות לפני שמערכת Search Ads 360 תזהה את מספר הקליק.

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

חותמת הזמן של הזמינות צריכה להיות אחת מהאפשרויות הבאות:
- אם תיעדתם המרות במהלך 24 השעות האחרונות אבל לא העליתם אותן עדיין, חותמת הזמן צריכה להיות הזמן שבו ההמרה האחרונה שהועלתה שהתרחש. כך מערכת Search Ads 360 מודיעה שייתכן שהתרחשו המרות במהלך 24 השעות האחרונות, אבל עדיין לא סיפקת את הנתונים. שיטות בידינג מערכות אוטומטיות אחרות יתייחסו להיסטוריית הביצועים עד לתאריך להמרה שהעלית.
- אם לא התרחשו המרות במהלך 24 השעות האחרונות, חותמת הזמן צריכה להיות התאריך והשעה הנוכחיים. כך מערכת Search Ads 360 אומרת שלא המרות התרחשו במהלך 24 השעות האחרונות. שיטות בידינג ואוטומציה אחרת המערכות יכללו את 24 השעות האחרונות – יום שלם ללא המרות – וכן חלק מהיסטוריית הביצועים.

שליחה של בקשת הוספה

אתם יכולים לשלוח בקשה של Conversion.insert() לבצע כל אחת מהפעולות הבאות:

שיוך המרה לביקור ספציפי
שיוך המרה למילת מפתח בלבד

שדות החובה בבקשת Conversion.insert() תלויים ב- האירוע או הפריט שאליהם משייכים את ההמרה. בקטעים הבאים מפורטות הדרישות ושדות אופציונליים לכל אירוע או פריט שאפשר לשייך אליו המרה.

שיוך המרה לביקור ספציפי

כשלקוח לוחץ על מודעה אחת או יותר ומגיע לאתר של מפרסם, מערכת Search Ads 360 מתייחסת לסשן של משתמש באתר של המפרסם כביקור. כדי לשייך המרה לביקור, צריך לציין את הפרטים הבאים בConversion.insert() בקשה:

שדות חובה

clickId: מזהה קליק של הביקור תלוי אותיות רישיות. אני רוצה לראות ביומני האינטרנט של המפרסם עבור מספר הקליק או הצגת ההמרות ברשימה, והם כוללים מספר קליק מהמרה אחרת. מערכת Search Ads 360 תשייך את ההמרה אל מילת המפתח, המודעה ואובייקטים אחרים ב-Search Ads 360 שהיו אחראים יצירת הביקור.
ממתינים לפחות 30 דקות אחרי מערכת Search Ads 360 יוצרת מספר קליק כדי להעלות המרות. אם מתקבלת ההודעה "מזהה הקליק לא נמצא" שגיאה, להמתין 4 שעות ואז להעלות את המרות שוב. יש להעלות את כל ההמרות בתוך 90 יום מהתאריך שבו נוצר מזהה קליק. אחרת, ייתכן ש-Search Ads 360 API לא יזהה את הביקור.
conversionId: כשמדובר בהמרות אופליין, המפרסמים מספקים את המזהה הזה. המפרסמים יכולים לציין כל מזהה שיש לו משמעות. לכל המרה בבקשה צריך לציין מזהה ייחודי, והשילוב של המזהה וחותמת הזמן חייב להיות ייחודי מבין כל ההמרות אצל המפרסם. כשמשתמשים בהמרות אונליין, מערכת Search Ads 360 מעתיקה את dsConversionId או את floodlightOrderId בנכס הזה, בהתאם להוראות לדיווח על פעילות מ-Floodlight של המפרסם.
conversionTimestamp: מציין את התאריך והשעה שבהם התרחשה המרה. לדוגמה, אם ההמרה מתרחשת ביום שישי, 05 באוגוסט 2016 11:53:22 שעון קיץ, החוף המזרחי (GMT -4:00), לציין את חותמת הזמן בפרק זמן של אלפיות שנייה: 1470412402000.
segmentationType: מציין את סוג מערכת ההמרות שאתם מעלים את ההמרה אל. בשלב הזה יש תמיכה רק בהמרות של Floodlight, לכן השדה הזה תמיד צריך לציין את הערך FLOODLIGHT.
segmentationName: שם הפעילות ב-Floodlight שהמפרסם מייצג שמשמש לדיווח על ההמרה.
אם המפרסם שלכם מכיל פעילויות עם אותו שם (זה יכול לקרות אם הפעילויות שייכים לקבוצות שונות ב-Floodlight), הפעולה המומלצת היא לשנות את השם של אחת הפעילויות.

לחלופין, אם אתם יודעים שהמזהה של Search Ads 360 הקצה לפעילות ב-Floodlight, אפשר לציין את המזהה ב-segmentationId במקום לציין את השם השדה segmentationName. (Campaign Manager גם מקצה מזהה לפעילות ב-Floodlight, אבל מזהה Campaign Manager שונה מהמזהה של Search Ads 360 ולא ניתן להשתמש בו כדי לשייך conversions.) כדי לראות את מזהה Search Ads 360 של פעילות ב-Floodlight, צריך להוריד קובץ המרות (מ ממשק המשתמש של Search Ads 360 או הדוחות API). אם לפחות המרה אחת שויכה לפעילות Floodlight במהלך מסגרת הזמן, יופיע בדוח מזהה Search Ads 360.
type: סוג ההמרה, כלומר ACTION או TRANSACTION. להמרה מסוג ACTION אין ערך כספי, בעוד ההמרה לעסקה כן מתבצעת. דוגמאות: הרשמות לרשימות של כתובות אימייל (ACTION) לעומת רכישות במסחר אלקטרוני (עסקה).
אם מציינים TRANSACTION, צריך גם לציין את השדה הבא:
- revenueMicros: השווי הכספי של ההמרה.

שדות אופציונליים

quantityMillis: מספר הפריטים בהמרה הזו. לדוגמה, מספר האנשים שנרשמו לניוזלטר באימייל או את סך כל הפריטים שנמכרו. אם לא מציינים את השדה הזה להמרות מסוג ACTION, מערכת Search Ads 360 מוסיפה באופן אוטומטי של 1000.
currencyCode: המטבע של ההכנסה מעסקה. כברירת מחדל, ההכנסה היא כאילו הם במטבע של המפרסם. אם מציינים מטבע אחר, מערכת Search Ads 360 ממירה את סכום ההכנסה שצוין למטבע של המפרסם. מידע נוסף
צריך להשתמש באותיות אלפביתיות לפי תקן ISO 4217 (3 תווים) [פורמט] כדי לציין את המטבע.
רלוונטי רק להמרות מסוג TRANSACTION.
customMetric ו-customDimension: מעלה נתונים נוספים לגבי המרות, כמו המדינה שאליה נשלח פריט שנרכש, מזהי מוצרים או אפילו משך שיחת טלפון. מידע נוסף על העלאת נתונים בשביל משתנים של Floodlight.
deviceType: מציין את סוג המכשיר שבו התרחשה ההמרה. צפייה רשימת הערכים הקבילים השדה הזה.

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "revenueMicros": "10000000", // 10 million revenueMicros is equivalent to $10 of revenue
    "currencyCode": "USD"
  }]
}

כדי לשלוח את הבקשה, צריך להשתמש בסקריפט של כלי השירות של Search Ads 360

כדי לשלוח בקשת JSON POST גולמית, אפשר להשתמש ב-sa360Api.py סקריפט באופן הבא:

מעתיקים את אובייקט ה-JSON לדוגמה (כל מה שמופיע בין השניים, כולל סוגריים מסולסלים) בקובץ טקסט חדש בשם request.txt.
משנים את מזהה הסוכנות שמופיע בקוד ה-JSON למזהה הסוכנות שלכם.
מסירים תגובות, למשל // The date column segments the report by individual days.
מרכיבים את פרטי הכניסה של OAuth 2.0 במחרוזת אחת שמופרדת בפסיקים עוקב:
client-ID,client-secret,refresh-token
(זו אותה המחרוזת ש-sa360Api.py יוצרת כשמריצים את sa360Api.py --login, כפי שמתואר בהגדרה הרשאה).
מפעילים את sa360Api.py באופן הבא:
sa360Api.py --cred CREDENTIALS --server API-method --post < request.txt
בפקודה שלמעלה, מחליפים ב-CREDENTIALS את המחרוזת שהרכבתם בשלב הקודם.
מחליפים את השם של שיטת ה-POST בתיבה שלמטה בשדה API-method.
לדוגמה:
sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --post < request.txt

Java

  /**
   * Instantiate the Doubleclicksearch service, create conversions, and upload them.
   */
  public static void main(String[] args) throws Exception {

    Doubleclicksearch service = getService(); // See Set Up Your Application.

    // Set up a List to keep track of each conversion you create.
    List<Conversion> conversions = new Vector<Conversion>();

    // Add a conversion to the List.
    addTransactionConversionForVisit(conversions, "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
        "test_" + System.currentTimeMillis(), 10000000L, 1378710000000L);

    // Upload the List and handle the response.
    uploadConversions(conversions, service);
  }


  /**
   * Create a TRANSACTION conversion and add it to a List<Conversion>. This sample hard-codes
   * the segmentation name and currency. You probably wouldn't want your production code to be so brittle.
   */
  private static List<Conversion> addTransactionConversionForVisit(List<Conversion> conversions,
      String clickId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion().setClickId(clickId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }


  /**
   * Convert the List of conversions to a DS ConversionList, send an insert request to DS,
   * and output the response to a file.
   */
  private static void uploadConversions(List<Conversion> conversions, Doubleclicksearch service)
      throws IOException {

    FileOutputStream outputStream =
        new FileOutputStream(new File("./", "InsertConversionsResponse.txt"));
    final PrintStream printStream = new PrintStream(outputStream);

    try {
      // Convert the List to a ConversionList.
      ConversionList conversionList = new ConversionList().setConversion(conversions);

      // Insert an upload request and download the response to a file.
      service.conversion().insert(conversionList).executeAndDownloadTo(printStream);
      printStream.close();
    } catch (GoogleJsonResponseException e) {
      System.err.println("Get request was rejected.");
      for (ErrorInfo error : e.getDetails().getErrors()) {
        System.err.println(error.getMessage());
      }
      System.exit(e.getStatusCode());
    }
  }

Python

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a visit.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with a click ID from your site
              'conversionId': 'test_20140206_00',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '10000000', // 10 million revenueMicros is equivalent to $10 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

שיוך המרה למילת מפתח בלבד

אם המטרה העיקרית שלכם היא לשייך המרות למילות מפתח, לא צריך לשייך אותן למודעות – אפשר להשמיט את רוב השטח של Search Ads 360 ולציין רק את המזהה של מילת המפתח, ביחד עם כמה שדות אחרים:

שדות חובה

criterionId: זהו המזהה של מילת המפתח. כדי לקבל את criterionId צריך להוסיף את TrackerId במאקרו לכתובות דפי הנחיתה שלכם. למידע על השגת מזהים של מילות מפתח, ניתן לעיין במאמר מזהים של Search Ads 360 וכן המרות.
conversionId: כשמדובר בהמרות אופליין, המפרסמים מספקים את המזהה הזה. המפרסמים יכולים לציין כל מזהה שיש לו משמעות. לכל המרה בבקשה צריך לציין מזהה ייחודי, והשילוב של המזהה וחותמת הזמן חייב להיות ייחודי מבין כל ההמרות אצל המפרסם. כשמשתמשים בהמרות אונליין, מערכת Search Ads 360 מעתיקה את dsConversionId או את floodlightOrderId בנכס הזה, בהתאם להוראות לדיווח על פעילות מ-Floodlight של המפרסם.
conversionTimestamp: מציין את התאריך והשעה שבהם התרחשה המרה. לדוגמה, אם ההמרה מתרחשת ביום שישי, 05 באוגוסט 2016 11:53:22 שעון קיץ, החוף המזרחי (GMT -4:00), לציין את חותמת הזמן בפרק זמן של אלפיות שנייה: 1470412402000.
segmentationType: מציין את סוג מערכת ההמרות שאתם מעלים את ההמרה אל. בשלב הזה יש תמיכה רק בהמרות של Floodlight, לכן השדה הזה תמיד צריך לציין את הערך FLOODLIGHT.
segmentationName: שם הפעילות ב-Floodlight שהמפרסם מייצג שמשמש לדיווח על ההמרה.
אם המפרסם שלכם מכיל פעילויות עם אותו שם (זה יכול לקרות אם הפעילויות שייכים לקבוצות שונות ב-Floodlight), הפעולה המומלצת היא לשנות את השם של אחת הפעילויות.

לחלופין, אם אתם יודעים שהמזהה של Search Ads 360 הקצה לפעילות ב-Floodlight, אפשר לציין את המזהה ב-segmentationId במקום לציין את השם השדה segmentationName. (Campaign Manager גם מקצה מזהה לפעילות ב-Floodlight, אבל מזהה Campaign Manager שונה מהמזהה של Search Ads 360 ולא ניתן להשתמש בו כדי לשייך conversions.) כדי לראות את מזהה Search Ads 360 של פעילות ב-Floodlight, צריך להוריד קובץ המרות (מ ממשק המשתמש של Search Ads 360 או הדוחות API). אם לפחות המרה אחת שויכה לפעילות Floodlight במהלך מסגרת הזמן, יופיע בדוח מזהה Search Ads 360.
type: סוג ההמרה, כלומר ACTION או TRANSACTION. להמרה מסוג ACTION אין ערך כספי, בעוד ההמרה לעסקה כן מתבצעת. דוגמאות: הרשמות לרשימות של כתובות אימייל (ACTION) לעומת רכישות במסחר אלקטרוני (עסקה).
אם מציינים TRANSACTION, צריך גם לציין את השדה הבא:
- revenueMicros: השווי הכספי של ההמרה.

שדות אופציונליים

quantityMillis: מספר הפריטים בהמרה הזו. לדוגמה, מספר האנשים שנרשמו לניוזלטר באימייל או את סך כל הפריטים שנמכרו. אם לא מציינים את השדה הזה להמרות מסוג ACTION, מערכת Search Ads 360 מוסיפה באופן אוטומטי של 1000.
currencyCode: המטבע של ההכנסה מעסקה. כברירת מחדל, ההכנסה היא כאילו הם במטבע של המפרסם. אם מציינים מטבע אחר, מערכת Search Ads 360 ממירה את סכום ההכנסה שצוין למטבע של המפרסם. מידע נוסף
צריך להשתמש באותיות אלפביתיות לפי תקן ISO 4217 (3 תווים) [פורמט] כדי לציין את המטבע.
רלוונטי רק להמרות מסוג TRANSACTION.
customMetric ו-customDimension: מעלה נתונים נוספים לגבי המרות, כמו המדינה שאליה נשלח פריט שנרכש, מזהי מוצרים או אפילו משך שיחת טלפון. מידע נוסף על העלאת נתונים בשביל משתנים של Floodlight.
deviceType: מציין את סוג המכשיר שבו התרחשה ההמרה. צפייה רשימת הערכים הקבילים השדה הזה.

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "criterionId": "43700003491981017", // Replace with your ID
    "conversionId": "customerTransaction73126",
    "conversionTimestamp": "1351196386000",
    "segmentationType": "FLOODLIGHT",
    "segmentationName": "Offline Purchase",
    "type": "TRANSACTION",
    "revenueMicros": "20000000", // 20 million revenueMicros is equivalent to $20 of revenue
    "currencyCode": "USD"
  }]
}

כדי לשלוח את הבקשה, צריך להשתמש בסקריפט של כלי השירות של Search Ads 360

כדי לשלוח בקשת JSON POST גולמית, אפשר להשתמש ב-sa360Api.py סקריפט באופן הבא:

מעתיקים את אובייקט ה-JSON לדוגמה (כל מה שמופיע בין השניים, כולל סוגריים מסולסלים) בקובץ טקסט חדש בשם request.txt.
משנים את מזהה הסוכנות שמופיע בקוד ה-JSON למזהה הסוכנות שלכם.
מסירים תגובות, למשל // The date column segments the report by individual days.
מרכיבים את פרטי הכניסה של OAuth 2.0 במחרוזת אחת שמופרדת בפסיקים עוקב:
client-ID,client-secret,refresh-token
(זו אותה המחרוזת ש-sa360Api.py יוצרת כשמריצים את sa360Api.py --login, כפי שמתואר בהגדרה הרשאה).
מפעילים את sa360Api.py באופן הבא:
sa360Api.py --cred CREDENTIALS --server API-method --post < request.txt
בפקודה שלמעלה, מחליפים ב-CREDENTIALS את המחרוזת שהרכבתם בשלב הקודם.
מחליפים את השם של שיטת ה-POST בתיבה שלמטה בשדה API-method.
לדוגמה:
sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --post < request.txt

Java

  /**
   * Creates a TRANSACTION conversion, attributes it to a keyword only, and adds it to a List<Conversion>.
   * The example in the preceding section contains the uploadConversions method,
   * which can submit the list as an insert() request.
   */
  private static List<Conversion> addTransactionConversionForKeyword(List<Conversion> conversions,
      Long criterionId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion()
        .setCriterionId(criterionId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }

Python

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a keyword only.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'criterionId': '43700004289911004', // Replace with your ID
              'conversionId': 'test_1378710000000',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '20000000', // 20 million revenueMicros is equivalent to $20 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

העלאת נתונים ממודל שיוך (Attribution) של צד שלישי

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

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

לפני שמתחילים

ב-Campaign Manager, יוצרים מודל שיוך בהתאמה אישית ומייבאים את המודל אל Search Ads 360. הקפידו לתת למודל את השם מודל שיוך חיצוני. כך התכונות של Search Ads 360 יכולות לזהות שמודל שיוך הוחל על של נתוני ההמרות שמעלים. מידע עוד

שדות חובה

כדי להחיל מודל שיוך של צד שלישי על המרה, צריך לציין את כל הפרטים הבאים: הבקשה שלך לקבלת Conversion.insert():

clickId: מזהה קליק של הביקור תלוי אותיות רישיות. אני רוצה לראות ביומני האינטרנט של המפרסם עבור מספר הקליק או הצגת ההמרות ברשימה, והם כוללים מספר קליק מהמרה אחרת. מערכת Search Ads 360 תשייך את ההמרה אל מילת המפתח, המודעה ואובייקטים אחרים ב-Search Ads 360 שהיו אחראים יצירת הביקור.
להמתין לפחות 30 דקות אחרי זה מערכת Search Ads 360 יוצרת מספר קליק לפני העלאת ההמרה עם המזהה הזה. אחרת, ייתכן ש-Search Ads 360 API לא יזהה את הביקור.
attributionModel: מגדירים כמודל שיוך חיצוני. מידע נוסף
countMillis: סכום הקרדיט על ההמרה שיש לשייך לקליק הזה. רלוונטי רק אם הבקשה כוללת גם את השדה attributionModel.
אין בלבול בין השדה הזה לבין quantityMillis, שדה אופציונלי שמציין מספר הפריטים בהמרה (למשל, מספר הפריטים בעגלת הקניות) רכישה).
conversionId: כשמדובר בהמרות אופליין, המפרסמים מספקים את המזהה הזה. המפרסמים יכולים לציין כל מזהה שיש לו משמעות. לכל המרה בבקשה צריך לציין מזהה ייחודי, והשילוב של המזהה וחותמת הזמן חייב להיות ייחודי מבין כל ההמרות אצל המפרסם. כשמשתמשים בהמרות אונליין, מערכת Search Ads 360 מעתיקה את dsConversionId או את floodlightOrderId בנכס הזה, בהתאם להוראות לדיווח על פעילות מ-Floodlight של המפרסם.
conversionTimestamp: מציין את התאריך והשעה שבהם התרחשה המרה. לדוגמה, אם ההמרה מתרחשת ביום שישי, 05 באוגוסט 2016 11:53:22 שעון קיץ, החוף המזרחי (GMT -4:00), לציין את חותמת הזמן בפרק זמן של אלפיות שנייה: 1470412402000.
segmentationType: מציין את סוג מערכת ההמרות שאתם מעלים את ההמרה אל. בשלב הזה יש תמיכה רק בהמרות של Floodlight, לכן השדה הזה תמיד צריך לציין את הערך FLOODLIGHT.
segmentationName: שם הפעילות ב-Floodlight שהמפרסם מייצג שמשמש לדיווח על ההמרה.
אם המפרסם שלכם מכיל פעילויות עם אותו שם (זה יכול לקרות אם הפעילויות שייכים לקבוצות שונות ב-Floodlight), הפעולה המומלצת היא לשנות את השם של אחת הפעילויות.

לחלופין, אם אתם יודעים שהמזהה של Search Ads 360 הקצה לפעילות ב-Floodlight, אפשר לציין את המזהה ב-segmentationId במקום לציין את השם השדה segmentationName. (Campaign Manager גם מקצה מזהה לפעילות ב-Floodlight, אבל מזהה Campaign Manager שונה מהמזהה של Search Ads 360 ולא ניתן להשתמש בו כדי לשייך conversions.) כדי לראות את מזהה Search Ads 360 של פעילות ב-Floodlight, צריך להוריד קובץ המרות (מ ממשק המשתמש של Search Ads 360 או הדוחות API). אם לפחות המרה אחת שויכה לפעילות Floodlight במהלך מסגרת הזמן, יופיע בדוח מזהה Search Ads 360.
type: סוג ההמרה, כלומר ACTION או TRANSACTION. להמרה מסוג ACTION אין ערך כספי, בעוד ההמרה לעסקה כן מתבצעת. דוגמאות: הרשמות לרשימות של כתובות אימייל (ACTION) לעומת רכישות במסחר אלקטרוני (עסקה).
אם מציינים TRANSACTION, צריך גם לציין את השדה הבא:
- revenueMicros: השווי הכספי של ההמרה.

אם עוקבים אחר הכנסות מהמרות, חשוב לוודא שהמודל מחלק את ההכנסות בין נקודת המגע בנתיב ההמרות.לדוגמה, אם המודל מתבסס על גישה לינארית (חלוקת הכנסות באופן שווה בין כל נקודת מגע), בנתיב המרות שכולל 3 קליקים על מודעות, כל קליק ישויך ל-33% מההמרה. אם ההמרה הרוויח $100 בהכנסה, ודא שהמודל שלך מחלק הכנסה של 33 $לכל קליק, ולוודא שההכנסות מ-revenueMicros מוגדרות רק ב-33 $לכל קליק.

שדות אופציונליים

quantityMillis: מספר הפריטים בהמרה הזו. לדוגמה, מספר האנשים שנרשמו לניוזלטר באימייל או את סך כל הפריטים שנמכרו. אם לא מציינים את השדה הזה להמרות מסוג ACTION, מערכת Search Ads 360 מוסיפה באופן אוטומטי של 1000.
currencyCode: המטבע של ההכנסה מעסקה. כברירת מחדל, ההכנסה היא כאילו הם במטבע של המפרסם. אם מציינים מטבע אחר, מערכת Search Ads 360 ממירה את סכום ההכנסה שצוין למטבע של המפרסם. מידע נוסף
צריך להשתמש באותיות אלפביתיות לפי תקן ISO 4217 (3 תווים) [פורמט] כדי לציין את המטבע.
רלוונטי רק להמרות מסוג TRANSACTION.
customMetric ו-customDimension: מעלה נתונים נוספים לגבי המרות, כמו המדינה שאליה נשלח פריט שנרכש, מזהי מוצרים או אפילו משך שיחת טלפון. מידע נוסף על העלאת נתונים בשביל משתנים של Floodlight.
deviceType: מציין את סוג המכשיר שבו התרחשה ההמרה. צפייה רשימת הערכים הקבילים השדה הזה.

דוגמה

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "PP5K8iI6ul7Vw09JZZDEp", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "attributionModel": "External Attribution Model",
    "countMillis": "330",
    "revenueMicros": "33000000", // 33 million revenueMicros is equivalent to $33 of revenue
    "currencyCode": "USD"
  }]
}

כדי לשלוח את הבקשה, צריך להשתמש בסקריפט של כלי השירות של Search Ads 360

כדי לשלוח בקשת JSON POST גולמית, אפשר להשתמש ב-sa360Api.py סקריפט באופן הבא:

מעתיקים את אובייקט ה-JSON לדוגמה (כל מה שמופיע בין השניים, כולל סוגריים מסולסלים) בקובץ טקסט חדש בשם request.txt.
משנים את מזהה הסוכנות שמופיע בקוד ה-JSON למזהה הסוכנות שלכם.
מסירים תגובות, למשל // The date column segments the report by individual days.
מרכיבים את פרטי הכניסה של OAuth 2.0 במחרוזת אחת שמופרדת בפסיקים עוקב:
client-ID,client-secret,refresh-token
(זו אותה המחרוזת ש-sa360Api.py יוצרת כשמריצים את sa360Api.py --login, כפי שמתואר בהגדרה הרשאה).
מפעילים את sa360Api.py באופן הבא:
sa360Api.py --cred CREDENTIALS --server API-method --post < request.txt
בפקודה שלמעלה, מחליפים ב-CREDENTIALS את המחרוזת שהרכבתם בשלב הקודם.
מחליפים את השם של שיטת ה-POST בתיבה שלמטה בשדה API-method.
לדוגמה:
sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --post < request.txt

טיפול בתשובות של Search Ads 360

התגובה מ-Search Ads 360 מציינת הצלחה רק אם כל ההמרות הבקשה אומתה והועלתה בהצלחה.

אם הבקשה מצליחה

אם הבקשה תאושר, התשובה תכלול את הנתונים הפנימיים המלאים של Search Ads 360 של כל המרה שהועלתה, למשל מזהה קמפיין, מזהה קבוצת מודעות ומילת מפתח מזהה (קריטריון).

{
 "kind": "doubleclicksearch#conversionList",
 "conversion": [
  {
   "agencyId": "12300000000000456",
   "advertiserId": "45600000000010291",
   "engineAccountId": "700000000042441",
   "campaignId": "71700000002044839",
   "adGroupId": "58700000032026064",
   "criterionId": "43700004289911004",
   "adId": "0",
   "dsConversionId": "48719131694768384",
   "conversionId": "test_1383157331951",
   "state": "ACTIVE",
   "type": "TRANSACTION",
   "revenueMicros": "20000000",
   "currencyCode": "USD",
   "segmentationType": "FLOODLIGHT",
   "segmentationId": "25700000001464141",
   "segmentationName": "Test",
   "conversionTimestamp": "1378710000000",
   "conversionModifiedTimestamp": "1383157332368"
  },
  ...
 ]
}

אם הבקשה לא מצליחה.

אם המרה אחת או יותר לא עוברות אימות או העלאה, התגובה כוללת הודעות לגבי כל העלאה של המרה שנכשלה. התגובה לא כוללת הודעות על המרות הועלה בהצלחה.

הנה דוגמה לתשובה לבקשה שלא מצליחה במלואה:

{
 "error": {
    "errors": [
       {
          "reason": "requestValidation",
          "message": "The request was not valid. Details: [0x0000011F: Advertiser conversion ID ..."
       },
       {
          "reason": "requestValidation",
          "message": "The request was not valid. Details:  [0x00000101: Click ID ..."
       }
    ]
  }
}

כל הודעה על כשל כוללת שני שדות חשובים: סיבה ושגיאה מפורטת הודעה. השדה 'סיבה' יכול להכיל requestValidation, internalError, transactionFailed או transactionFailed.

שגיאות requestVerifyation

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

קוד הקסדצימלי המזהה את סוג השגיאה. ניתן להשתמש בקוד כדי לזהות את השגיאות.
תיאור של שגיאת האימות.

מידע נוסף זמין במאמר רשימת קודים תיאורים שמערכת Search Ads 360 יכולה להחזיר במקרים של שגיאות בהעלאת המרות.

סוגים נוספים של שגיאות

כל סוגי השגיאות האחרים (internalError, transactionFailed, או lateStageRequestError) מציינים שיש בעיה פנימית Search Ads 360.

איך עונים לשגיאה

אם הבקשה נכשלת, אפשר לנסות לשלוח מחדש את הבקשה כולה מאוחר יותר. Search Ads 360 ידווח על שגיאות requestValidation עבור כל ההמרות כבר הועלה, אבל הוא ינסה להעלות את ההמרות הנותרות.

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