创建转化操作

本指南列出了您可以使用 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 参数，以及指向每个具体转化操作类型文档的链接：

增强型网站转化

借助增强型网站转化，您可以将 WEBPAGE 转化操作的第一方转化数据发送在转化事件发生后的 24 小时内，而不是在转化发生的同时。这样，您就可以从各种来源（例如客户数据库或 CRM 系统）找到第一方数据。

其他转化操作类型

Google Ads API 可在报告中提供其他类型的转化操作，但可能会限制或禁止创建或修改这些操作。

SKAdNetwork 转化次数

如果您投放的是 iOS 应用广告系列，并且已实现 SKAdNetwork，则可以使用以下资源在 Customer 和 Campaign 级别访问向 Google 提供的 SKAdNetwork 数据：

您还可以通过 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、媒体资源名称和事件名称。

• Universal 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 转化的其他属性或导入的 Universal 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 的转化操作。此流程与使用 导入 > 使用 API 或上传手动导入 > 跟踪点击带来的转化创建新的转化操作的 Google Ads 界面流程相同。它还会将 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
      

您还可以在客户端库的“再营销”文件夹中以及代码示例集合中找到此示例：添加转化操作代码示例。

验证

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 错误。