新增轉換

呼叫 Conversion.insert() 方法，新增一或多項轉換。如要正確歸因轉換，您的要求必須指定廣告主用於回報離線轉換的 Floodlight 活動名稱，以及導致轉換的關鍵字、廣告和點擊 ID (可能)。如要瞭解如何取得 Search Ads 360 ID，請參閱「Search Ads 360 ID 和轉換」。

如要瞭解上傳歷來轉換資料的限制，請參閱 Search Ads 360 說明中心。

如果 Conversion.insert() 要求指定多項轉換，Search Ads 360 會盡可能上傳每項轉換，而不是將整個批次視為全有或全無的交易。如果批次中的部分轉換無法上傳，其他轉換可能仍會成功上傳。轉換上傳作業可能因要求無效，或暫時性網路或系統故障而失敗。因此，我們建議您讀取每個插入轉換的回應，確保上傳成功。

資料上傳後要多久才能使用？

如果您為轉換指定的時間戳記為今天或昨天，在您上傳後的 1 小時內，Search Ads 360 UI 中就會出現轉換的指標。conversionTimestamp如果您指定的conversionTimestamp早於昨天，指標會在數小時內更新。

將所有轉換的時間戳記轉換為 Epoch 時間 (也稱為 Unix 時間)。

我是否能透過 API 建立 Floodlight 活動？

如果廣告主尚未建立 Floodlight 活動來追蹤離線轉換， 您可以 使用 Campaign Manager API 建立活動。您無法使用 API 指定 Floodlight 活動主要用於離線轉換，但如果出價策略會使用轉換資料，建議您這麼做。

我們建議您使用 API 建立 Floodlight 活動後，請 Search Ads 360 使用者登入 Search Ads 360，並變更活動設定，指出轉換的主要來源是離線活動。

新增轉換的最佳做法

我們建議您在新增轉換時，按照下列最佳做法行事：

  1. 請 Search Ads 360 使用者登入 Search Ads 360，並變更用於回報離線轉換的每個 Floodlight 活動設定。設定應指出轉換的主要來源為離線活動。如需操作說明，請參閱 Search Ads 360 說明中心。

  2. 盡快上傳可用的轉換資料。如要 將轉換歸給特定造訪，請在該次造訪發生後等待至少 6 小時，然後再上傳轉換。如果您在造訪發生後的 6 小時內即上傳造訪，Search Ads 360 可能會無法辨識該次造訪的點擊 ID。在極少數情況下，您可能需要等待最多 24 小時，Search Ads 360 才能辨識點擊 ID。

    確認每次上傳要求均包含最新的轉換資料。在單一上傳要求中，項目可以不依時間順序排列。不過，如果您之後才在別的要求中上傳較舊的轉換資料，出價策略可能無法將該資料納入考量。

傳送插入要求

您可以傳送 Conversion.insert() 要求，執行下列任一操作：

  • 將轉換歸因於特定造訪
  • 只將轉換歸因於關鍵字

Conversion.insert() 請求中必須填寫的欄位，取決於您要將轉換歸給的事件或項目。以下各節列出可將轉換歸因於的每個事件或項目的必要和選用欄位。

將轉換歸因於特定造訪

當顧客點選一或多則廣告並前往廣告主的網站時， Search Ads 360 會將廣告主網站上的使用者工作階段視為一次造訪。 如要將轉換歸因於某次造訪，請在 Conversion.insert() 要求中指定下列項目：

必填欄位

  • clickId：區分大小寫的點擊 ID，代表該次造訪。在廣告主的網站記錄中尋找點擊 ID 或列出轉換，然後使用來自其他轉換的點擊 ID。Search Ads 360 會將轉換歸因於促成造訪的關鍵字、廣告和其他 Search Ads 360 物件。
    等待至少 6 小時，讓 Search Ads 360 產生點擊 ID，然後再上傳轉換。 如果收到「找不到點擊 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 使用者介面或報表 API)。如果報表時間範圍內，至少有一項轉換歸因於 Floodlight 活動，報表就會顯示 Search Ads 360 ID。

  • type：轉換類型，即 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 ID，只指定關鍵字的 ID 和其他幾個欄位：

必填欄位

  • 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 使用者介面或報表 API)。如果報表時間範圍內，至少有一項轉換歸因於 Floodlight 活動，報表就會顯示 Search Ads 360 ID。

  • type：轉換類型，即 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。請務必將模式命名為「外部歸因模式」。 這樣一來，Search Ads 360 功能就能識別您上傳的轉換資料已套用歸因模式。瞭解詳情

必填欄位

如要將第三方歸因模式套用至轉換，請在 Conversion.insert() 要求中指定下列所有項目：

  • clickId：區分大小寫的點擊 ID，代表該次造訪。在廣告主的網站記錄中尋找點擊 ID 或列出轉換，然後使用來自其他轉換的點擊 ID。Search Ads 360 會將轉換歸因於促成造訪的關鍵字、廣告和其他 Search Ads 360 物件。
    等待至少 30 分鐘，讓 Search Ads 360 產生點擊 ID，再上傳含有該 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 使用者介面或報表 API)。如果報表時間範圍內，至少有一項轉換歸因於 Floodlight 活動，報表就會顯示 Search Ads 360 ID。

  • type：轉換類型，即 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 內部表示法，例如廣告活動 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 錯誤，但會嘗試上傳其餘轉換。

如果重新提交後仍看到錯誤，請參閱「疑難排解」一節，瞭解如何繼續操作。