← 返回目录
来源:Google Ads API 官方文档 · 中文版 · 本地归档

管理线下转化

您可以使用 Google Ads API 将线下转化数据导入 Google Ads,以跟踪促成线下销售(例如通过电话或销售代表)的广告。

为了充分利用导入转化数据带来的好处,我们建议您实现增强型潜在客户转化,该功能可利用 GCLID 和用户提供的数据来最大限度地提高持久性和效果。

增强型转化

增强型转化功能可让您通过第一方转化数据(例如电子邮件地址、电话号码和邮寄地址)来补充转化数据,从而提高转化衡量的准确性。

增强型转化分为两种类型。如需了解详情,请参阅增强型转化简介。

以下部分介绍了如何增强线下转化,此功能也称为增强型潜在客户转化。

什么是增强型潜在客户转化?

增强型潜在客户转化是一项经过升级的线下转化数据导入功能,可使用用户提供的数据(例如电子邮件地址)来补充导入的线下转化数据,从而提高衡量准确性和出价效果。您导入线下转化数据后,系统会将您提供的经过哈希处理的客户数据与在您网站上收集的相同数据(例如潜在客户表单)以及与您的广告互动过的已登录客户的数据进行匹配,从而将转化归因于 Google Ads 广告系列。如需了解详情,请参阅增强型潜在客户转化简介。

您可以通过两种方式实现增强型潜在客户转化,具体取决于您是否使用 Google 代码来跟踪网页上的表单提交事件。为了获得最佳效果和持久性,我们建议您使用 Google 代码来设置增强型潜在客户转化。

  • 如果您是从头开始,请先阅读前提条件部分。
  • 如果您已设置线下转化数据导入,并想升级到增强型潜在客户转化,建议您先从配置代码部分开始。
  • 如果您已设置 Google 代码,或者不打算使用 Google 代码,并且正在开始进行 Google Ads API 集成,请跳至 API 实现部分。
  • 如果您无法导入用户提供的数据,或者依赖外部归因来确定转化,请参阅旧版线下转化数据导入指南。

前提条件

首先,请验证您是否已完成“入门”部分中的步骤。

您必须选择启用增强型潜在客户转化并接受客户数据条款,然后才能使用增强型潜在客户转化。您可以向 Google Ads 转化客户发出以下查询,以验证是否已满足这些前提条件:

SELECT
  customer.id,
  customer.conversion_tracking_setting.accepted_customer_data_terms,
  customer.conversion_tracking_setting.enhanced_conversions_for_leads_enabled
FROM customer

如果 accepted_customer_data_terms 或 enhanced_conversions_for_leads_enabled 为 false,请按照创建新的转化操作中的说明完成这些前提条件。

配置代码植入

按照配置 Google 代码设置中的说明配置 Google 代码,以启用增强型潜在客户转化。 如需通过 Google 跟踪代码管理器设置增强型潜在客户转化,请按照这些说明操作。

API 实现

下面是使用 Google Ads API 导入增强型潜在客户转化的总体流程。

  1. 对用户提供的数据(例如电子邮件地址、电话号码和邮寄地址)进行规范化处理和哈希处理。

  2. 填充 ClickConversion 个对象

    经过标准化和哈希处理的用户提供的数据。

  3. 使用 ConversionUploadService 将 ClickConversion 对象导入 Google Ads API。如需了解详情,请参阅 UploadClickConversions。

  4. 检查导入的内容。

检索转化操作资源名称

若要上传转化,您必须指定您在 Google Ads 中设置的 ConversionAction 的资源名称,以便导入点击转化。您可以使用以下 GAQL 查询来查询 conversion_action 资源,从而找到资源名称:

SELECT
  customer.id,
  conversion_action.id,
  conversion_action.name,
  conversion_action.type,
  conversion_action.resource_name
FROM conversion_action
WHERE conversion_action.type = 'UPLOAD_CLICKS'
  AND conversion_action.status = 'ENABLED'

对用户提供的数据进行规范化和哈希处理

出于隐私保护方面的考虑,以下数据在导入之前必须使用 SHA-256 进行哈希处理:

  • 电子邮件地址
  • 电话号码
  • 名字
  • 姓氏
  • 街道地址

为了使哈希结果实现标准化,在对其中每个值进行哈希处理之前,请执行以下操作:

  • 移除开头和结尾处的空格。
  • 将文字转换为小写形式。
  • 根据 E164 标准设置电话号码的格式。

增强型转化的电子邮件地址格式

为确保增强型转化功能实现尽可能高的匹配率,您必须在进行哈希处理之前正确设置电子邮件地址的格式。请按照以下步骤操作:

  1. 应用标准规范化(所有电子邮件地址):

    • 移除所有前导或尾随的空格。
    • 将整个电子邮件地址转换为小写。
  2. 如果适用,请应用 Gmail/Googlemail 特定的规范化:

    • 此步骤仅适用于网域为 gmail.com 和 googlemail.com 的电子邮件地址。
    • 移除句点 (�3):从用户名部分(@ 之前)移除所有句点字符。.
    • 移除加号后缀 (+):从用户名部分移除加号 (+) 及后面的所有字符。

      • 示例:Jane.Doe+Shopping@googlemail.com 先变为 jane.doe+shopping@googlemail.com(小写),然后变为 janedoe@googlemail.com(Gmail/Googlemail 特定规则)。
    • 其他网域:来自除 gmail.com 或 googlemail.com 以外的任何网域的电子邮件地址,都不应从用户名中移除句点或加号后缀。仅对这些地址应用标准归一化(小写、去除空格)。

      • 示例:user.name+NYC@Example.com 将标准化为 user.name+nyc@example.com。
  3. 对标准化电子邮件地址进行哈希处理:

    • 应用适当的规范化步骤后,使用 SHA-256 算法对生成的电子邮件地址进行哈希处理。

请勿对以下数据进行哈希处理:

  • 国家/地区
  • 州/省
  • 城市
  • 邮编

代码示例

此示例展示了如何对用户提供的数据进行规范化和哈希处理。

Java

private String normalizeAndHash(MessageDigest digest, String s)
    throws UnsupportedEncodingException {
  // Normalizes by first converting all characters to lowercase, then trimming spaces.
  String normalized = s.toLowerCase();
  // Removes leading, trailing, and intermediate spaces.
  normalized = normalized.replaceAll("\\s+", "");
  // Hashes the normalized string using the hashing algorithm.
  byte[] hash = digest.digest(normalized.getBytes("UTF-8"));
  StringBuilder result = new StringBuilder();
  for (byte b : hash) {
    result.append(String.format("%02x", b));
  }

  return result.toString();
}

/**
 * Returns the result of normalizing and hashing an email address. For this use case, Google Ads
 * requires removal of any '.' characters preceding {@code gmail.com} or {@code googlemail.com}.
 *
 * @param digest the digest to use to hash the normalized string.
 * @param emailAddress the email address to normalize and hash.
 */
private String normalizeAndHashEmailAddress(MessageDigest digest, String emailAddress)
    throws UnsupportedEncodingException {
  String normalizedEmail = emailAddress.toLowerCase();
  String[] emailParts = normalizedEmail.split("@");
  if (emailParts.length > 1 && emailParts[1].matches("^(gmail|googlemail)\\.com\\s*")) {
    // Removes any '.' characters from the portion of the email address before the domain if the
    // domain is gmail.com or googlemail.com.
    emailParts[0] = emailParts[0].replaceAll("\\.", "");
    normalizedEmail = String.format("%s@%s", emailParts[0], emailParts[1]);
  }
  return normalizeAndHash(digest, normalizedEmail);
}
      

C#

/// <summary>
/// Normalizes the email address and hashes it. For this use case, Google Ads requires
/// removal of any '.' characters preceding <code>gmail.com</code> or
/// <code>googlemail.com</code>.
/// </summary>
/// <param name="emailAddress">The email address.</param>
/// <returns>The hash code.</returns>
private string NormalizeAndHashEmailAddress(string emailAddress)
{
    string normalizedEmail = emailAddress.ToLower();
    string[] emailParts = normalizedEmail.Split('@');
    if (emailParts.Length > 1 && (emailParts[1] == "gmail.com" ||
        emailParts[1] == "googlemail.com"))
    {
        // Removes any '.' characters from the portion of the email address before
        // the domain if the domain is gmail.com or googlemail.com.
        emailParts[0] = emailParts[0].Replace(".", "");
        normalizedEmail = $"{emailParts[0]}@{emailParts[1]}";
    }
    return NormalizeAndHash(normalizedEmail);
}

/// <summary>
/// Normalizes and hashes a string value.
/// </summary>
/// <param name="value">The value to normalize and hash.</param>
/// <returns>The normalized and hashed value.</returns>
private static string NormalizeAndHash(string value)
{
    return ToSha256String(digest, ToNormalizedValue(value));
}

/// <summary>
/// Hash a string value using SHA-256 hashing algorithm.
/// </summary>
/// <param name="digest">Provides the algorithm for SHA-256.</param>
/// <param name="value">The string value (e.g. an email address) to hash.</param>
/// <returns>The hashed value.</returns>
private static string ToSha256String(SHA256 digest, string value)
{
    byte[] digestBytes = digest.ComputeHash(Encoding.UTF8.GetBytes(value));
    // Convert the byte array into an unhyphenated hexadecimal string.
    return BitConverter.ToString(digestBytes).Replace("-", string.Empty);
}

/// <summary>
/// Removes leading and trailing whitespace and converts all characters to
/// lower case.
/// </summary>
/// <param name="value">The value to normalize.</param>
/// <returns>The normalized value.</returns>
private static string ToNormalizedValue(string value)
{
    return value.Trim().ToLower();
}
      

PHP

private static function normalizeAndHash(string $hashAlgorithm, string $value): string
{
    // Normalizes by first converting all characters to lowercase, then trimming spaces.
    $normalized = strtolower($value);
    // Removes leading, trailing, and intermediate spaces.
    $normalized = str_replace(' ', '', $normalized);
    return hash($hashAlgorithm, strtolower(trim($normalized)));
}

/**
 * Returns the result of normalizing and hashing an email address. For this use case, Google
 * Ads requires removal of any '.' characters preceding "gmail.com" or "googlemail.com".
 *
 * @param string $hashAlgorithm the hash algorithm to use
 * @param string $emailAddress the email address to normalize and hash
 * @return string the normalized and hashed email address
 */
private static function normalizeAndHashEmailAddress(
    string $hashAlgorithm,
    string $emailAddress
): string {
    $normalizedEmail = strtolower($emailAddress);
    $emailParts = explode("@", $normalizedEmail);
    if (
        count($emailParts) > 1
        && preg_match('/^(gmail|googlemail)\.com\s*/', $emailParts[1])
    ) {
        // Removes any '.' characters from the portion of the email address before the domain
        // if the domain is gmail.com or googlemail.com.
        $emailParts[0] = str_replace(".", "", $emailParts[0]);
        $normalizedEmail = sprintf('%s@%s', $emailParts[0], $emailParts[1]);
    }
    return self::normalizeAndHash($hashAlgorithm, $normalizedEmail);
}
在接这个接口时卡住了?
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →