שינוי המרות קיימות

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

• משנים את ההכנסה, קוד המטבע או הכמות.
• משנים את מזהה ההזמנה שסופק על ידי המפרסם ואת כל המשתנים המותאמים אישית של Floodlight.
• כדי להסיר את ההמרה, משנים את הערך של conversion.state מ-ACTIVE ל-REMOVED.

ב-Search Ads 360 אין תמיכה בשינויים הבאים:

• תאריך ההמרה.
• סוג ההמרה
• מילת המפתח או הביקור שמשויכים להמרה.
• הפעילות ב-Floodlight או השם שלה

עם זאת, תמיד אפשר לסמן המרה קיימת כ'הוסר' ולהעלות המרה חדשה עם התאריך, הסוג, מזהי השיוך או הפעילות ב-Floodlight המעודכנים (חשוב לציין גם conversionId חדש).

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

(עדכון 2025) הוצאה משימוש של dsConversionId

בשלב הזה, אפשר להשתמש ב-dsConversionId או ב-conversionId כדי לזהות ולערוך המרות. השדה dsConversionId יוצא משימוש ברבעון השלישי של שנת 2025. מעכשיו והלאה, צריך להשתמש ב-conversionId כדי לערוך המרות ב-Search Ads 360 Conversion API.

שינויים מרכזיים:

• הוצאה משימוש של dsConversionId: לא תהיה יותר תמיכה ב-dsConversionID ב-Search Ads 360 Reporting API (שנקרא conversion.id) או בממשק המשתמש של הדיווח (שנקרא 'מזהה המרה').
• דרישה לגבי conversionId: השדה conversionId יהפוך לשדה חובה לעריכת המרות דרך Search Ads 360 Conversion API.

איך מקבלים את conversionId:

• Search Ads 360 Reporting API: אפשר לאחזר את advertiser_conversion_id באמצעות Search Ads 360 Reporting API. הערך הזה תואם ל-conversionId הנדרש לעריכה.
• ממשק המשתמש של Search Ads 360: אפשר למצוא את 'מזהה ההמרה של המפרסם' בדף הדוחות של ההמרות בממשק המשתמש של Search Ads 360.

שליחת בקשה לעדכון

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

• מציינים את clickId של ההמרה
  • כל ההמרות שעורכים צריכות להתרחש תוך 60 יום ממועד יצירת מספר הקליק.
• מציינים את הערך של criterionId (מזהה מילת המפתח) של ההמרה

בשתי השיטות צריך לציין את השדות conversionId,‏ conversionTimestamp ו-type של ההמרה ושל העסקה.

בנוסף, אם בהמרה המקורית צוינו השדות revenueMicros ו-currencyCode או quantityMillis, צריך לציין את הנתונים האלה בבקשת העדכון גם אם לא משנים אותם.

זיהוי המרות לפי מספר קליק

אם במקור צוין מספר קליק בהמרה, אפשר לשלוח בקשה מסוג Conversion.update() שמציינת את השדות הבאים:

• clickId
• conversionId
• conversionTimestamp
• type
• state (נדרש רק אם רוצים לשנות את המצב ל'הוסר' או ל'פעיל')
• quantityMillis (רק אם צוין בהמרה המקורית)
• revenueMicros (רק אם צוין בהמרה המקורית)
• currencyCode (רק אם צוין בהמרה המקורית)

דוגמה

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

{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA",
    "conversionId" : "test_20130906_10",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "revenueMicros": "100000000", // 100 million revenueMicros is equivalent to $100 of revenue
    "currencyCode": "USD"
  },
  {
   "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA",
   "conversionId": "test_1383337059137",
   "conversionTimestamp": "1378710000000",
   "segmentationType" : "FLOODLIGHT",
   "segmentationName" : "Test",
   "type": "ACTION",
   "quantityMillis": "1000"
  }]
}     

הבקשה הבאה מעדכנת אחת מההמרות מהדוגמה הקודמת ומסירה את השנייה:

JSON

הערה: בבקשה Conversion.update() נעשה שימוש בשיטת ה-HTTP‏ PUT.

PUT 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 data from your site
   "conversionId": "test_20130906_10",
   "conversionTimestamp": "1378710000000",
   "type": "TRANSACTION",
   "revenueMicros": "90000000", // 90 million revenueMicros is equivalent to $90 of revenue
   "currencyCode": "USD"
  },
  {
   "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site
   "conversionId": "test_1383337059137",
   "conversionTimestamp": "1378710000000",
   "type": "ACTION",
   "quantityMillis": "1000",
   "state": "REMOVED"
  }
 ]
}        

שולחים את הבקשה הזו באמצעות סקריפט השירות של Search Ads 360

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

1. מעתיקים את אובייקט ה-JSON לדוגמה (הכול בין שתי סוגריות המרובעות, כולל אותן) לקובץ טקסט חדש בשם request.txt.
2. מחליפים את מזהה הסוכנות שמופיע בקוד ה-JSON במזהה הסוכנות שלכם.
3. מסירים תגובות, כמו // The date column segments the report by individual days.
4. אספו את פרטי הכניסה ל-OAuth 2.0 למחרוזת אחת שמפרידה בין הערכים באמצעות פסיק, באופן הבא:
   client-ID,client-secret,refresh-token
   (זוהי אותה מחרוזת שמופיעה כפלט של sa360Api.py כשמריצים את sa360Api.py --login, כפי שמתואר בקטע הגדרת הרשאה).
5. מריצים את sa360Api.py באופן הבא:
   sa360Api.py --cred CREDENTIALS --server API-method --put < request.txt
   בפקודה שלמעלה, מחליפים את CREDENTIALS במחרוזת שיצרתם בשלב הקודם.
   מחליפים את השם של שיטת ה-PUT בתיבת הטקסט שלמטה ב-API-method.

   לדוגמה:
   sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --put < request.txt

Java

/**
 * Instantiate the Doubleclicksearch service, create a conversion that updates an existing conversion,
 * and upload the conversions.
 */
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>();

  // Create a conversion and add it to the conversion list.
  // Just to get a little fancy, the updateConversionFromVisit() method can be used for all
  // visit conversions, including conversions that don't specify quantity, revenue, or currency.
  // If quantityMillis wasn't specified in the original conversion, specify -1L for the
  // quantityMillis parameter. Likewise, if revenueMicros wasn't specified originally,
  // specify -1L for the revenueMicros parameter and an empty string for currency.
  conversionList = updateConversionFromVisit(
      conversionList,
      "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site
      "test_20130906_10",           // conversionId
      1378710000000L,               // timeStamp
      "TRANSACTION",                // type
      "",                           // state
      -1L,                          // quantityMillis
      90000000L,                    // revenueMicros. Equivalent to $90 of revenue
      "USD");                       // currencyCode

   // Here's a conversion that needs to be removed. Just set the state parameter to "REMOVED".
   conversionList = updateConversionFromVisit(
      conversionList,
      "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site
      "test_1383337059137",         // conversionId
      1378710000000L,               // timeStamp
      "ACTION",                     // type
      "REMOVED",                    // state
      1000L,                        // quantityMillis
      -1L,                          // revenueMicros
      "");                          // currencyCode

    // Upload the List and handle the response.
    uploadConversions(conversions, service); // See an example in Add New Conversions. 
  }

/**
 * Create a conversion and add it to a List<Conversion>.
 */
  private static List<Conversion> updateConversionFromVisit(List<Conversion> conversions,
      String clickId,
      String conversionId,
      Long timeStamp,
      String type,
      String state,
      Long quantity,
      Long revenue,
      String currency) {

    // Identifies the existing conversion.
    Conversion conversion = new Conversion()
        .setClickId(clickId)
        .setConversionId(conversionId)
        .setConversionTimestamp(BigInteger.valueOf(timeStamp))
        .setType(type);

    // Only add these fields if the value is not empty greater than -1.
    if(!state.isEmpty()) conversion.setState(state);
    if (quantity > -1L) {
      conversion.setQuantityMillis(quantity);
    }
    if (revenue > -1L) {
      conversion.setRevenueMicros(revenue);
      if (!currency.isEmpty()) {
        conversion.setCurrencyCode(currency);
      } else {
        System.err.println(String.format(
            "Can't add conversion %s. It specifies revenue but no currency.",
            conversion.getConversionId()));
        return conversions;
      }
    }

    conversions.add(conversion);
    return conversions;
  }         

Python

def update_conversion(service):
  """Change the revenue for one existing conversion and remove another.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().update(
      body=
      {
          'conversion' : [{
              'clickId' : 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site
              'conversionId' : 'test_20130906_13',
              'conversionTimestamp' : '1378710000000',
              'segmentationType' : 'FLOODLIGHT',
              'segmentationName' : 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '90000000', // 90 million revenueMicros is equivalent to $90 of revenue
              'currencyCode': 'USD'
            },
            {
             'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site
             'conversionId': 'test_1383337059137_01',
             'conversionTimestamp': '1378710000000',
             'segmentationType' : 'FLOODLIGHT',
             'segmentationName' : 'Test',
             'type': 'ACTION',
             'quantityMillis': '1000',
             'state': 'REMOVED'
            }]
      }
  )

  pprint.pprint(request.execute())

זיהוי המרות לפי מזהה מילת מפתח

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

• criterionId (מזהה מילת מפתח)
• conversionId
• conversionTimestamp
• type
• state (נדרש רק אם רוצים לשנות את המצב ל'הוסר' או ל'פעיל')
• quantityMillis (רק אם צוין בהמרה המקורית)
• revenueMicros (רק אם צוין בהמרה המקורית)
• currencyCode (רק אם צוין בהמרה המקורית)

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

דוגמה

דוגמה להמרה קיימת:

{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
   "agencyId": "12300000000000456",
   "advertiserId": "45600000000010291",
   "engineAccountId": "700000000042441",
   "campaignId": "71700000002044839",
   "adGroupId": "58700000032026064",
   "criterionId": "43700004289911004",
   "adId": "44700000155906860",
   "conversionId": "test_1383157519886",
   "conversionTimestamp": "1378710000000",
   "type": "ACTION",
   "quantityMillis": "1000",
   "segmentationType": "FLOODLIGHT",
   "segmentationName": "Test"
  }]
}     

הבקשה הבאה מעדכנת את חותמת הזמן של ההמרה:

JSON

הערה: בבקשה Conversion.update() נעשה שימוש בשיטת ה-HTTP‏ PUT.

שולחים את הבקשה הזו באמצעות סקריפט השירות של Search Ads 360

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

1. מעתיקים את אובייקט ה-JSON לדוגמה (הכול בין שתי סוגריות המרובעות, כולל אותן) לקובץ טקסט חדש בשם request.txt.
2. מחליפים את מזהה הסוכנות שמופיע בקוד ה-JSON במזהה הסוכנות שלכם.
3. מסירים תגובות, כמו // The date column segments the report by individual days.
4. אספו את פרטי הכניסה ל-OAuth 2.0 למחרוזת אחת שמפרידה בין הערכים באמצעות פסיק, באופן הבא:
   client-ID,client-secret,refresh-token
   (זוהי אותה מחרוזת שמופיעה כפלט של sa360Api.py כשמריצים את sa360Api.py --login, כפי שמתואר בקטע הגדרת הרשאה).
5. מריצים את sa360Api.py באופן הבא:
   sa360Api.py --cred CREDENTIALS --server API-method --put < request.txt
   בפקודה שלמעלה, מחליפים את CREDENTIALS במחרוזת שיצרתם בשלב הקודם.
   מחליפים את השם של שיטת ה-PUT בתיבת הטקסט שלמטה ב-API-method.

   לדוגמה:
   sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --put < request.txt

PUT https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
 "conversion": [
  {
   "criterionId": "43700004289911004", // Replace with your ID
   "conversionId": "test_1383157519886",
   "conversionTimestamp": "1378710000000",
   "type": "ACTION",
   "quantityMillis": "3000"
  }
 ]
}        

Java

    // Send conversion data to updateConversion, which creates a conversion and adds it
    // to the conversion list.
    conversionList =  updateConversionFromKeyword(conversionList,
        43700004289911004L,   // criterionId. Replace with your ID
        "test_1383157519886", // conversionId
        1378710000000L,       // timeStamp
        "ACTION",             // type
        "",                   // state
        3000L,                // quantityMillis
        -1L,                  // revenueMicros
        "");                  // currencyCode

  private static List<Conversion> updateConversionFromKeyword(List<Conversion> conversions,
       Long criterionId,
       String conversionId,
       Long timeStamp,
       String type,
       String state,
       Long quantity,
       Long revenue,
       String currency
    ) {

   Conversion conversion = new Conversion()
   .setCriterionId(criterionId)
   .setConversionId(conversionId)
   .setConversionTimestamp(BigInteger.valueOf(timeStamp))
   .setType(type);

   // Only add these fields if the value is not empty greater than -1.
   if(!state.isEmpty()) conversion.setState(state);
   if (quantity > -1L) {
     conversion.setQuantityMillis(quantity);
   }
   if (revenue > -1L) {
     conversion.setRevenueMicros(revenue);
     if (!currency.isEmpty()) {
       conversion.setCurrencyCode(currency);
     } else {
       System.err.println(String.format(
           "Can't add conversion %s. It specifies revenue but no currency.",
           conversion.getConversionId()));
       return conversions;
     }
   }

   conversions.add(conversion);
   return conversions;
   }                 

Python

def update_conversion(service):
  """Change the timestamp of a conversion. Use only the keyword id (criterionId)
  to identify the conversion.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().update(
      body=
      {
          'conversion': [{
              'criterionId': '43700004289911004', // Replace with your ID
              'conversionId': 'test_1383157519886',
              'conversionTimestamp': '1378760000000',
              'type': 'ACTION',
              'quantityMillis': '1000'
            }]
      }
  )

  pprint.pprint(request.execute())

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

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

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

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