Sửa đổi lượt chuyển đổi hiện tại

Gọi phương thức Conversion.update() để thực hiện các loại thay đổi sau đối với một hoặc nhiều lượt chuyển đổi hiện có:

Search Ads 360 không hỗ trợ thay đổi những nội dung sau:

  • Ngày chuyển đổi.
  • Loại chuyển đổi.
  • Từ khoá hoặc lượt truy cập được phân bổ cho lượt chuyển đổi.
  • Hoạt động Floodlight hoặc tên hoạt động.

Tuy nhiên, bạn luôn có thể đánh dấu một lượt chuyển đổi hiện có là ĐÃ XOÁ và tải một lượt chuyển đổi mới lên với ngày, loại, mã phân bổ hoặc hoạt động Floodlight đã cập nhật (hãy nhớ chỉ định cả conversionId mới).

Giống như với Conversion.insert(), nếu yêu cầu cập nhật của bạn chỉ định nhiều lượt chuyển đổi, thì Search Ads 360 sẽ cố gắng cập nhật từng lượt chuyển đổi trên cơ sở tối đa thay vì cập nhật toàn bộ lô dưới dạng một giao dịch hoàn toàn hoặc không có gì. Nếu một số bản cập nhật trong một lô không thành công, thì một số khác vẫn có thể thành công. Bạn nên đọc phản hồi cho mọi lượt chuyển đổi được cập nhật để đảm bảo cập nhật thành công.

Gửi yêu cầu cập nhật

Hầu hết trường mà bạn chỉ định trong Conversion.update() đều được dùng để xác định các lượt chuyển đổi mà bạn muốn cập nhật. Bạn có thể sử dụng một trong các kỹ thuật sau để xác định một lượt chuyển đổi hiện có:

  • Chỉ định clickId của lượt chuyển đổi
    • Tất cả các lượt chuyển đổi được chỉnh sửa phải trong vòng 60 ngày kể từ thời điểm mã lượt nhấp được tạo.
  • Chỉ định criterionId của lượt chuyển đổi (mã từ khoá)

Cả hai kỹ thuật đều yêu cầu bạn chỉ định conversionId, conversionTimestamp và giao dịch type của lượt chuyển đổi.

Ngoài ra, nếu lượt chuyển đổi ban đầu được chỉ định revenueMicros và currencyCode hoặc quantityMillis, thì yêu cầu cập nhật cần chỉ định dữ liệu này ngay cả khi bạn không thay đổi.

Xác định lượt chuyển đổi theo mã lượt nhấp

Nếu ban đầu một lượt chuyển đổi đã chỉ định mã lượt nhấp, thì bạn có thể gửi yêu cầu Conversion.update() chỉ định các trường sau:

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • state (chỉ bắt buộc nếu bạn muốn thay đổi trạng thái thành ĐÃ XOÁ hoặc ĐANG HOẠT ĐỘNG)
  • quantityMillis (chỉ khi được chỉ định trong lượt chuyển đổi ban đầu)
  • revenueMicros (chỉ khi được chỉ định trong lượt chuyển đổi ban đầu)
  • currencyCode (chỉ khi được chỉ định trong lượt chuyển đổi ban đầu)

Ví dụ:

Dưới đây là ví dụ về hai lượt chuyển đổi hiện có: 

{
 "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"
  }]
}

Yêu cầu sau đây sẽ cập nhật một trong các lượt chuyển đổi trong ví dụ trước rồi xoá lượt chuyển đổi còn lại:

JSON

Xin lưu ý rằng yêu cầu Conversion.update() sử dụng phương thức 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())

Xác định lượt chuyển đổi theo mã từ khoá

Nếu bạn không có quyền truy cập vào mã lượt nhấp hoặc nếu một lượt chuyển đổi ban đầu được phân bổ cho một từ khoá hoặc từ khoá/quảng cáo, thì bạn có thể gửi yêu cầu Conversion.update() chỉ định các trường sau:

  • criterionId (Mã từ khóa)
  • conversionId
  • conversionTimestamp
  • type
  • state (chỉ bắt buộc nếu bạn muốn thay đổi trạng thái thành ĐÃ XOÁ hoặc ĐANG HOẠT ĐỘNG)
  • quantityMillis (chỉ khi được chỉ định trong lượt chuyển đổi ban đầu)
  • revenueMicros (chỉ khi được chỉ định trong lượt chuyển đổi ban đầu)
  • currencyCode (chỉ khi được chỉ định trong lượt chuyển đổi ban đầu)

Bạn có thể tuỳ ý chỉ định các mã khác, chẳng hạn như mã quảng cáo của lượt chuyển đổi, mã chiến dịch, v.v., nhưng bạn không cần. Search Ads 360 chỉ cần các mã trong danh sách trên để xác định một lượt chuyển đổi hiện có.

Ví dụ:

Dưới đây là ví dụ về một lượt chuyển đổi hiện có: 

{
 "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"
  }]
}

Yêu cầu sau đây sẽ cập nhật dấu thời gian của lượt chuyển đổi:

JSON

Xin lưu ý rằng yêu cầu Conversion.update() sử dụng phương thức 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())

Xử lý phản hồi của Search Ads 360

Phản hồi cho một yêu cầu cập nhật giống với phản hồi cho một yêu cầu chèn: Search Ads 360 chỉ cho biết thành công nếu tất cả các lượt chuyển đổi trong yêu cầu đó đã được cập nhật thành công.

Nếu yêu cầu thành công, thì phản hồi sẽ bao gồm bản trình bày nội bộ đầy đủ của Search Ads 360 cho từng lượt chuyển đổi được cập nhật, chẳng hạn như mã chiến dịch, mã nhóm quảng cáo và mã từ khoá (tiêu chí).

Nếu không xác thực hoặc tải được một hoặc nhiều bản cập nhật lên, thì phản hồi sẽ bao gồm thông báo lỗi cho mỗi lần cập nhật không thành công. Phản hồi không chứa thông báo về những lượt chuyển đổi đã được cập nhật thành công. Để biết thêm thông tin về những thông báo lỗi này, hãy xem bài viết Xử lý phản hồi của Search Ads 360 đối với các yêu cầu chèn.