建立轉換動作

本指南列出可使用 Google Ads API 建立的不同類型轉換動作，並說明如何將這些轉換動作對應至 Google Ads 網頁介面，以及詳細的程式碼範例，說明如何建立新的轉換動作。

如要評估轉換，請為要追蹤的轉換動作的 type 設定 ConversionAction。舉例來說，線上購物和電話需要不同的轉換動作。

在 API 中設定新的轉換動作的最佳做法，就是使用下方的新增轉換動作程式碼範例。這個範例會為您處理所有背景驗證工作，並逐步引導您建立 ConversionAction。

您也必須採取額外步驟才能追蹤大多數轉換動作。舉例來說，如要追蹤網站上的轉換，您必須在網站的轉換頁中加入稱為「代碼」的程式碼片段。如需瞭解其他轉換動作要求，請參閱這篇說明中心文章。

網站轉換

網站轉換可讓您追蹤網站動作，例如線上銷售、連結點擊、網頁瀏覽和註冊。

如要追蹤網站上的轉換，您必須建立 ConversionAction，並將 ConversionActionType 設為 WEBPAGE，然後在網站的轉換頁面中加入稱為「代碼」的程式碼片段。

ConversionAction 包含多種網站轉換，在 API 中可透過 ConversionAction 的 tag_snippets 欄位中列出的每個 TagSnippet 中的 type 欄位加以區分。

TagSnippet 會提供追蹤程式碼，您必須將其納入網站，才能追蹤轉換動作。網站和電話號碼點擊轉換需要使用 event_snippet，應放置在表示轉換動作的網頁上，例如結帳確認或待開發客戶表單提交頁面，以及 global_site_tag，必須安裝在網站的每個網頁上。您可以使用 ConversionActionService 擷取這兩個屬性。如要進一步瞭解如何標記網頁，請前往說明中心。

下表列出 Google Ads 網頁介面中每個來源的對應 API 參數：

應用程式轉換

應用程式轉換可讓您追蹤透過 Google Play 商店安裝行動應用程式或進行應用程式內購。

下表列出 Google Ads 網頁介面中每個來源的對應 ConversionActionType API 參數：

如果您想使用 Google Analytics 4 資源或第三方應用程式分析追蹤其他行動應用程式動作，請參閱「其他轉換動作類型」。

來電轉換

來電轉換追蹤功能可讓您追蹤廣告帶來的來電、撥打網站上的電話號碼，以及點按行動網站上的電話號碼。

下表列出 Google Ads 網頁介面中每個來源的對應 ConversionActionType API 參數：

CLICK_TO_CALL 類型與 AD_CALL 類型不同，因為它不會追蹤實際的來電。CLICK_TO_CALL 只會追蹤行動裝置上電話號碼的點擊次數。當您無法使用 Google 轉接號碼追蹤電話時，這項功能就很實用。

AD_CALL

AD_CALL 轉換動作會在 Google Ads 網頁介面中顯示為「廣告的來電」轉換。建立 AD_CALL 轉換動作後，請在建立 CallAsset 時，在 call_conversion_action 欄位中指定其資源名稱。來電素材資源可讓您直接在廣告中顯示電話號碼。

只要通話時間超過指定的持續時間，就會記錄為轉換。預設值為 60 秒。

WEBSITE_CALL

WEBSITE_CALL 轉換動作會在 Google Ads 網頁介面中顯示為「網站來電」轉換。

與 AD_CALL 不同，這個追蹤器需要在網站上加入 event_snippet 和 global_site_tag，才能擷取動態 Google 轉接號碼，以便追蹤網站上列出的電話號碼。此外，您必須設定通話素材資源，並在客戶、廣告活動或廣告群組層級連結。

匯入離線轉換

下表列出 Google Ads 網頁介面中各個來源的對應 ConversionActionType API 參數，以及各個特定轉換動作類型的說明文件連結：

網站強化轉換

網站強化轉換可讓您在轉換事件發生後的 24 小時內，傳送 WEBPAGE 轉換動作的第一方轉換資料，而非在同一時間傳送。這樣一來，您就能從多種來源 (例如顧客資料庫或客戶關係管理系統) 找出第一方資料。

其他轉換動作類型

Google Ads API 可在報表中提供其他類型的轉換動作，但可能會限制或禁止建立或修改這些動作。

SKAdNetwork 轉換

如果您執行 iOS 應用程式廣告活動，且已導入 SKAdNetwork，您可以使用下列資源，存取向 Google 提供的 SKAdNetwork 資料 (Customer 和 Campaign 層級)：

您也可以透過 CustomerSkAdNetworkConversionValueSchema，為特定已連結的 iOS 應用程式客戶儲存 SKAdNetwork 轉換價值對應項目。

#!/usr/bin/env python
# Copyright 2019 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    """Adds a keyword plan, campaign, ad group, etc. to the customer account.

    Also handles errors from the API and prints them.

    Args:
        client: An initialized instance of GoogleAdsClient
        customer_id: A str of the customer_id to use in requests.
    """

    res = update_skan_cv_schema(
        client, customer_id, "my_app_id", "account_link_id"
    )
    print(res)

def update_skan_cv_schema(client, customer_id, app_id, account_link_id):
    skan_service = client.get_service(
        "CustomerSkAdNetworkConversionValueSchemaService"
    )

    req = client.get_type(
        "MutateCustomerSkAdNetworkConversionValueSchemaRequest"
    )
    operation = client.get_type(
        "CustomerSkAdNetworkConversionValueSchemaOperation"
    )
    schema_instance = client.get_type(
        "CustomerSkAdNetworkConversionValueSchema"
    )

    new_schema = operation.update
    new_schema.resource_name = (
        skan_service.customer_sk_ad_network_conversion_value_schema_path(
            "customer_id", "account_link_id"
        )
    )
    new_schema.schema.app_id = app_id
    new_schema.schema.measurement_window_hours = 48

    skan_cv_mapping = (
        schema_instance.SkAdNetworkConversionValueSchema.FineGrainedConversionValueMappings()
    )
    skan_cv_mapping.fine_grained_conversion_value = 0  # 0 - 63
    skan_cv_mapping.conversion_value_mapping.min_time_post_install_hours = 0
    skan_cv_mapping.conversion_value_mapping.max_time_post_install_hours = 48

    skan_cv_event = schema_instance.SkAdNetworkConversionValueSchema.Event()
    skan_cv_event.mapped_event_name = "TEST"
    skan_cv_event.event_revenue_value = 10

    skan_cv_mapping.conversion_value_mapping.mapped_events.append(skan_cv_event)
    new_schema.schema.fine_grained_conversion_value_mappings.append(
        skan_cv_mapping
    )

    req.operation = operation
    req.customer_id = customer_id

    res = skan_service.mutate_customer_sk_ad_network_conversion_value_schema(
        req
    )
    return res

if __name__ == "__main__":
    # GoogleAdsClient will read the google-ads.yaml configuration file in the
    # home directory if none is specified.
    googleads_client = GoogleAdsClient.load_from_storage(
        version="v18"
    )

    parser = argparse.ArgumentParser(
        description="Creates a keyword plan for specified customer."
    )
    # The following argument(s) should be provided to run the example.
    parser.add_argument(
        "-c",
        "--customer_id",
        type=str,
        required=True,
        help="The Google Ads customer ID.",
    )
    args = parser.parse_args()

    try:
        main(googleads_client, args.customer_id)
    except GoogleAdsException as ex:
        print(
            f'Request with ID "{ex.request_id}" failed with status '
            f'"{ex.error.code().name}" and includes the following errors:'
        )
        for error in ex.failure.errors:
            print(f'\tError with message "{error.message}".')
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)
  

Google Analytics

來自已連結 Google Analytics 資源的轉換會具有下列 type 值之一：

• GA4 資源轉換：

  • GOOGLE_ANALYTICS_4_CUSTOM
  • GOOGLE_ANALYTICS_4_PURCHASE

  您也可以從 google_analytics_4_settings 欄位擷取 GA4 資源 ID、資源名稱和事件名稱。

• 通用 Analytics 資源轉換：

  • UNIVERSAL_ANALYTICS_GOAL
  • UNIVERSAL_ANALYTICS_TRANSACTION

您可以對 GA4 資源轉換進行下列變更：

• 將 GA4 資源中的轉換匯入 Google Ads 帳戶，方法是將 status 欄位從 HIDDEN 修改為 ENABLED。
• 修改其 primary_for_goal 和 category 欄位，指出該欄位應如何影響 Google Ads 出價和報表。
• 更新其 name 或 value_settings。
• 使用 remove 作業從 Google Ads 帳戶中移除轉換。

若嘗試修改匯入的 GA4 轉換的其他屬性，或任何匯入的通用 Analytics 轉換屬性，都會導致 MUTATE_NOT_ALLOWED 錯誤。您只能使用 Google Ads 使用者介面進行這些變更。

Firebase 和第三方應用程式數據分析

如要匯入第三方應用程式數據分析或 Firebase 轉換，請使用 ConversionActionService 的 mutate 方法，將 ConversionAction 的 status 從 HIDDEN 變更為 ENABLED。這些轉換動作不支援更新 app_id。

• FIREBASE_ANDROID_FIRST_OPEN
• FIREBASE_ANDROID_IN_APP_PURCHASE
• FIREBASE_ANDROID_CUSTOM
• FIREBASE_IOS_FIRST_OPEN
• FIREBASE_IOS_IN_APP_PURCHASE
• FIREBASE_IOS_CUSTOM
• THIRD_PARTY_APP_ANALYTICS_ANDROID_FIRST_OPEN
• THIRD_PARTY_APP_ANALYTICS_ANDROID_IN_APP_PURCHASE
• THIRD_PARTY_APP_ANALYTICS_ANDROID_CUSTOM
• THIRD_PARTY_APP_ANALYTICS_IOS_FIRST_OPEN
• THIRD_PARTY_APP_ANALYTICS_IOS_IN_APP_PURCHASE
• THIRD_PARTY_APP_ANALYTICS_IOS_CUSTOM

商店銷售：上傳至轉換動作並產生報表

雖然您無法使用 Google Ads API 建立 STORE_SALES 或 STORE_SALES_DIRECT_UPLOAD 轉換動作，但 API 支援上傳商店銷售交易。

• STORE_SALES
• STORE_SALES_DIRECT_UPLOAD

唯讀轉換動作類型

下列轉換動作類型在 Google Ads API 中為唯讀，僅供報表使用。

• ANDROID_APP_PRE_REGISTRATION
• ANDROID_INSTALLS_ALL_OTHER_APPS
• FLOODLIGHT_ACTION
• FLOODLIGHT_TRANSACTION
• GOOGLE_HOSTED
• LEAD_FORM_SUBMIT
• SALESFORCE
• SEARCH_ADS_360
• SMART_CAMPAIGN_AD_CLICKS_TO_CALL
• SMART_CAMPAIGN_MAP_CLICKS_TO_CALL
• SMART_CAMPAIGN_MAP_DIRECTIONS
• SMART_CAMPAIGN_TRACKED_CALLS
• STORE_VISITS
• WEBPAGE_CODELESS

不明

如果 Google Ads 帳戶包含其他類型的轉換動作，您可能會發現查詢和報表會傳回 ConversionAction.type 為 UNKNOWN 的轉換動作。API 不支援管理這些轉換動作，但會在報表中傳回這些動作，以便針對 metrics.conversions 和 metrics.conversions_value 等主要轉換指標提供完整結果。

程式碼範例

以下程式碼範例將逐步說明如何建立新的轉換動作。具體來說，這個函式會建立轉換動作，並將 type 設為 UPLOAD_CLICKS。這個流程與 Google Ads UI 流程相同，您可以使用「匯入」>「使用 API 或上傳手動匯入」>「追蹤點擊的轉換」建立新的轉換動作。並將 category 設為 DEFAULT。

套用下列預設設定：

• Google Ads API 會自動設定 primary_for_goal 欄位，但您可以明確設定這個欄位，藉此控制轉換動作在與轉換目標結合時，對帳戶中的報表和出價造成的影響。

• Google Ads API 會自動將 counting_type 設為 MANY_PER_CLICK。詳情請參閱「轉換計算選項簡介」。

• Google Ads API 會將 attribution_model_settings 欄位設為 AttributionModel 的 GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN 值，藉此將歸因模式設為「資料驅動」。

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {

  // Creates a ConversionAction.
  ConversionAction conversionAction =
      ConversionAction.newBuilder()
          // Note that conversion action names must be unique. If a conversion action already
          // exists with the specified conversion_action_name the create operation will fail with
          // a ConversionActionError.DUPLICATE_NAME error.
          .setName("Earth to Mars Cruises Conversion #" + getPrintableDateTime())
          .setCategory(ConversionActionCategory.DEFAULT)
          .setType(ConversionActionType.WEBPAGE)
          .setStatus(ConversionActionStatus.ENABLED)
          .setViewThroughLookbackWindowDays(15L)
          .setValueSettings(
              ValueSettings.newBuilder()
                  .setDefaultValue(23.41)
                  .setAlwaysUseDefaultValue(true)
                  .build())
          .build();

  // Creates the operation.
  ConversionActionOperation operation =
      ConversionActionOperation.newBuilder().setCreate(conversionAction).build();

  try (ConversionActionServiceClient conversionActionServiceClient =
      googleAdsClient.getLatestVersion().createConversionActionServiceClient()) {
    MutateConversionActionsResponse response =
        conversionActionServiceClient.mutateConversionActions(
            Long.toString(customerId), Collections.singletonList(operation));
    System.out.printf("Added %d conversion actions:%n", response.getResultsCount());
    for (MutateConversionActionResult result : response.getResultsList()) {
      System.out.printf(
          "New conversion action added with resource name: '%s'%n", result.getResourceName());
    }
  }
}
AddConversionAction.java
      

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V18.ConversionActionService);

    // Note that conversion action names must be unique.
    // If a conversion action already exists with the specified name the create operation
    // will fail with a ConversionAction.DUPLICATE_NAME error.
    string ConversionActionName = "Earth to Mars Cruises Conversion #"
        + ExampleUtilities.GetRandomString();

    // Add a conversion action.
    ConversionAction conversionAction = new ConversionAction()
    {
        Name = ConversionActionName,
        Category = ConversionActionCategory.Default,
        Type = ConversionActionType.Webpage,
        Status = ConversionActionStatus.Enabled,
        ViewThroughLookbackWindowDays = 15,
        ValueSettings = new ConversionAction.Types.ValueSettings()
        {
            DefaultValue = 23.41,
            AlwaysUseDefaultValue = true
        }
    };

    // Create the operation.
    ConversionActionOperation operation = new ConversionActionOperation()
    {
        Create = conversionAction
    };

    try
    {
        // Create the conversion action.
        MutateConversionActionsResponse response =
            conversionActionService.MutateConversionActions(customerId.ToString(),
                    new ConversionActionOperation[] { operation });

        // Display the results.
        foreach (MutateConversionActionResult newConversionAction in response.Results)
        {
            Console.WriteLine($"New conversion action with resource name = " +
                $"'{newConversionAction.ResourceName}' was added.");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
AddConversionAction.cs
      

public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    // Creates a conversion action.
    $conversionAction = new ConversionAction([
        // Note that conversion action names must be unique.
        // If a conversion action already exists with the specified conversion_action_name
        // the create operation will fail with a ConversionActionError.DUPLICATE_NAME error.
        'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(),
        'category' => ConversionActionCategory::PBDEFAULT,
        'type' => ConversionActionType::WEBPAGE,
        'status' => ConversionActionStatus::ENABLED,
        'view_through_lookback_window_days' => 15,
        'value_settings' => new ValueSettings([
            'default_value' => 23.41,
            'always_use_default_value' => true
        ])
    ]);

    // Creates a conversion action operation.
    $conversionActionOperation = new ConversionActionOperation();
    $conversionActionOperation->setCreate($conversionAction);

    // Issues a mutate request to add the conversion action.
    $conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient();
    $response = $conversionActionServiceClient->mutateConversionActions(
        MutateConversionActionsRequest::build($customerId, [$conversionActionOperation])
    );

    printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL);

    foreach ($response->getResults() as $addedConversionAction) {
        /** @var ConversionAction $addedConversionAction */
        printf(
            "New conversion action added with resource name: '%s'%s",
            $addedConversionAction->getResourceName(),
            PHP_EOL
        );
    }
}
AddConversionAction.php
      

def main(client, customer_id):
    conversion_action_service = client.get_service("ConversionActionService")

    # Create the operation.
    conversion_action_operation = client.get_type("ConversionActionOperation")

    # Create conversion action.
    conversion_action = conversion_action_operation.create

    # Note that conversion action names must be unique. If a conversion action
    # already exists with the specified conversion_action_name, the create
    # operation will fail with a ConversionActionError.DUPLICATE_NAME error.
    conversion_action.name = f"Earth to Mars Cruises Conversion {uuid.uuid4()}"
    conversion_action.type_ = (
        client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS
    )
    conversion_action.category = (
        client.enums.ConversionActionCategoryEnum.DEFAULT
    )
    conversion_action.status = client.enums.ConversionActionStatusEnum.ENABLED
    conversion_action.view_through_lookback_window_days = 15

    # Create a value settings object.
    value_settings = conversion_action.value_settings
    value_settings.default_value = 15.0
    value_settings.always_use_default_value = True

    # Add the conversion action.
    conversion_action_response = (
        conversion_action_service.mutate_conversion_actions(
            customer_id=customer_id,
            operations=[conversion_action_operation],
        )
    )

    print(
        "Created conversion action "
        f'"{conversion_action_response.results[0].resource_name}".'
    )
add_conversion_action.py
      

def add_conversion_action(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new


  # Add a conversion action.
  conversion_action = client.resource.conversion_action do |ca|
    ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}"
    ca.type = :UPLOAD_CLICKS
    ca.category = :DEFAULT
    ca.status = :ENABLED
    ca.view_through_lookback_window_days = 15

    # Create a value settings object.
    ca.value_settings = client.resource.value_settings do |vs|
      vs.default_value = 15
      vs.always_use_default_value = true
    end
  end

  # Create the operation.
  conversion_action_operation = client.operation.create_resource.conversion_action(conversion_action)

  # Add the ad group ad.
  response = client.service.conversion_action.mutate_conversion_actions(
    customer_id: customer_id,
    operations: [conversion_action_operation],
  )

  puts "New conversion action with resource name = #{response.results.first.resource_name}."
end
add_conversion_action.rb
      

sub add_conversion_action {
  my ($api_client, $customer_id) = @_;

  # Note that conversion action names must be unique.
  # If a conversion action already exists with the specified conversion_action_name,
  # the create operation fails with error ConversionActionError.DUPLICATE_NAME.
  my $conversion_action_name = "Earth to Mars Cruises Conversion #" . uniqid();

  # Create a conversion action.
  my $conversion_action =
    Google::Ads::GoogleAds::V18::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V18::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V18::Services::ConversionActionService::ConversionActionOperation
    ->new({create => $conversion_action});

  # Add the conversion action.
  my $conversion_actions_response =
    $api_client->ConversionActionService()->mutate({
      customerId => $customer_id,
      operations => [$conversion_action_operation]});

  printf "New conversion action added with resource name: '%s'.\n",
    $conversion_actions_response->{results}[0]{resourceName};

  return 1;
}
add_conversion_action.pl
      

您也可以在用戶端程式庫的「Remarketing」資料夾中，以及「Add Conversion Action code example」程式碼範例集合中找到這個範例。

驗證

Google Ads 和 Google Ads API 支援多種轉換動作，因此部分驗證規則會根據動作的 type 而有所不同。

到目前為止，建立轉換動作時最常見的錯誤是 DUPLICATE_NAME。請確認每個轉換動作的名稱都不重複。

以下提供設定 ConversionAction 欄位的訣竅：

所有列舉欄位

嘗試將任何列舉欄位設為 UNKNOWN 會導致 RequestError.INVALID_ENUM_VALUE 錯誤。

app_id

app_id 屬性不可變更，只能在建立新的應用程式轉換時設定。

attribution_model_settings

將此設為已淘汰的選項會導致 CANNOT_SET_RULE_BASED_ATTRIBUTION_MODELS 錯誤。Google Ads 僅支援 GOOGLE_ADS_LAST_CLICK 和 GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN。

click_through_lookback_window_days

如果將這個屬性設為超出允許範圍的值，就會發生 RangeError.TOO_LOW 或 RangeError.TOO_HIGH 錯誤。

此屬性必須在 AD_CALL 或 WEBSITE_CALL 轉換動作的 [1,60] 範圍內。對於大多數其他轉換動作，允許的範圍為 [1,30]。

include_in_conversions_metric

在 create 或 update 作業中設定這個值會失敗，並傳回 FieldError.IMMUTABLE_FIELD 錯誤。請改為按照轉換目標指南所述設定 primary_for_goal。

phone_call_duration_seconds

如果嘗試在非來電轉換動作上設定這個屬性，系統會傳回 FieldError.VALUE_MUST_BE_UNSET 錯誤。

type

type 屬性不可變動，只能在建立新的轉換時設定。

如果更新轉換動作時，type 等於 UNKNOWN，就會導致 MutateError.MUTATE_NOT_ALLOWED 錯誤。

value_settings

WEBSITE_CALL 或 AD_CALL 轉換動作的 value_settings 必須將 always_use_default_value 設為 true。在建立或更新這個值時指定 false 值，會導致 INVALID_VALUE 錯誤。

view_through_lookback_window_days

如果將這個屬性設為超出允許範圍的值，會導致 RangeError.TOO_LOW 或 RangeError.TOO_HIGH 錯誤。對於大多數轉換動作，允許的範圍為 [1,30]。

您無法在 AD_CALL 或 WEBSITE_CALL 轉換動作上設定這個屬性。指定值會導致 VALUE_MUST_BE_UNSET 錯誤。