呼叫 Conversion.insert() 方法,新增一或多項轉換。為正確歸因轉換,您的要求必須指定廣告主用來記錄離線轉換的 Floodlight 活動名稱,以及造訪的點擊 ID 或促成轉換的關鍵字 ID。如要瞭解如何取得 Search Ads 360 ID,請參閱「Search Ads 360 ID 和轉換」一文。
如要瞭解上傳歷來轉換資料的限制,請前往 Search Ads 360 說明中心。
如果 Conversion.insert() 要求指定多項轉換,Search Ads 360 會盡可能上傳每項轉換,而不是將整批轉換視為一筆交易,全部上傳或全部不上傳。如果批次中的部分轉換無法上傳,其他轉換仍可能成功上傳。轉換上傳作業可能會因要求無效、暫時性網路或系統故障而失敗。因此,建議您閱讀每個插入轉換的回應,確認上傳成功。
資料上傳後要多久才能使用?
如果您為轉換指定的 conversionTimestamp 為今天或昨天,在您上傳後的 1 小時內,Search Ads 360 UI 中就會出現轉換的指標。如果您指定的 conversionTimestamp 早於昨天,指標會在幾小時內更新。
將所有轉換時間戳記轉換為 Epoch 時間 (也稱為 Unix 時間)。
可以透過 API 建立 Floodlight 活動嗎?
如果廣告主尚未建立 Floodlight 活動來追蹤離線轉換,您可以使用 Campaign Manager API 建立。您無法使用 API 指定 Floodlight 活動主要用於離線轉換,這是出價策略使用轉換資料時的最佳做法。
建議您使用 API 建立 Floodlight 活動後,由 Search Ads 360 使用者登入 Search Ads 360,並變更活動設定,指出轉換的主要來源是離線活動。
新增廣告轉換的最佳做法
新增轉換時,建議您採取下列最佳做法:
請 Search Ads 360 使用者登入 Search Ads 360,並變更您用來記錄離線轉換的每個 Floodlight 活動設定。設定應指出轉換的主要來源是離線活動。如需操作說明,請參閱 Search Ads 360 說明中心。
盡快上傳轉換資料。如果您將已歸因轉換歸因於特定造訪,請在造訪後等待至少 6 小時,再上傳轉換。如果您在上傳時,距離造訪時間不到 6 小時,Search Ads 360 可能無法辨識造訪的 clickID。在極少數情況下,Search Ads 360 最多可能需要 24 小時才能辨識 clickId。
確認每次上傳都包含最新的轉換。在單一上傳要求中,項目不一定要按照時間順序排列。不過,出價策略可能無法考量您稍後在其他要求中上傳的舊轉換。
傳送插入要求
您可以傳送 Conversion.insert() 要求,執行下列任一操作:
- 將轉換歸因於特定造訪
- 僅將轉換歸因於關鍵字
Conversion.insert() 要求中的必填欄位取決於您要將轉換歸因於哪個事件或項目。以下各節列出可歸因轉換的每個事件或項目,以及其必要和選用欄位。
將轉換歸因於特定造訪
當顧客點擊一或多則廣告並連往廣告主的網站時,Search Ads 360 會將使用者在廣告主網站上的工作階段視為一次造訪。如要將轉換歸因於某次造訪,請在 Conversion.insert() 要求中指定下列項目:
必填欄位
clickId:造訪的點擊 ID (區分大小寫)。在廣告主的網頁記錄中尋找點擊 ID,或使用新版 Search Ads 360 Reporting API 擷取其他轉換的conversion.click_id。Search Ads 360 會將轉換歸因於促成造訪的關鍵字、廣告和其他 Search Ads 360 物件。
Search Ads 360 產生點擊 ID 後,請至少等待 6 小時再上傳轉換資料。 如果收到「找不到點擊 ID」錯誤訊息,請等待 24 小時,然後再次上傳轉換資料。 所有轉換都應在點擊 ID 產生後的 90 天內上傳。否則 Search Ads 360 API 可能無法辨識造訪。conversionId:如果是離線轉換,廣告主會提供這個 ID。廣告主可以指定任何有意義的 ID。要求中的每筆轉換都必須指定專屬 ID,且 ID 和時間戳記的組合在廣告主的所有轉換中不得重複。如果是線上轉換,Search Ads 360 會根據廣告主的 Floodlight 指示,將dsConversionId或floodlightOrderId複製到這項屬性。conversionTimestamp:表示轉換發生的日期和時間。舉例來說,如果轉換發生在 2016 年 8 月 5 日星期五上午 11:53:22 (美國東部日光節約時間,GMT -4:00),請以 Epoch 毫秒數指定時間戳記:1470412402000。segmentationType:指定要上傳轉換的轉換系統類型。目前僅支援 Floodlight 轉換,因此這個欄位一律必須指定FLOODLIGHT。segmentationName:廣告主用來記錄轉換的 Floodlight 活動名稱。如果廣告主包含同名的活動 (如果活動屬於不同的 Floodlight 群組,就可能發生這種情況),建議您重新命名其中一個活動。
或者,您也可以在
segmentationId欄位中指定 Floodlight 活動的 ID,而不是在segmentationName欄位中指定名稱。請使用 Campaign Manager 指派給 Floodlight 活動的 ID。您可以使用新版 Search Ads 360 Reporting API 的conversion_action.floodlight_settings.activity_id欄位擷取這個 ID。Search Ads 360 在轉換要求回應中傳回的segmentationId也可接受。type:轉換類型,即ACTION或TRANSACTION。ACTION 轉換沒有金額價值,而 TRANSACTION 轉換則有。例如電子郵件名單註冊 (動作) 與電子商務購買 (交易)。如果指定
TRANSACTION,也必須指定下列欄位:revenueMicros:轉換的金額價值。
選填欄位
quantityMillis:這項轉換中的項目數量。例如訂閱電子報的人數或售出的商品總數。如果未在 ACTION 轉換中指定這個欄位,Search Ads 360 會自動插入1000值。currencyCode:交易收益的幣別。根據預設,系統會假設收益是以廣告主所用幣別計算。如果您指定其他幣別,Search Ads 360 會將指定的收益金額換算成廣告主所用幣別。瞭解詳情
請使用 ISO 4217 字母 (3 個字元) 格式指定貨幣。
僅適用於交易型轉換。customMetric和customDimension:上傳轉換的其他資料,例如購買商品的運送國家/地區、產品 ID,甚至是通話時間長度。進一步瞭解如何上傳 Floodlight 自訂變數資料。deviceType:指定轉換在哪種裝置類型上發生,請參閱這個欄位接受的值清單。
JSON
POST 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 a click ID from your site "conversionId" : "test_20130906_04", "conversionTimestamp" : "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "TRANSACTION", "revenueMicros": "10000000", // 10 million revenueMicros is equivalent to $10 of revenue "currencyCode": "USD" }] }
Java
/** * Instantiate the Doubleclicksearch service, create conversions, and upload them. */ 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>(); // Add a conversion to the List. addTransactionConversionForVisit(conversions, "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site "test_" + System.currentTimeMillis(), 10000000L, 1378710000000L); // Upload the List and handle the response. uploadConversions(conversions, service); } /** * Create a TRANSACTION conversion and add it to a List<Conversion>. This sample hard-codes * the segmentation name and currency. You probably wouldn't want your production code to be so brittle. */ private static List<Conversion> addTransactionConversionForVisit(List<Conversion> conversions, String clickId, String conversionId, Long revenue, Long timeStamp) { Conversion conversion = new Conversion().setClickId(clickId) .setConversionId(conversionId) .setSegmentationType("FLOODLIGHT") .setSegmentationName("Test") .setType("TRANSACTION") .setRevenueMicros(revenue) .setCurrencyCode("USD") .setConversionTimestamp(BigInteger.valueOf(timeStamp)); conversions.add(conversion); return conversions; } /** * Convert the List of conversions to a DS ConversionList, send an insert request to DS, * and output the response to a file. */ private static void uploadConversions(List<Conversion> conversions, Doubleclicksearch service) throws IOException { FileOutputStream outputStream = new FileOutputStream(new File("./", "InsertConversionsResponse.txt")); final PrintStream printStream = new PrintStream(outputStream); try { // Convert the List to a ConversionList. ConversionList conversionList = new ConversionList().setConversion(conversions); // Insert an upload request and download the response to a file. service.conversion().insert(conversionList).executeAndDownloadTo(printStream); printStream.close(); } catch (GoogleJsonResponseException e) { System.err.println("Get request was rejected."); for (ErrorInfo error : e.getDetails().getErrors()) { System.err.println(error.getMessage()); } System.exit(e.getStatusCode()); } }
Python
def insert_conversion(service): """Create and upload a TRANSACTION conversion that is attributed to a visit. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().insert( body= { 'conversion': [{ 'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with a click ID from your site 'conversionId': 'test_20140206_00', 'conversionTimestamp': '1378710000000', 'segmentationType': 'FLOODLIGHT', 'segmentationName': 'Test', 'type': 'TRANSACTION', 'revenueMicros': '10000000', // 10 million revenueMicros is equivalent to $10 of revenue 'currencyCode': 'USD' }] } ) pprint.pprint(request.execute())
僅將轉換歸因於關鍵字
如果沒有點擊 ID,可以直接將轉換歸因於關鍵字。在新版 Search Ads 360 中,關鍵字 ID 只有在廣告群組內才不重複,因此您需要指定一組完整的新版 Search Ads 360 ID 來識別關鍵字,以及其他幾個欄位:
必填欄位
customerId:包含關鍵字的客戶帳戶客戶 ID,例如123-456-7890。campaignId:包含關鍵字的廣告活動 ID。adGroupId:包含關鍵字的廣告群組 ID。criterionId:關鍵字的 ID。如果轉換指定
criterionId,但未指定customerId、campaignId或adGroupId,則會失敗並傳回錯誤代碼0x0000012E。如要瞭解如何取得這些 ID,請參閱「Search Ads 360 ID 和轉換」。conversionId:如果是離線轉換,廣告主會提供這個 ID。廣告主可以指定任何有意義的 ID。要求中的每筆轉換都必須指定專屬 ID,且 ID 和時間戳記的組合在廣告主的所有轉換中不得重複。如果是線上轉換,Search Ads 360 會根據廣告主的 Floodlight 指示,將dsConversionId或floodlightOrderId複製到這項屬性。conversionTimestamp:表示轉換發生的日期和時間。舉例來說,如果轉換發生在 2016 年 8 月 5 日星期五上午 11:53:22 (美國東部日光節約時間,GMT -4:00),請以 Epoch 毫秒數指定時間戳記:1470412402000。segmentationType:指定要上傳轉換的轉換系統類型。目前僅支援 Floodlight 轉換,因此這個欄位一律必須指定FLOODLIGHT。segmentationName:廣告主用來記錄轉換的 Floodlight 活動名稱。如果廣告主包含同名的活動 (如果活動屬於不同的 Floodlight 群組,就可能發生這種情況),建議您重新命名其中一個活動。
或者,您也可以在
segmentationId欄位中指定 Floodlight 活動的 ID,而不是在segmentationName欄位中指定名稱。請使用 Campaign Manager 指派給 Floodlight 活動的 ID。您可以使用新版 Search Ads 360 Reporting API 的conversion_action.floodlight_settings.activity_id欄位擷取這個 ID。Search Ads 360 在轉換要求回應中傳回的segmentationId也可接受。type:轉換類型,即ACTION或TRANSACTION。ACTION 轉換沒有金額價值,而 TRANSACTION 轉換則有。例如電子郵件名單註冊 (動作) 與電子商務購買 (交易)。如果指定
TRANSACTION,也必須指定下列欄位:revenueMicros:轉換的金額價值。
選填欄位
quantityMillis:這項轉換中的項目數量。例如訂閱電子報的人數或售出的商品總數。如果未在 ACTION 轉換中指定這個欄位,Search Ads 360 會自動插入1000值。currencyCode:交易收益的幣別。根據預設,系統會假設收益是以廣告主所用幣別計算。如果您指定其他幣別,Search Ads 360 會將指定的收益金額換算成廣告主所用幣別。瞭解詳情
請使用 ISO 4217 字母 (3 個字元) 格式指定貨幣。
僅適用於交易型轉換。customMetric和customDimension:上傳轉換的其他資料,例如購買商品的運送國家/地區、產品 ID,甚至是通話時間長度。進一步瞭解如何上傳 Floodlight 自訂變數資料。deviceType:指定轉換在哪種裝置類型上發生,請參閱這個欄位接受的值清單。
JSON
POST 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": "customerTransaction73126", "conversionTimestamp": "1351196386000", "segmentationType": "FLOODLIGHT", "segmentationName": "Offline Purchase", "type": "TRANSACTION", "revenueMicros": "20000000", // 20 million revenueMicros is equivalent to $20 of revenue "currencyCode": "USD" }] }
Java
/** * Creates a TRANSACTION conversion, attributes it to a keyword only, and adds it to a List<Conversion>. * The example in the preceding section contains the uploadConversions method, * which can submit the list as an insert() request. */ private static List<Conversion> addTransactionConversionForKeyword(List<Conversion> conversions, String customerId, Long campaignId, Long adGroupId, Long criterionId, String conversionId, Long revenue, Long timeStamp) { Conversion conversion = new Conversion() .setCustomerId(customerId) .setCampaignId(campaignId) .setAdGroupId(adGroupId) .setCriterionId(criterionId) .setConversionId(conversionId) .setSegmentationType("FLOODLIGHT") .setSegmentationName("Test") .setType("TRANSACTION") .setRevenueMicros(revenue) .setCurrencyCode("USD") .setConversionTimestamp(BigInteger.valueOf(timeStamp)); conversions.add(conversion); return conversions; }
Python
def insert_conversion(service): """Create and upload a TRANSACTION conversion that is attributed to a keyword only. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().insert( 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_1378710000000', 'conversionTimestamp': '1378710000000', 'segmentationType': 'FLOODLIGHT', 'segmentationName': 'Test', 'type': 'TRANSACTION', 'revenueMicros': '20000000', // 20 million revenueMicros is equivalent to $20 of revenue 'currencyCode': 'USD' }] } ) pprint.pprint(request.execute())
上傳第三方歸因模式的資料
歸因模式會將轉換功勞分配給轉換路徑中的所有活動。舉例來說,假設消費者在完成轉換前曾點擊付費搜尋廣告、多媒體廣告和另一個付費搜尋廣告,線性歸因模式會將 33% 的轉換功勞歸因於每次點擊。
儘管 Search Ads 360 會提供歸因模式,如果您使用的是第三方服務,或者自行開發了將轉換功勞歸因於點擊的服務,仍然可以將第三方歸因資料上傳到 Search Ads 360,讓報表和 Search Ads 360 出價策略使用這項資料。
事前準備
在 Campaign Manager 中建立自訂歸因模式,然後將該模式匯入 Search Ads 360。請務必將模式命名為「External Attribution Model」(外部歸因模式)。 這樣一來,Search Ads 360 功能就能辨識出您上傳的轉換資料已套用歸因模式。瞭解詳情
必填欄位
如要將第三方歸因模式套用至轉換,請在 Conversion.insert() 要求中指定下列所有項目:
clickId:造訪的點擊 ID (區分大小寫)。在廣告主的網頁記錄中尋找點擊 ID,或使用新版 Search Ads 360 Reporting API 擷取其他轉換的conversion.click_id。Search Ads 360 會將轉換歸因於促成造訪的關鍵字、廣告和其他 Search Ads 360 物件。
Search Ads 360 產生點擊 ID 後,請至少等待 30 分鐘,再上傳含有該 ID 的轉換。 否則 Search Ads 360 API 可能無法辨識造訪。attributionModel:設為「External Attribution Model」。 瞭解詳情countMillis:要分配給這次點擊的轉換功勞量。 只有在要求也包含attributionModel欄位時才適用。請勿與
quantityMillis混淆,後者是選填欄位,用於指定轉換中的項目數量 (例如購物車交易中的商品數量)。conversionId:如果是離線轉換,廣告主會提供這個 ID。廣告主可以指定任何有意義的 ID。要求中的每筆轉換都必須指定專屬 ID,且 ID 和時間戳記的組合在廣告主的所有轉換中不得重複。如果是線上轉換,Search Ads 360 會根據廣告主的 Floodlight 指示,將dsConversionId或floodlightOrderId複製到這項屬性。conversionTimestamp:表示轉換發生的日期和時間。舉例來說,如果轉換發生在 2016 年 8 月 5 日星期五上午 11:53:22 (美國東部日光節約時間,GMT -4:00),請以 Epoch 毫秒數指定時間戳記:1470412402000。segmentationType:指定要上傳轉換的轉換系統類型。目前僅支援 Floodlight 轉換,因此這個欄位一律必須指定FLOODLIGHT。segmentationName:廣告主用來記錄轉換的 Floodlight 活動名稱。如果廣告主包含同名的活動 (如果活動屬於不同的 Floodlight 群組,就可能發生這種情況),建議您重新命名其中一個活動。
或者,您也可以在
segmentationId欄位中指定 Floodlight 活動的 ID,而不是在segmentationName欄位中指定名稱。請使用 Campaign Manager 指派給 Floodlight 活動的 ID。您可以使用新版 Search Ads 360 Reporting API 的conversion_action.floodlight_settings.activity_id欄位擷取這個 ID。Search Ads 360 在轉換要求回應中傳回的segmentationId也可接受。type:轉換類型,即ACTION或TRANSACTION。ACTION 轉換沒有金額價值,而 TRANSACTION 轉換則有。例如電子郵件名單註冊 (動作) 與電子商務購買 (交易)。如果指定
TRANSACTION,也必須指定下列欄位:revenueMicros:轉換的金額價值。
如果您有追蹤轉換收益,請務必讓模式將收益分配給轉換路徑中的每個接觸點。舉例來說,假設模式使用的是線性方法 (對每個接觸點分配相等的收益),那麼在包含 3 次廣告點擊的轉換路徑中,每次點擊會分配到 33% 的轉換收益。如果該次轉換獲得了 $100 美元的收益,請確定模式能夠分配 $33 美元的收益給每次點擊,而且 revenueMicros 針對每次點擊都只指定 $33 美元的收益。
選填欄位
quantityMillis:這項轉換中的項目數量。例如訂閱電子報的人數或售出的商品總數。如果未在 ACTION 轉換中指定這個欄位,Search Ads 360 會自動插入1000值。currencyCode:交易收益的幣別。根據預設,系統會假設收益是以廣告主所用幣別計算。如果您指定其他幣別,Search Ads 360 會將指定的收益金額換算成廣告主所用幣別。瞭解詳情
請使用 ISO 4217 字母 (3 個字元) 格式指定貨幣。
僅適用於交易型轉換。customMetric和customDimension:上傳轉換的其他資料,例如購買商品的運送國家/地區、產品 ID,甚至是通話時間長度。進一步瞭解如何上傳 Floodlight 自訂變數資料。deviceType:指定轉換在哪種裝置類型上發生,請參閱這個欄位接受的值清單。
範例
POST https://www.googleapis.com/doubleclicksearch/v2/conversion Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "kind": "doubleclicksearch#conversionList", "conversion" : [{ "clickId" : "PP5K8iI6ul7Vw09JZZDEp", // Replace with a click ID from your site "conversionId" : "test_20130906_04", "conversionTimestamp" : "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "TRANSACTION", "attributionModel": "External Attribution Model", "countMillis": "330", "revenueMicros": "33000000", // 33 million revenueMicros is equivalent to $33 of revenue "currencyCode": "USD" }] }
處理 Search Ads 360 回應
只有在要求中的所有轉換都成功驗證並上傳後,Search Ads 360 的回應才會顯示成功。
如果要求成功
如果要求成功,回應會包含每個上傳轉換的完整 Search Ads 360 內部表示法。這項表示法會使用新版 Search Ads 360 ID:客戶帳戶的客戶 ID,以及轉換歸因的廣告活動 ID、廣告群組 ID、關鍵字 (條件) ID 和廣告 ID。
以下是歸因於造訪的轉換回應範例:
{
"kind": "doubleclicksearch#conversionList",
"conversion": [
{
"customerId": "123-456-7890",
"campaignId": "14660344555",
"adGroupId": "105138634255",
"criterionId": "948710340465",
"adId": "562719339005",
"clickId": "COiYmPDTv7kCFcP0KgodOzQAAA",
"conversionId": "test_20130906_04",
"state": "ACTIVE",
"type": "TRANSACTION",
"revenueMicros": "10000000",
"currencyCode": "USD",
"segmentationType": "FLOODLIGHT",
"segmentationId": "25700000001464141",
"segmentationName": "Test",
"conversionTimestamp": "1378710000000",
"conversionModifiedTimestamp": "1383157332368",
"floodlightOrderId": "test_20130906_04",
"countMillis": "1000",
"deviceType": "DESKTOP"
},
...
]
}
回應只會包含適用於轉換的 ID。舉例來說,如果轉換僅歸因於關鍵字,則回應不會包含 clickId 和 adId。
如果要求失敗
如果有一或多項轉換無法驗證或上傳,回應會包含每項失敗轉換上傳的訊息。回應不含成功上傳轉換的訊息。
以下是未完全成功的要求回應範例:
{
"error": {
"errors": [
{
"reason": "requestValidation",
"message": "The request was not valid. Details: [0x0000011F: Advertiser conversion ID ..."
},
{
"reason": "requestValidation",
"message": "The request was not valid. Details: [0x00000101: Click ID ..."
}
]
}
}
每則失敗訊息都包含兩個重要欄位:原因和詳細錯誤訊息。原因欄位可包含 requestValidation、internalError、transactionFailed 或 lateStageRequestError。
requestValidation 錯誤
requestValidation 錯誤表示轉換上傳要求中的資料有問題 (例如轉換已上傳,或找不到 clickId)。在這類錯誤中,訊息詳細資料包含兩個項目:
- 用來識別錯誤類型的十六進位代碼。您可以在自己的指令碼中使用這段程式碼,找出錯誤。
- 驗證錯誤的說明。
如要進一步瞭解 Search Ads 360 可能傳回的轉換上傳錯誤代碼和說明,請參閱這份清單。
其他錯誤類型
所有其他類型的錯誤 (internalError、transactionFailed 或 lateStageRequestError) 都表示 Search Ads 360 發生內部問題。
回應錯誤
如果要求失敗,請稍後再重新提交整個要求呼叫。Search Ads 360 會針對已上傳的轉換回報 requestValidation 錯誤,但會嘗試上傳其餘轉換。
如果重新提交後仍看到錯誤,請參閱疑難排解一節,瞭解如何處理。