Conversion.update() 메서드를 호출하여 하나 이상의 기존 전환을 다음과 같이 변경합니다.
- 수익, 통화 코드 또는 수량을 수정합니다.
- 광고주가 제공한 주문 ID 및 맞춤 플러드라이트 변수를 수정합니다.
conversion.state를ACTIVE에서REMOVED로 변경하여 전환을 삭제합니다.
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'를 찾을 수 있습니다.
업데이트 요청 보내기
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() 요청을 보낼 수 있습니다.
clickIdconversionIdconversionTimestamptypesegmentationType및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)conversionIdconversionTimestamptypestate(상태를 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 응답 처리를 참고하세요.