呼叫 Conversion.insert()
方法,新增一或多個轉換。為正確歸因轉換,您的要求必須指定廣告主用來回報離線轉換的 Floodlight 活動名稱,以及關鍵字、廣告和可能導致轉換的點擊 ID。如要瞭解如何取得 Search Ads 360 ID,請參閱「Search Ads 360 ID 和轉換」一文。
如要瞭解上傳歷來轉換資料的限制,請前往 Search Ads 360 說明中心。
如果您的 Conversion.insert()
要求指定多個轉換,Search Ads 360 會盡力上傳每個轉換,而不是將整個批次上傳為全有或全無的交易。如果某批轉換無法上傳,其他轉換可能仍能順利上傳。轉換上傳作業可能會因無效要求或暫時性網路或系統故障而失敗。因此,建議您讀取回應,確認每個插入的轉換資料是否已成功上傳。
資料上傳後要多久才能使用?
如果您為轉換指定的
conversionTimestamp
為今天或昨天,在您上傳後的 1 小時內,廣告活動管理 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 可能會無法辨識該次造訪的點擊 ID。在少數情況下,您可能需要等待最多 24 小時,Search Ads 360 才能辨識 clickId。
確認每次上傳要求均包含最新的轉換資料。在單一上傳要求中,項目不必按照時間順序排列。不過,如果您之後才在別的要求中上傳較舊的轉換資料,出價策略可能無法將該資料納入考量。
傳送插入要求
您可以傳送 Conversion.insert()
要求來執行下列任一操作:
- 將轉換歸因於特定造訪
- 只將轉換歸因於某個關鍵字
Conversion.insert()
要求中需要的欄位取決於您要將轉換歸給哪個事件或項目。以下各節會列出可歸因於轉換的每個事件或項目的必要和選用欄位。
將轉換歸因於特定造訪
當客戶點按一或多則廣告並前往廣告主網站時,Search Ads 360 會將廣告主網站上的使用者工作階段視為一次造訪。如要將轉換歸因於造訪,請在 Conversion.insert()
要求中指定下列項目:
必填欄位
clickId
:訪客的 點擊 ID (區分大小寫)。在廣告主的網頁記錄中查看點擊 ID 或列出轉換,然後使用其他轉換的點擊 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 群組,就可能發生這種情況),建議您重新命名其中一個活動。
或者,如果您知道 Search Ads 360 已指派給 Floodlight 活動的 ID,可以直接在
segmentationId
中指定 ID,而非在segmentationName
欄位中指定名稱。(Campaign Manager 也會為 Floodlight 活動指派 ID,但 Campaign Manager ID 與 Search Ads 360 ID 不同,因此無法用於歸因轉換)。如要查看 Floodlight 活動的 Search Ads 360 ID,請下載轉換報表 (從 Search Ads 360 UI 或報表 API)。如果報表時間範圍內至少有一次轉換歸因於 Floodlight 活動,報表中就會顯示 Search Ads 360 ID。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())
只將轉換歸因於某個關鍵字
如果您主要想將轉換歸因於關鍵字 (而非廣告),可以省略大部分 Search Ads 360 識別碼,只指定關鍵字的識別碼和其他幾個欄位:
必填欄位
criterionId
:這是關鍵字 ID。如要取得criterionId
,請在到達網頁網址中加入TrackerId
巨集。如要瞭解如何取得關鍵字 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 群組,就可能發生這種情況),建議您重新命名其中一個活動。
或者,如果您知道 Search Ads 360 已指派給 Floodlight 活動的 ID,可以直接在
segmentationId
中指定 ID,而非在segmentationName
欄位中指定名稱。(Campaign Manager 也會為 Floodlight 活動指派 ID,但 Campaign Manager ID 與 Search Ads 360 ID 不同,因此無法用於歸因轉換)。如要查看 Floodlight 活動的 Search Ads 360 ID,請下載轉換報表 (從 Search Ads 360 UI 或報表 API)。如果報表時間範圍內至少有一次轉換歸因於 Floodlight 活動,報表中就會顯示 Search Ads 360 ID。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" : [{ "criterionId": "43700003491981017", // 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, Long criterionId, String conversionId, Long revenue, Long timeStamp) { Conversion conversion = new Conversion() .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': [{ 'criterionId': '43700004289911004', // 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 或列出轉換,然後使用其他轉換的點擊 ID。Search Ads 360 會將轉換歸因於產生造訪的關鍵字、廣告和其他 Search Ads 360 物件。
等待 Search Ads 360 產生點擊 ID 後,再等待至少 30 分鐘,然後上傳含有該 ID 的轉換。否則 Search Ads 360 API 可能無法辨識造訪。attributionModel
:設為「外部歸因模式」。 瞭解詳情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 群組,就可能發生這種情況),建議您重新命名其中一個活動。
或者,如果您知道 Search Ads 360 已指派給 Floodlight 活動的 ID,可以直接在
segmentationId
中指定 ID,而非在segmentationName
欄位中指定名稱。(Campaign Manager 也會為 Floodlight 活動指派 ID,但 Campaign Manager ID 與 Search Ads 360 ID 不同,因此無法用於歸因轉換)。如要查看 Floodlight 活動的 Search Ads 360 ID,請下載轉換報表 (從 Search Ads 360 UI 或報表 API)。如果報表時間範圍內至少有一次轉換歸因於 Floodlight 活動,報表中就會顯示 Search Ads 360 ID。type
:轉換類型,即ACTION
或TRANSACTION
。ACTION 轉換沒有金額價值,但 TRANSACTION 轉換有。例如電子郵件名單註冊 (動作) 和電子商務購物 (交易)。如果您指定
TRANSACTION
,也必須指定下列欄位:revenueMicros
:轉換的金額。
如果您有追蹤轉換收益,請務必讓模式將收益分配給轉換路徑中的每個接觸點。舉例來說,假設模式使用的是線性方法 (對每個接觸點分配相等的收益),那麼在包含 3 次廣告點擊的轉換路徑中,每次點擊會分配到 33% 的轉換功勞。如果該次轉換獲得了 $100 美元的收益,請確定模式能夠分配 $33 美元的收益給每次點擊,而且針對每次點擊,您都只能指定 $33 美元的收益。revenueMicros
選填欄位
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 內部表示法,例如廣告活動 ID、廣告群組 ID 和關鍵字 (條件) ID。
{ "kind": "doubleclicksearch#conversionList", "conversion": [ { "agencyId": "12300000000000456", "advertiserId": "45600000000010291", "engineAccountId": "700000000042441", "campaignId": "71700000002044839", "adGroupId": "58700000032026064", "criterionId": "43700004289911004", "adId": "0", "dsConversionId": "48719131694768384", "conversionId": "test_1383157331951", "state": "ACTIVE", "type": "TRANSACTION", "revenueMicros": "20000000", "currencyCode": "USD", "segmentationType": "FLOODLIGHT", "segmentationId": "25700000001464141", "segmentationName": "Test", "conversionTimestamp": "1378710000000", "conversionModifiedTimestamp": "1383157332368" }, ... ] }
如果要求失敗
如果一或多筆轉換無法驗證或上傳,回應會包含每筆轉換上傳失敗的訊息。回應中不會包含有關成功上傳的轉換訊息。
以下是對未完全成功的要求的回應範例:
{ "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 錯誤,但會嘗試上傳剩餘的轉換。
如果重新提交後仍出現錯誤,請參閱「疑難排解」一節,瞭解如何繼續操作。