기존 전환 수정

Conversion.update() 메서드를 호출하여 하나 이상의 기존 전환을 다음과 같이 변경합니다.

Search Ads 360에서는 다음 항목을 변경할 수 없습니다.

  • 전환 날짜입니다.
  • 전환 유형
  • 전환에 기여한 키워드 또는 방문
  • 플러드라이트 활동 또는 활동 이름

하지만 언제든지 기존 전환을 REMOVED로 표시하고 업데이트된 날짜, 유형, 기여 분석 ID 또는 플러드라이트 활동이 포함된 새 전환을 업로드할 수 있습니다(새 conversionId도 지정해야 함).

Search Ads 360 API를 통해 업로드된 전환(오프라인 전환)과 Search Ads 360에서 플러드라이트 태그를 통해 기록한 전환(온라인 전환)을 모두 수정할 수 있으며, 다음 시간 제한이 적용됩니다.

  • clickId로 전환을 식별하는 경우 클릭 ID는 지난 60일 이내에 생성되어야 합니다(그렇지 않으면 오류 코드 0x0000012F).
  • 플러드라이트 태그를 통해 기록된 전환은 conversionTimestamp로부터 28일 이내에만 수정할 수 있습니다(그렇지 않으면 오류 코드 0x00000125).

Conversion.insert()와 마찬가지로 업데이트 요청에서 여러 전환을 지정하는 경우 Search Ads 360은 전체 배치를 전부 또는 전무 트랜잭션으로 업데이트하는 대신 최선을 다해 각 전환을 업데이트하려고 시도합니다. 배치의 일부 업데이트가 실패하더라도 다른 업데이트는 성공할 수 있습니다. 업데이트된 모든 전환에 대한 응답을 읽어 업데이트가 성공했는지 확인하는 것이 좋습니다.

dsConversionId 지원 중단

dsConversionId 필드는 지원 중단되었으며 더 이상 전환을 식별하는 데 사용할 수 없습니다. Search Ads 360 Conversion API에서 전환을 수정하려면 conversionId(광고주 전환 ID)를 사용해야 합니다. Conversion.update()는 전환이 다음 중 하나에 해당하는 경우 오류 코드 0x0000013C(Conversion editing using integer DS conversion ID is deprecated)과 함께 전환을 거부합니다.

  • dsConversionId 필드를 지정하거나
  • conversionId 필드에 Search Ads 360 전환 ID(Search Ads 360에서 각 전환에 대해 생성하는 17자리 숫자 ID)를 전달합니다.

주요 변경사항:

  • dsConversionId 지원 중단: dsConversionID는 Search Ads 360 Conversion API, Search Ads 360 Reporting API(conversion.id라고 함) 또는 보고 UI('전환 ID'라고 함)에서 더 이상 지원되지 않습니다.
  • conversionId 요구사항: conversionId는 Search Ads 360 Conversion API를 통해 전환을 수정하는 데 필요한 필수 필드입니다.

conversionId을 받는 방법:

  • Search Ads 360 API를 통해 업로드된 전환: 전환을 삽입할 때 지정한 conversionId를 사용합니다.
  • 플러드라이트 태그를 통해 기록된 전환: 플러드라이트 태그가 전환에 대해 보고한 플러드라이트 주문 ID(ord 값)를 사용합니다(예: 플러드라이트 판매 활동의 주문 또는 거래 ID).
  • Search Ads 360 Reporting API: Search Ads 360 Reporting API를 사용하여 advertiser_conversion_id를 검색할 수 있습니다. 이 값은 수정에 필요한 conversionId에 해당합니다.
  • Search Ads 360 UI: Search Ads 360 사용자 인터페이스의 전환 보고 페이지에서 '광고주 전환 ID'를 찾을 수 있습니다. SA360 보고서의 전환 ID

업데이트 요청 보내기

Conversion.update()에서 지정하는 대부분의 필드는 업데이트할 전환을 식별하는 데 사용됩니다. 다음 기법 중 하나를 사용하여 기존 전환을 식별할 수 있습니다.

  • 전환의 clickId를 지정합니다.
    • 수정된 모든 전환은 클릭 ID가 생성된 시점으로부터 60일 이내여야 합니다.
  • 전환의 키워드(customerId, campaignId, adGroupId, criterionId)를 지정합니다.

두 기법 모두 전환의 conversionId, conversionTimestamp, 거래 type를 지정해야 합니다. conversionTimestamp는 기존 전환의 타임스탬프여야 하며, 에포크 밀리초 UTC 형식이어야 합니다. 타임스탬프가 기존 전환과 일치하지 않는 경우(예: 현지 시간대에서 변환되었기 때문) Search Ads 360에서 전환을 찾을 수 없으며 오류 코드 0x0000011B를 반환합니다.

Search Ads 360에서 플러드라이트 태그를 통해 기록한 전환의 경우 전환의 플러드라이트 활동(segmentationType 및 segmentationName 또는 segmentationId)도 지정해야 합니다. 그렇지 않으면 요청이 실패하고 오류 코드 0x0000010C가 표시됩니다. 모든 업데이트 요청에서 플러드라이트 활동을 지정하는 것이 좋습니다.

또한 원래 전환에서 revenueMicros 및 currencyCode 또는 quantityMillis를 지정한 경우 업데이트 요청에서 이 데이터를 변경하지 않더라도 이 데이터를 지정해야 합니다.

클릭 ID로 전환 식별

전환에서 원래 클릭 ID를 지정한 경우 다음 필드를 지정하는 Conversion.update() 요청을 보낼 수 있습니다.

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • segmentationType 및 segmentationName(또는 segmentationId)(플러드라이트 태그를 통해 기록된 전환에 필요, 모든 전환에 권장됨)
  • state(상태를 REMOVED 또는 ACTIVE로 변경하려는 경우에만 필요)
  • 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() 요청은 PUT HTTP 메서드를 사용합니다.

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",
   "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",
   "conversionTimestamp": "1378710000000",
   "segmentationType" : "FLOODLIGHT",
   "segmentationName" : "Test",
   "type": "ACTION",
   "quantityMillis": "1000",
   "state": "REMOVED"
  }
 ]
}        

자바

/**
 * 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. This sample hard-codes the segmentation name.
    Conversion conversion = new Conversion()
        .setClickId(clickId)
        .setConversionId(conversionId)
        .setConversionTimestamp(BigInteger.valueOf(timeStamp))
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .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())

키워드 ID로 전환 식별

클릭 ID에 액세스할 수 없거나 전환이 원래 키워드 또는 키워드/광고에 기여한 경우 다음 필드를 지정하는 Conversion.update() 요청을 보낼 수 있습니다.

  • customerId, campaignId, adGroupId, criterionId(키워드를 식별하는 새 Search Ads 360 ID)
  • conversionId
  • conversionTimestamp
  • type
  • state(상태를 REMOVED 또는 ACTIVE로 변경하려는 경우에만 필요)
  • quantityMillis(원본 전환에 지정된 경우에만 해당)
  • revenueMicros(원본 전환에 지정된 경우에만 해당)
  • currencyCode(원본 전환에 지정된 경우에만 해당)

키워드 ID는 광고 그룹 내에서만 고유하므로 네 가지 ID를 모두 지정해야 합니다. 전환에서 customerId, campaignId 또는 adGroupId 없이 criterionId를 지정하면 업데이트가 실패하고 오류 코드 0x0000012E가 표시됩니다. 전환의 광고 ID와 같은 다른 ID는 지정할 필요가 없습니다.

예

다음은 기존 전환의 예입니다.

{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
   "customerId": "123-456-7890",
   "campaignId": "14660344555",
   "adGroupId": "105138634255",
   "criterionId": "948710340465",
   "conversionId": "test_1383157519886",
   "conversionTimestamp": "1378710000000",
   "type": "ACTION",
   "quantityMillis": "1000",
   "segmentationType": "FLOODLIGHT",
   "segmentationName": "Test"
  }]
}     

다음 요청은 전환수를 업데이트합니다.

JSON

Conversion.update() 요청은 PUT HTTP 메서드를 사용합니다.

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

자바

    // Send conversion data to updateConversion, which creates a conversion and adds it
    // to the conversion list.
    conversionList =  updateConversionFromKeyword(conversionList,
        "123-456-7890",       // customerId. Replace with your ID
        14660344555L,         // campaignId. Replace with your ID
        105138634255L,        // adGroupId. Replace with your ID
        948710340465L,        // 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,
       String customerId,
       Long campaignId,
       Long adGroupId,
       Long criterionId,
       String conversionId,
       Long timeStamp,
       String type,
       String state,
       Long quantity,
       Long revenue,
       String currency
    ) {

   Conversion conversion = new Conversion()
   .setCustomerId(customerId)
   .setCampaignId(campaignId)
   .setAdGroupId(adGroupId)
   .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 quantity of a conversion. Use the keyword's IDs (customerId,
  campaignId, adGroupId, and criterionId) to identify the conversion.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().update(
      body=
      {
          'conversion': [{
              'customerId': '123-456-7890', // Replace with your ID
              'campaignId': '14660344555', // Replace with your ID
              'adGroupId': '105138634255', // Replace with your ID
              'criterionId': '948710340465', // Replace with your ID
              'conversionId': 'test_1383157519886',
              'conversionTimestamp': '1378710000000',
              'type': 'ACTION',
              'quantityMillis': '3000'
            }]
      }
  )

  pprint.pprint(request.execute())

Search Ads 360 응답 처리

업데이트 요청에 대한 응답은 삽입 요청에 대한 응답과 동일합니다. Search Ads 360은 요청의 모든 전환이 성공적으로 업데이트된 경우에만 성공을 표시합니다.

요청이 성공하면 응답에는 새 Search Ads 360 고객 ID, 캠페인 ID, 광고 그룹 ID, 키워드(기준) ID와 같이 업데이트된 각 전환의 전체 Search Ads 360 내부 표현이 포함됩니다.

하나 이상의 업데이트가 검증 또는 업로드에 실패하면 응답에 실패한 각 업데이트에 대한 실패 메시지가 포함됩니다. 응답에는 성공적으로 업데이트된 전환에 대한 메시지가 포함되지 않습니다. 이러한 실패 메시지에 대한 자세한 내용은 삽입 요청에 대한 Search Ads 360 응답 처리를 참고하세요.