呼叫 Conversion.update()
方法,對一或多個現有轉換進行下列類型的變更:
- 修改收益、貨幣代碼或數量。
- 修改廣告客戶提供的訂單 ID 和任何 Floodlight 自訂變數。
- 如要移除轉換,請將
conversion.state
從ACTIVE
變更為REMOVED
。
Search Ads 360 不支援變更下列項目:
- 轉換日期。
- 轉換類型。
- 促成轉換的關鍵字、廣告或造訪。
- Floodlight 活動或活動名稱。
不過,您隨時可以將現有轉換標示為「已移除」,並上傳包含更新日期、類型、歸因 ID 或 Floodlight 活動的新轉換 (請務必一併指定新的 conversionId
)。
和 Conversion.insert()
一樣,如果您的更新要求指定多個轉換,Search Ads 360 會盡可能嘗試更新每個轉換,而不是將整批更新視為一次全部或無效交易。如果批次中的部分更新失敗,其他項目可能仍會成功。建議您針對每個更新後的轉換閱讀回覆,確保更新成功。
傳送更新要求
您在 Conversion.update()
中指定的大部分欄位會用來識別您要更新的轉換。您可以使用下列任一技巧找出現有的轉換:
- 指定轉換的
clickId
- 所有編輯的轉換都必須在產生點擊 ID 後的 60 天內。
- 指定轉換的
criterionId
(關鍵字 ID)
這兩種技巧都需要指定轉換的 conversionId
、conversionTimestamp
和交易 type
。
此外,如果原始轉換已指定 revenueMicros
和 currencyCode
或 quantityMillis
,即使您未變更原始轉換,更新要求也必須指定這項資料。
按點擊 ID 識別轉換
如果轉換原本有指定點擊 ID,您可以傳送 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()
要求會使用 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", "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())
按關鍵字 ID 識別轉換
如果您沒有點擊 ID 的存取權,或轉換原本歸因於關鍵字或關鍵字/廣告,可以傳送指定下列欄位的 Conversion.update()
要求:
criterionId
(關鍵字 ID)conversionId
conversionTimestamp
type
state
(只有在您想將狀態變更為「已移除」或「有效」時才需要)quantityMillis
(僅限在原始轉換中指定)revenueMicros
(僅限在原始轉換中指定)currencyCode
(僅限在原始轉換中指定)
您可以視需要指定其他 ID,例如轉換的廣告 ID、廣告活動 ID 等,但這並非硬性規定。Search Ads 360 只需要上述清單中的 ID,就能識別現有的轉換。
範例
以下是現有的轉換範例:
{ "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()
要求會使用 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": [ { "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 內部表示法,例如廣告活動 ID、廣告群組 ID 和關鍵字 (條件) ID。
如果一或多項更新無法驗證或上傳,回應中會包含每個更新失敗的失敗訊息。回應中不含成功更新的轉換相關訊息。如要進一步瞭解這些失敗訊息,請參閱「處理 Search Ads 360 回應」一文的插入要求。