使用入门

您必须在 Google Ads 转化账号中启用转化跟踪，才能记录转化。本指南详细介绍了如何确认是否已启用转化跟踪、如何启用转化跟踪（如果尚未启用），以及如何检索有关现有转化操作的信息。

对于大多数转化操作，您还需要执行额外的步骤才能进行跟踪。如需详细了解各种转化操作类型及其要求，请参阅转化操作类别和创建转化操作。

准备提供同意

导入转化数据或用户数据时，您必须确认自己有权与 Google 共享转化数据。您可以使用以下两种方式之一来执行此操作：

1. 配置账号级默认用户意见征求设置。在 Google Ads 界面中，依次点击工具 > 数据管理器 > 意见征求设置 > 默认意见征求设置。
2. 在每个导入的转化或用户数据载荷（例如 ClickConversion.consent、CallConversion.consent 或 UserData.consent）上设置意见征求字段。

设置网站以跟踪转化

如果您要跟踪网站转化或实现增强型潜在客户转化，请先配置网站代码。按照为增强型潜在客户转化配置 Google 代码中的步骤操作，或按照为增强型潜在客户转化配置 Google 跟踪代码管理器中的步骤使用 Google 跟踪代码管理器。

在 Google Ads 转化账号中启用转化跟踪

请按照以下步骤验证账号的转化跟踪设置，并创建或检索转化操作。

启用转化跟踪的步骤

检索有关转化跟踪设置的信息

您可以查询 ConversionTrackingSetting 的 Customer 资源，检查账号的转化跟踪设置并确认是否已启用转化跟踪。使用 GoogleAdsService.SearchStream 发出以下查询：

SELECT
  customer.conversion_tracking_setting.google_ads_conversion_customer,
  customer.conversion_tracking_setting.conversion_tracking_status,
  customer.conversion_tracking_setting.conversion_tracking_id,
  customer.conversion_tracking_setting.cross_account_conversion_tracking_id
FROM customer

google_ads_conversion_customer 字段表示为此客户创建和管理转化的 Google Ads 账号。对于使用跨账号转化跟踪的客户，这是经理账号的 ID。在 Google Ads API 请求中，应将 Google Ads 转化客户 ID 指定为 customer_id，以创建和管理转化。请注意，即使未启用转化跟踪，此字段也会填充。

conversion_tracking_status 字段指示是否启用了转化跟踪，以及账号是否正在使用跨账号转化跟踪。

在 Google Ads 转化客户下创建转化操作

如果 conversion_tracking_status 值为 NOT_CONVERSION_TRACKED，则表示账号未启用转化跟踪。通过在 Google Ads 转化账号中创建至少一个 ConversionAction 来启用转化跟踪，如以下示例所示。或者，您也可以在界面中创建转化操作，具体方法是按照 Google Ads 帮助中心内有关转化跟踪设置的文章中的说明，为您要启用的转化类型进行设置。

请注意，通过 Google Ads API 发送增强型转化数据时，系统会自动启用增强型转化，但您可以通过 Google Ads 界面停用该功能。

代码示例

Java

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
      

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V26.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
      

PHP

    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
      

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    conversion_action_service: ConversionActionServiceClient = (
        client.get_service("ConversionActionService")
    )

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

    # Create conversion action.
    conversion_action: ConversionAction = 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: ConversionAction.ValueSettings = (
        conversion_action.value_settings
    )
    value_settings.default_value = 15.0
    value_settings.always_use_default_value = True

    # Add the conversion action.
    conversion_action_response: MutateConversionActionsResponse = (
        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
      

Ruby

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
      

Perl

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::V26::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V26::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V26::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
      

curl

注意：虽然此处未提供此步骤的直接 REST 代码示例，但您可以使用手动 REST 请求来实现此目的。

请参阅 Google Ads API REST 接口文档和特定于方法的参考页面。您需要根据 proto 定义构建 JSON 载荷。

重要资源：

• 使用 REST
• REST 接口结构
• JSON 字段映射
• 请参阅特定服务和方法的 REST API 参考文档。

确保 type 设置为正确的 ConversionActionType 值。如需详细了解如何在 Google Ads API 中创建转化操作，请参阅创建转化操作。

检索现有转化操作

您可以通过发出以下查询来检索现有转化操作的详细信息。确保请求中的客户 ID 设置为您之前确定的 Google Ads 转化客户，并且转化操作类型设置为正确的 ConversionActionType 值。

SELECT
  conversion_action.id,
  conversion_action.resource_name,
  conversion_action.name,
  conversion_action.type,
  conversion_action.category,
  conversion_action.status
FROM conversion_action

WHERE conversion_action.type = 'INSERT_CONVERSION_ACTION_TYPE'

跨账号转化跟踪

借助跨账号转化跟踪，Google Ads 账号可以代表其他账号导入转化数据，这些账号可能投放了促成转化的广告。这有助于您整合发出导入请求的账号，从而简化集成。

在 Google Ads API 中启用跨账号转化跟踪

注意： 使用 Google Ads API 修改跨账号转化跟踪设置是一项仅限许可清单的功能。如需使用此功能，请与您的客户经理联系，或使用 Google Ads 界面进行设置。

您可以在创建或更新客户账号时，使用 Google Ads API 选择启用跨账号转化跟踪。

在 Customer 资源上，将 conversion_tracking_setting.google_ads_conversion_customer 字段设置为应代表客户账号管理转化操作的经理账号的资源名称。

修改客户账号的转化客户的请求必须由即将成为该客户的新转化客户的经理账号发送。为此，请将 login-customer-id 设置为经理账号 ID。

当您选择采用跨账号转化跟踪，或为现有客户账号切换转化跟踪经理账号时，需要注意的事项与在界面中进行此更改时相同。具体而言：

• 客户账号将采用其新转化跟踪经理账号的默认转化价值规则和默认客户生命周期目标。
• 以特定转化操作为目标的广告系列将改用转化经理账号的默认转化目标。如果您继续以特定转化操作为目标，可能会导致行为不一致，因为经理账号可能与客户账号的目标不同。确保您的广告系列以正确的目标为优化方向。
• 如果某个账号属于多个经理账号，则该账号只能使用一个经理账号的转化操作。如果未指定转化跟踪账号，该账号默认会将自身用作转化跟踪账号。

跨账号导入转化数据

启用跨账号跟踪后，客户账号和经理账号可以代表广告投放账号导入转化数据。这样一来，您就可以简化导入逻辑，无需在导入时确定每次转化的广告投放账号，只需从账号树状视图中选择一个账号即可导入所有转化。

警告： 为避免创建重复的转化，请勿使用不同的账号多次上传同一转化。

若要成功上传转化数据，上传账号必须有权访问转化操作。在跨账号跟踪层次结构中，如果上传账号是账号树状视图中转化操作所有者的父级（经理）或后代，则该账号有权访问该操作。

下图展示了导入转化的授权结构。其中，C1 是投放了促成转化的广告的客户账号，M2 是转化操作所有者和 C1 的转化跟踪父级账号。以绿色突出显示的账号可以代表 C1 导入转化数据，而以红色突出显示的账号则不能。

创建转化操作

若要衡量转化，请为您要跟踪的转化操作的type设置ConversionAction。 例如，在线购买和来电需要不同的转化操作。

在 API 中设置新转化操作的最佳方法是使用添加转化操作代码示例。该示例会为您处理所有后台身份验证任务，并引导您创建 ConversionAction。

对于大多数转化操作，您还需要执行额外的步骤才能进行跟踪。例如，如需跟踪网站上的转化，您必须在网站的转化页中添加一段名为代码的代码段。如需详细了解其他转化操作类型的要求，请参阅关于转化类型的 Google Ads 帮助中心文章。

如果您使用的是跨账号转化跟踪，ConversionActionService 会返回以下转化操作：

• 由账号用于跨账号转化跟踪的经理账号定义的所有转化操作
• 客户已累积统计信息的所有转化操作，包括系统定义的操作以及经理拥有的操作（即使该经理随后解除关联）
• 客户在自己的账号中定义的所有操作
• 在关联的 Google Analytics 媒体资源中创建的 Google Analytics 转化。 这包括未导入 Google Ads 的 Google Analytics 转化操作，其状态为HIDDEN。

代码示例

以下代码示例将引导您完成创建新转化操作的过程。具体而言，它会创建一个 type 设置为 UPLOAD_CLICKS 的转化操作。它还会将 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 值，将归因模型设置为以数据为依据。如需详细了解归因模型，请参阅归因模型简介。

Java

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
      

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V26.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
      

PHP

    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
      

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    conversion_action_service: ConversionActionServiceClient = (
        client.get_service("ConversionActionService")
    )

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

    # Create conversion action.
    conversion_action: ConversionAction = 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: ConversionAction.ValueSettings = (
        conversion_action.value_settings
    )
    value_settings.default_value = 15.0
    value_settings.always_use_default_value = True

    # Add the conversion action.
    conversion_action_response: MutateConversionActionsResponse = (
        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
      

Ruby

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
      

Perl

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::V26::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V26::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V26::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
      

curl

注意：虽然此处未提供此步骤的直接 REST 代码示例，但您可以使用手动 REST 请求来实现此目的。

请参阅 Google Ads API REST 接口文档和特定于方法的参考页面。您需要根据 proto 定义构建 JSON 载荷。

重要资源：

• 使用 REST
• REST 接口结构
• JSON 字段映射
• 请参阅特定服务和方法的 REST API 参考文档。

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

ConversionActionService.MutateConversionActions 字段参考

在 ConversionActionService 上使用 MutateConversionActions，在 Google Ads 转化客户下创建、更新或移除转化操作：

POST https://googleads.googleapis.com/v26/customers/{customer_id}/conversionActions:mutate

下表列出了 MutateConversionActionsRequest 上的顶级请求和操作字段：

字段	要求	说明
customer_id	必填	Google Ads 转化客户 (google_ads_conversion_customer) 的 10 位数 ID (string)，不含连字符。
partial_failure	可选	如果设置为 true (bool)，则系统会执行有效操作，并在 partial_failure_error 中返回失败操作的错误。默认设置为 false。
validate_only	可选	如果为 true (bool)，则验证请求而不执行更改。
response_content_type	可选	ResponseContentType 控制响应是仅返回 resource_name（RESOURCE_NAME_ONLY，默认值）还是返回更改后的 ConversionAction 对象 (MUTABLE_RESOURCE)。
operations[].create	必填（创建时）	要创建的 ConversionAction 资源。预计不会出现 resource_name。
operations[].update	必需（更新时）	要更新的 ConversionAction 资源（必须包含 resource_name 以及 ConversionActionOperation 上的同级 update_mask）。
operations[].update_mask	必需（更新时）	ConversionActionOperation（update 的同级，未嵌套在 ConversionAction 中）上的 FieldMask（snake_case 中修改后的 ConversionAction 字段路径的逗号分隔列表；REST JSON updateMask 接受 snake_case 或 camelCase，而 gRPC 和客户端库需要 snake_case）。
operations[].remove	必需（移除时）	要移除的转化操作的资源名称 (customers/{customer_id}/conversionActions/{action_id})。

在 operations[].create 或 operations[].update 中配置 ConversionAction 时，请遵循以下字段要求和可变性限制（如需了解特定于类型的错误规则，请参阅验证）：

ConversionAction 字段	要求和可变性	说明
name	必需（可变）	在转化客户账号中具有唯一的显示名称 (string)。
type	create (IMMUTABLE) 必须提供	ConversionActionType（例如 WEBPAGE、UPLOAD_CLICKS、UPLOAD_CALLS、AD_CALL 或 WEBSITE_CALL）。
category	可选（可变）	ConversionActionCategory（例如 DEFAULT、PURCHASE、SUBMIT_LEAD_FORM、SIGNUP 或 PHONE_CALL_LEAD）。默认值为 DEFAULT。
status	可选（可变）	ConversionActionStatus（ENABLED、REMOVED 或 HIDDEN）。默认值为 ENABLED。
primary_for_goal	可选（可变）	bool，用于控制在标准客户和广告系列转化目标中，该操作是否可出价（注意：CustomConversionGoal 资源会忽略此设置）。默认值为 true。
counting_type	可选（可变）	ConversionActionCountingType（MANY_PER_CLICK 默认值或 ONE_PER_CLICK）。
value_settings	可选（可变）	ValueSettings（default_value、default_currency_code、always_use_default_value）。
attribution_model_settings	可选（可变）	AttributionModelSettings（attribution_model：GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN 默认值或 GOOGLE_ADS_LAST_CLICK）。
click_through_lookback_window_days	可选（可变）	int64点击型转化回溯期（以天为单位，大多数类型为 1 到 90 天；来电类型为 1 到 60 天）。
view_through_lookback_window_days	可选（可变）	int64 浏览型转化回溯期（以天为单位，大多数类型为 1 到 30 天；来电类型未设置）。
phone_call_duration_seconds	仅限调用类型（可变）	int64 最短通话时长（以秒为单位，0 到 10000）。
app_id	仅限应用类型（一经创建便无法更改）	移动应用标识符 (string)；只能在 create 上为应用转化操作设置。
include_in_conversions_metric	在变更中为只读	无法直接修改；请改为配置 primary_for_goal。
tag_snippets[]	OUTPUT_ONLY	已在 WEBPAGE 项转化操作中填充网站跟踪代码段 (TagSnippet)。

REST 请求和响应结构

如需通过 REST 创建或更新 ConversionAction，请向 ConversionActionService.MutateConversionActions 发送 POST 请求。更新现有转化操作时，请在操作对象上指定 updateMask 作为 update 的同级对象：

POST https://googleads.googleapis.com/v26/customers/{customer_id}/conversionActions:mutate

{
  "operations": [
    {
      "create": {
        "name": "Earth to Mars Cruise Conversion",
        "type": "UPLOAD_CLICKS",
        "category": "DEFAULT",
        "status": "ENABLED",
        "primaryForGoal": true,
        "countingType": "ONE_PER_CLICK",
        "clickThroughLookbackWindowDays": "60",
        "valueSettings": {
          "defaultValue": 23.41,
          "defaultCurrencyCode": "USD",
          "alwaysUseDefaultValue": true
        }
      }
    },
    {
      "updateMask": "primary_for_goal,value_settings.default_value",
      "update": {
        "resourceName": "customers/{customer_id}/conversionActions/6666666666",
        "primaryForGoal": false,
        "valueSettings": {
          "defaultValue": 45.00
        }
      }
    }
  ]
}

成功的响应会返回 results[] 中的 MutateConversionActionResult 条目：

{
  "results": [
    {
      "resourceName": "customers/{customer_id}/conversionActions/7777777777"
    },
    {
      "resourceName": "customers/{customer_id}/conversionActions/6666666666"
    }
  ]
}

使用 GAQL 检查转化操作设置和代码段

除了启用转化跟踪的步骤中显示的基本查询之外，您还可以使用 GoogleAdsService.SearchStream 查询 conversion_action 资源，以检查 primary_for_goal、归因模型状态、回溯期、价值设置和网站 tag_snippets：

SELECT
  conversion_action.id,
  conversion_action.resource_name,
  conversion_action.name,
  conversion_action.type,
  conversion_action.category,
  conversion_action.status,
  conversion_action.primary_for_goal,
  conversion_action.counting_type,
  conversion_action.click_through_lookback_window_days,
  conversion_action.view_through_lookback_window_days,
  conversion_action.value_settings.default_value,
  conversion_action.value_settings.default_currency_code,
  conversion_action.value_settings.always_use_default_value,
  conversion_action.attribution_model_settings.attribution_model,
  conversion_action.attribution_model_settings.data_driven_model_status,
  conversion_action.tag_snippets
FROM conversion_action
WHERE conversion_action.status = 'ENABLED'

验证

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 到 90 天。

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