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

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

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

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

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

כמו במקרה של Conversion.insert(), אם בבקשת העדכון יש מספר המרות, מערכת 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"
  }
 ]
}

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. 

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 לבקשות הוספה.