呼叫 Conversion.insert()
方法,即可新增一或多項轉換。為了正確歸因轉換,您的要求
請指定廣告客戶用來製作報表的 Floodlight 活動名稱
離線轉換,以及關鍵字、廣告的 ID,以及促成轉換的點擊。適用對象
瞭解如何取得 Search Ads 360 ID,請參閱 Search Ads 360 ID 和
轉換。
如要瞭解上傳歷來轉換資料的相關限制,請前往 Search Ads 360 說明中心。
如果您的 Conversion.insert()
要求指定多次轉換
Search Ads 360 會盡可能嘗試上傳每次轉換,而非
將整個批次上傳為「沒有」或「否」的交易。如果目標地區產生的部分轉換
批次上傳失敗,其他則可能仍可成功上傳。轉換上傳可能失敗
。因此,我們
建議您針對每個插入的轉換閱讀回應
確認上傳成功
資料上傳後要多久才能使用?
如果指定
conversionTimestamp
(前一天或昨天) 發生的轉換指標
就會在上傳後的一小時內,顯示在 Search Ads 360 使用者介面中。如果發生以下情況:
指定的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 並變更設定 。這些設定應 表示主要轉換來源為離線活動。詳情請參閱 Search Ads 360 說明中心 一文。
盡快上傳可用的轉換資料。如果您是 將轉換歸因於特定造訪,請等待至少 30 分鐘後 如果造訪的 ClickID 為何,Search Ads 360 可能無法辨識該次造訪的 clickID 值 才剛好在造訪後 30 分鐘內就上傳。在極少數的情況下,您可能需要 最多等待 4 小時,Search Ads 360 才能辨識 clickId。
確認每次上傳要求均包含最新的轉換資料。在單一 上傳要求,如果資料沒有按照時間順序排列,也沒有問題。但出價策略 如果您後來在其他要求中上傳更早以前的轉換,將無法納入考量。
如果您超過 24 小時才上傳 Floodlight 活動的轉換資料, 傳送 供應情形時間戳記。
可用性時間戳記應為下列其中一個值:
- 如果在過去 24 小時內記錄了轉換但尚未上傳 但時間戳記應為上次上傳轉換的時間 這樣 Search Ads 360 就會得知可能發生轉換 ,但你尚未提供相關資料。出價策略,以及 其他自動化系統只考量到最近發生的成效記錄 您上傳的轉換
- 如果過去 24 小時內沒有發生任何轉換,時間戳記應為 目前的時間和日期。這樣一來,Search Ads 360 就不會 過去 24 小時內發生的轉換次數。出價策略和其他自動化功能 系統會將過去 24 小時 (一個無轉換的全天) 納入計算, 部分成效記錄
傳送插入要求
您可以傳送 Conversion.insert()
要求,執行下列任一操作:
- 將轉換歸因於特定造訪
- 只將轉換歸因於關鍵字
Conversion.insert()
要求中的必填欄位取決於
這些轉換功勞歸因於哪個事件或項目以下各節列出了
以及選填欄位,能夠將轉換功勞歸給各個事件或項目
將轉換歸因於特定造訪
當客戶點擊一或多則廣告進入廣告客戶的網站時,
Search Ads 360 會將廣告客戶網站上的使用者工作階段視為一次造訪。
如要將轉換歸因於某次造訪,請在 Conversion.insert()
中指定以下項目
要求:
必填欄位
clickId
:造訪會區分大小寫的點擊 ID。查看 點擊 ID 或列出轉換的廣告客戶網頁記錄,然後使用 其他轉換的點擊 IDSearch Ads 360 會將轉換歸因於 關鍵字、廣告和其他 Search Ads 360 物件 產生造訪的次數
請等待至少 30 分鐘 Search Ads 360 會產生點擊 ID 以上傳轉換。 如果收到「找不到點擊 ID」錯誤,等待 4 小時後再上傳 再次發生轉換。 所有轉換應在產生轉換後的 90 天內上傳 由系統產生點擊 ID。 否則 Search Ads 360 API 可能無法識別該次造訪。conversionId
:如果是離線轉換,廣告客戶請提供這個 ID。廣告客戶可以 並指定好記的任何 ID請求中的每次轉換都必須指定專屬 ID、 且廣告客戶中所有轉換的 ID 和時間戳記組合都不得重複。 Search Ads 360 會針對線上轉換複製dsConversionId
或floodlightOrderId
可能會加到這項資源中conversionTimestamp
:代表 轉換是否發生。舉例來說, 轉換發生在 2016 年 8 月 5 日星期五上午 11:53:22 (GMT -4:00)、 指定時間戳記 (以 Epoch 時間計算的毫秒為單位):1470412402000
。segmentationType
:指明您要上傳的轉換系統類型 轉換目標。由於系統目前僅支援 Floodlight 轉換,因此這個欄位 一律必須指定FLOODLIGHT
。segmentationName
:廣告客戶所屬的 Floodlight 活動名稱 回報轉換。如果廣告客戶包含相同名稱的活動 ( 建議採取的行動是 重新命名其中一項活動。
或者,如果您知道 Search Ads 360 指派給 Floodlight 活動的 ID, 可以在
segmentationId
中指定 ID,而不是在segmentationName
欄位。(Campaign Manager 也會為 Floodlight 活動指派 ID, 但 Campaign Manager ID 與 Search Ads 360 ID 不同,因此無法用於歸因 conversions.)如要查看 Floodlight 活動的 Search Ads 360 ID,請下載 轉換報表 (來自 Search Ads 360 使用者介面或報表 API)。如果在出價策略期間,系統有至少一次轉換已歸因於該 Floodlight 活動 報表的時間範圍會顯示 Search Ads 360 ID。type
:轉換類型,也就是ACTION
或TRANSACTION
。ACTION 轉換沒有貨幣價值,但 TRANSACTION 轉換可以。例如電子郵件名單註冊 (ACTION) 和 電子商務購買 (TRANSACTION)。如果指定
TRANSACTION
, 您也需要指定下列欄位:revenueMicros
:轉換的金額。
選填欄位
quantityMillis
:該次轉換中的項目數量。舉例來說, 訂閱電子報或售出商品總數量的人數。 如果您未針對 ACTION 轉換指定這個欄位,Search Ads 360 會自動插入 值為1000
。currencyCode
:交易收益的貨幣。根據預設,收益為 預設為廣告客戶的貨幣。如果指定不同的貨幣,Search Ads 360 就會 將指定收益金額換算成廣告客戶的貨幣。 瞭解詳情
請使用 ISO 4217 字母 (3 個字元) 即可指定貨幣。
僅適用於 TRANSACTION 轉換。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。新增TrackerId
即可取得criterionId
巨集加入到達網頁網址。如要瞭解如何取得關鍵字 ID,請參閱 Search Ads 360 ID 和 轉換。conversionId
:如果是離線轉換,廣告客戶請提供這個 ID。廣告客戶可以 並指定好記的任何 ID請求中的每次轉換都必須指定專屬 ID、 且廣告客戶中所有轉換的 ID 和時間戳記組合都不得重複。 Search Ads 360 會針對線上轉換複製dsConversionId
或floodlightOrderId
可能會加到這項資源中conversionTimestamp
:代表 轉換是否發生。舉例來說, 轉換發生在 2016 年 8 月 5 日星期五上午 11:53:22 (GMT -4:00)、 指定時間戳記 (以 Epoch 時間計算的毫秒為單位):1470412402000
。segmentationType
:指明您要上傳的轉換系統類型 轉換目標。由於系統目前僅支援 Floodlight 轉換,因此這個欄位 一律必須指定FLOODLIGHT
。segmentationName
:廣告客戶所屬的 Floodlight 活動名稱 回報轉換。如果廣告客戶包含相同名稱的活動 ( 建議採取的行動是 重新命名其中一項活動。
或者,如果您知道 Search Ads 360 指派給 Floodlight 活動的 ID, 可以在
segmentationId
中指定 ID,而不是在segmentationName
欄位。(Campaign Manager 也會為 Floodlight 活動指派 ID, 但 Campaign Manager ID 與 Search Ads 360 ID 不同,因此無法用於歸因 conversions.)如要查看 Floodlight 活動的 Search Ads 360 ID,請下載 轉換報表 (來自 Search Ads 360 使用者介面或報表 API)。如果在出價策略期間,系統有至少一次轉換已歸因於該 Floodlight 活動 報表的時間範圍會顯示 Search Ads 360 ID。type
:轉換類型,也就是ACTION
或TRANSACTION
。ACTION 轉換沒有貨幣價值,但 TRANSACTION 轉換可以。例如電子郵件名單註冊 (ACTION) 和 電子商務購買 (TRANSACTION)。如果指定
TRANSACTION
, 您也需要指定下列欄位:revenueMicros
:轉換的金額。
選填欄位
quantityMillis
:該次轉換中的項目數量。舉例來說, 訂閱電子報或售出商品總數量的人數。 如果您未針對 ACTION 轉換指定這個欄位,Search Ads 360 會自動插入 值為1000
。currencyCode
:交易收益的貨幣。根據預設,收益為 預設為廣告客戶的貨幣。如果指定不同的貨幣,Search Ads 360 就會 將指定收益金額換算成廣告客戶的貨幣。 瞭解詳情
請使用 ISO 4217 字母 (3 個字元) 即可指定貨幣。
僅適用於 TRANSACTION 轉換。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 提供 歸因模式 (如果您使用第三方服務或 您可以將第三方歸因資料上傳到 Google Search Ads 360,並在報表和 Search Ads 360 出價策略中使用這項資料。
事前準備
在 Campaign Manager 中建立自訂歸因模式,然後匯入至 Search Ads 360。請務必將模式命名為「外部歸因模式」。 這樣 Search Ads 360 功能就能辨識歸因模式已套用到 上傳的轉換資料。瞭解詳情 更多內容
必填欄位
如要為轉換套用第三方歸因模式,請在
您的 Conversion.insert()
要求:
clickId
:造訪會區分大小寫的點擊 ID。查看 點擊 ID 或列出轉換的廣告客戶網頁記錄,然後使用 其他轉換的點擊 IDSearch Ads 360 會將轉換歸因於 關鍵字、廣告和其他 Search Ads 360 物件 產生造訪的次數
請等待至少 30 分鐘 在上傳含有這個 ID 的轉換之前,Search Ads 360 會先產生點擊 ID。 否則 Search Ads 360 API 可能無法識別該次造訪。attributionModel
:設為「External Attribution Model」(外部歸因模式)。 瞭解詳情countMillis
:對這次點擊的影響的轉換功勞數量。 僅適用於要求同時包含attributionModel
欄位的情況。請不要將此情況與
quantityMillis
混淆,後者是指定 轉換中的項目數量 (例如購物車中的項目數量) 購買)。conversionId
:如果是離線轉換,廣告客戶請提供這個 ID。廣告客戶可以 並指定好記的任何 ID請求中的每次轉換都必須指定專屬 ID、 且廣告客戶中所有轉換的 ID 和時間戳記組合都不得重複。 Search Ads 360 會針對線上轉換複製dsConversionId
或floodlightOrderId
可能會加到這項資源中conversionTimestamp
:代表 轉換是否發生。舉例來說, 轉換發生在 2016 年 8 月 5 日星期五上午 11:53:22 (GMT -4:00)、 指定時間戳記 (以 Epoch 時間計算的毫秒為單位):1470412402000
。segmentationType
:指明您要上傳的轉換系統類型 轉換目標。由於系統目前僅支援 Floodlight 轉換,因此這個欄位 一律必須指定FLOODLIGHT
。segmentationName
:廣告客戶所屬的 Floodlight 活動名稱 回報轉換。如果廣告客戶包含相同名稱的活動 ( 建議採取的行動是 重新命名其中一項活動。
或者,如果您知道 Search Ads 360 指派給 Floodlight 活動的 ID, 可以在
segmentationId
中指定 ID,而不是在segmentationName
欄位。(Campaign Manager 也會為 Floodlight 活動指派 ID, 但 Campaign Manager ID 與 Search Ads 360 ID 不同,因此無法用於歸因 conversions.)如要查看 Floodlight 活動的 Search Ads 360 ID,請下載 轉換報表 (來自 Search Ads 360 使用者介面或報表 API)。如果在出價策略期間,系統有至少一次轉換已歸因於該 Floodlight 活動 報表的時間範圍會顯示 Search Ads 360 ID。type
:轉換類型,也就是ACTION
或TRANSACTION
。ACTION 轉換沒有貨幣價值,但 TRANSACTION 轉換可以。例如電子郵件名單註冊 (ACTION) 和 電子商務購買 (TRANSACTION)。如果指定
TRANSACTION
, 您也需要指定下列欄位:revenueMicros
:轉換的金額。
如果您有追蹤轉換收益,請務必讓模式將收益分配給每次 轉換路徑中的各個接觸點例如,假設模型採用線性方法 (將收益平均分配給每個接觸點),也就是符合下列條件的轉換路徑: 3 次廣告點擊,則每次點擊會歸給 33% 的轉換。如果轉換 可獲得 NT $3,000 元的收益,請務必讓模式平均分配 NT $990 元的收益給每次點擊 並確認 revenueMicros 只會指定每次點擊的 $33 美元收益。
選填欄位
quantityMillis
:該次轉換中的項目數量。舉例來說, 訂閱電子報或售出商品總數量的人數。 如果您未針對 ACTION 轉換指定這個欄位,Search Ads 360 會自動插入 值為1000
。currencyCode
:交易收益的貨幣。根據預設,收益為 預設為廣告客戶的貨幣。如果指定不同的貨幣,Search Ads 360 就會 將指定收益金額換算成廣告客戶的貨幣。 瞭解詳情
請使用 ISO 4217 字母 (3 個字元) 即可指定貨幣。
僅適用於 TRANSACTION 轉換。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)。在本 錯誤類型,則訊息 details 包含兩個項目:
- 識別錯誤類型的十六進位代碼。您可以將程式碼 以便找出錯誤
- 驗證錯誤的說明。
詳情請參閱 程式碼清單和 說明。
其他錯誤類型
所有其他類型的錯誤 (internalError、transactionFailed、 lateStageRequestError) 表示 Search Ads 360。
回應錯誤
如果要求失敗,請稍後再重新提交整個要求呼叫。Search Ads 360 如果發生轉換,系統會回報該次轉換的 requestValidation 錯誤 但會試著上傳剩餘的轉換資料。
如果重新提交後仍發生錯誤,請查看 疑難排解 一節,瞭解如何繼續。