Lượt chuyển đổi nâng cao

API lượt chuyển đổi ngoại tuyến CM360 hỗ trợ việc nâng cao lượt chuyển đổi dựa trên thẻ trang web bằng giá trị nhận dạng người dùng.

Lượt chuyển đổi nâng cao

  • Chấp nhận Điều khoản dịch vụ về tính năng Lượt chuyển đổi nâng cao cho cấu hình Floodlight trong CM360.
  • Đo lường trang web bằng ID khớp.
  • Ghi lại những lượt chuyển đổi Floodlight xảy ra trên trang web của bạn. Hãy nhớ ghi lại tất cả thông tin sau vì đây là các trường bắt buộc trong các lệnh gọi API tiếp theo:
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • Sau 90 phút kể từ khi thẻ trực tuyến ghi nhận lượt chuyển đổi, hãy gọi conversions.batchupdate để nâng cao những lượt chuyển đổi này bằng giá trị nhận dạng người dùng.
    • Giá trị nhận dạng người dùng phải được định dạng và băm, đồng thời được thêm vào trường userIdentifiers trên các đối tượng Chuyển đổi.
    • Bạn phải chỉ định số lượng và giá trị. Bạn có thể tuỳ ý điều chỉnh số lượng và giá trị của lượt chuyển đổi trong cùng một lệnh gọi conversions.batchupdate hoặc cung cấp số lượng và giá trị ban đầu.
    • Mỗi lô chèn và cập nhật có thể chứa cả thành công và thất bại. Bạn nên thử lại các lỗi NOT_FOUND trong trường hợp quá trình xử lý lượt chuyển đổi bị chậm trễ hơn bình thường, tối đa là 6 giờ.
    • Bạn phải nâng cao lượt chuyển đổi bằng giá trị nhận dạng người dùng trong vòng 24 giờ sau khi lượt chuyển đổi được thẻ trực tuyến ghi lại.

Chuẩn hoá và băm

Để bảo vệ quyền riêng tư, bạn phải băm địa chỉ email, số điện thoại, họ, tên và địa chỉ đường phố bằng thuật toán SHA-256 trước khi tải lên. Để chuẩn hoá kết quả băm, trước khi băm một trong các giá trị này, bạn phải:

  • Xoá khoảng trắng ở đầu hoặc ở cuối.
  • Chuyển đổi văn bản thành chữ thường.
  • Định dạng số điện thoại theo tiêu chuẩn E164.

  • Xoá tất cả dấu chấm (.) đứng trước tên miền trong địa chỉ email gmail.com và googlemail.com.

C#

/// <summary>
/// Normalizes the email address and hashes it. For this use case, Campaign Manager 360
/// 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();
}

Java

private String normalizeAndHash(MessageDigest digest, String s)
    throws UnsupportedEncodingException {
  // Normalizes by removing leading and trailing whitespace and converting all characters to
  // lower case.
  String normalized = s.trim().toLowerCase();
  // 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, Campaign Manager 360
 * 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);
}

PHP

private static function normalizeAndHash(string $hashAlgorithm, string $value): string
{
    return hash($hashAlgorithm, strtolower(trim($value)));
}

/**
  * Returns the result of normalizing and hashing an email address. For this use case, Campaign
  * Manager 360 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);
}

Python

def normalize_and_hash_email_address(email_address):
    """Returns the result of normalizing and hashing an email address.

    For this use case, Campaign Manager 360 requires removal of any '.'
    characters preceding "gmail.com" or "googlemail.com"

    Args:
        email_address: An email address to normalize.

    Returns:
        A normalized (lowercase, removed whitespace) and SHA-265 hashed string.
    """
    normalized_email = email_address.lower()
    email_parts = normalized_email.split("@")
    # Checks whether the domain of the email address is either "gmail.com"
    # or "googlemail.com". If this regex does not match then this statement
    # will evaluate to None.
    is_gmail = re.match(r"^(gmail|googlemail)\.com$", email_parts[1])

    # Check that there are at least two segments and the second segment
    # matches the above regex expression validating the email domain name.
    if len(email_parts) > 1 and is_gmail:
        # Removes any '.' characters from the portion of the email address
        # before the domain if the domain is gmail.com or googlemail.com.
        email_parts[0] = email_parts[0].replace(".", "")
        normalized_email = "@".join(email_parts)

    return normalize_and_hash(normalized_email)

def normalize_and_hash(s):
    """Normalizes and hashes a string with SHA-256.

    Private customer data must be hashed during upload, as described at:
    https://support.google.com/google-ads/answer/7474263

    Args:
        s: The string to perform this operation on.

    Returns:
        A normalized (lowercase, removed whitespace) and SHA-256 hashed string.
    """
    return hashlib.sha256(s.strip().lower().encode()).hexdigest()

Ruby

# Returns the result of normalizing and then hashing the string using the
# provided digest.  Private customer data must be hashed during upload, as
# described at https://support.google.com/google-ads/answer/7474263.
def normalize_and_hash(str)
  # Remove leading and trailing whitespace and ensure all letters are lowercase
  # before hasing.
  Digest::SHA256.hexdigest(str.strip.downcase)
end

# Returns the result of normalizing and hashing an email address. For this use
# case, Campaign Manager 360 requires removal of any '.' characters preceding
# 'gmail.com' or 'googlemail.com'.
def normalize_and_hash_email(email)
  email_parts = email.downcase.split("@")
  # Removes any '.' characters from the portion of the email address before the
  # domain if the domain is gmail.com or googlemail.com.
  if email_parts.last =~ /^(gmail|googlemail)\.com\s*/
    email_parts[0] = email_parts[0].gsub('.', '')
  end
  normalize_and_hash(email_parts.join('@'))
end

Thêm giá trị nhận dạng người dùng vào lượt chuyển đổi

Trước tiên, hãy chuẩn bị đối tượng Conversion để tải lên hoặc chỉnh sửa như bình thường, sau đó đính kèm mã nhận dạng người dùng như sau:

{
  "matchId": "my-match-id-846513278",
  "ordinal": "my-ordinal-12345678512",
  "quantity": 1,
  "value": 104.23,
  "timestampMicros": 1656950400000000,
  "floodlightConfigurationId": 99999,
  "floodlightActivityId": 8888,
  "userIdentifiers": [
    { "hashedEmail": "0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b" },
    { "hashedPhoneNumber": "1fb1f420856780a29719b994c8764b81770d79f97e2e1861ba938a7a5a15dfb9" },
    {
      "addressInfo": {
        "hashedFirstName": "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2",
        "hashedLastName": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f",
        "hashedStreetAddress": "22b7e2d69b91e0ef4a88e81a73d897b92fd9c93ccfbe0a860f77db16c26f662e",
        "city": "seattle",
        "state": "washington",
        "countryCode": "US",
        "postalCode": "98101"
      }
    }
  ]
}

Phản hồi thành công sẽ có dạng như sau:

{
  "hasFailures": false,
  "status": [
    {
      "conversion": {
        "floodlightConfigurationId": 99999,
        "floodlightActivityId": 8888,
        "timestampMicros": 1656950400000000,
        "value": 104.23,
        "quantity": 1,
        "ordinal": "my-ordinal-12345678512",
        "matchId": "my-match-id-846513278",
        "userIdentifiers": [
          { "hashedEmail": "0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b" },
          { "hashedPhoneNumber": "1fb1f420856780a29719b994c8764b81770d79f97e2e1861ba938a7a5a15dfb9" },
          {
            "addressInfo": {
              "hashedFirstName": "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2",
              "hashedLastName": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f",
              "hashedStreetAddress": "22b7e2d69b91e0ef4a88e81a73d897b92fd9c93ccfbe0a860f77db16c26f662e",
              "city": "seattle",
              "state": "washington",
              "countryCode": "US",
              "postalCode": "98101"
            }
          }
        ],
        "kind": "dfareporting#conversion"
      },
      "kind": "dfareporting#conversionStatus"
    }
  ]
}

Lỗi thường gặp

Sau đây là một số lỗi mà bạn có thể gặp phải khi nâng cao lượt chuyển đổi bằng giá trị nhận dạng người dùng:

Trường hashed_X không phải là giá trị băm SHA-256 hợp lệ
Tất cả các trường có tiền tố đã băm chỉ chấp nhận hàm băm SHA-256 được mã hoá theo hệ thập lục phân.
Trường country_code có độ dài không chính xác
country_code phải có chính xác 2 chữ cái.
Cấu hình Floodlight chưa ký điều khoản dịch vụ về tính năng lượt chuyển đổi nâng cao
Bạn chưa chấp nhận Điều khoản dịch vụ về tính năng Lượt chuyển đổi nâng cao cho mã cấu hình Floodlight của yêu cầu.
Có nhiều hơn 5 user_identifier được chỉ định
Một lượt chuyển đổi chỉ có thể có tối đa 5 giá trị nhận dạng người dùng.

Câu hỏi thường gặp

Tại sao nên dùng mã nhận dạng lượt khớp?
Chỉnh sửa dựa trên mã lượt nhấp sẽ loại trừ những lượt chuyển đổi không có lượt nhấp trước đó và giới hạn giá trị của chế độ tích hợp lượt chuyển đổi nâng cao.
Tại sao bạn nên ghi lại số lượng và giá trị?
API Lượt chuyển đổi ngoại tuyến của CM360 yêu cầu bạn chỉ định số lượng và giá trị.
Tôi có cần lấy dấu thời gian chính xác đến từng phần triệu giây do Google ghi lại để chỉnh sửa một lượt chuyển đổi trực tuyến dựa trên thẻ không?
Đối với nội dung chỉnh sửa dựa trên mã nhận dạng trùng khớp, API hiện chấp nhận nội dung chỉnh sửa miễn là dấu thời gian được cung cấp trong yêu cầu nằm trong vòng 1 phút so với dấu thời gian do Google ghi lại.
Tại sao tôi cần đợi 90 phút sau khi một lượt chuyển đổi được thẻ trực tuyến ghi nhận trước khi nâng cao lượt chuyển đổi đó?
API có thể mất đến 90 phút để lập chỉ mục lượt chuyển đổi trực tuyến và cho phép bạn chỉnh sửa.
Tôi nên chú ý đến điều gì trong phản hồi API?
Ngay cả khi API lượt chuyển đổi CM360 trả về một phản hồi thành công, một số lượt chuyển đổi riêng lẻ có thể không tải lên hoặc cập nhật được. Kiểm tra từng trường ConversionStatus để xem có lỗi không:
  • Bạn có thể và nên thử lại NOT_FOUND trong tối đa 6 giờ, trong trường hợp quá trình xử lý lượt chuyển đổi bị chậm trễ hơn bình thường. Bạn cũng có thể xem Câu hỏi thường gặp về lý do khiến lỗi NOT_FOUND có thể kéo dài hơn 6 giờ.
  • Bạn không nên thử lại các lỗi INVALID_ARGUMENT và PERMISSION_DENIED.