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

API lượt chuyển đổi ngoại tuyến CM360 hỗ trợ cải thiện các lượt chuyển đổi dựa trên thẻ trên trang web thông qua 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ề lượt chuyển đổi nâng cao cho cấu hình Floodlight của bạn trong CM360.
  • Đo lường trang web của bạn bằng mã so khớp.
  • Ghi lại các 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ả những dữ liệu sau đây vì chúng 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 được lượt chuyển đổi, hãy gọi conversions.batchupdate để cải thiện các 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, rồi thêm vào trường userIdentifiers trên Đố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ể bao gồm cả lần thành công và không thành công. Bạn nên thử lại NOT_FOUND lỗi 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 trong tối đa 6 giờ.
    • Lượt chuyển đổi phải được nâng cao bằng giá trị nhận dạng người dùng trong vòng 24 giờ sau khi được thẻ trực tuyến thu thập.

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, tên, họ 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);
}

1.199

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 giá trị 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"
      }
    }
  ]
}

Một 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"
    }
  ]
}

Các lỗi phổ biến

Dưới đây là một số lỗi 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 băm_X không phải là hàm 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á bằng thập lục phân.
Trường quốc gia_mã có độ dài không chính xác
country_code phải có đúng 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ụ của 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.
Đã chỉ định nhiều hơn 5 giá trị nhận dạng người dùng
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 mã nhận dạng để so khớp lại được đề xuất?
Nội dung 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 đứng sau lượt nhấp và giới hạn giá trị của tính năng tích hợp lượt chuyển đổi nâng cao.
Tại sao cần ghi lại số lượng và giá trị?
API lượt chuyển đổi ngoại tuyến CM360 yêu cầu phải chỉ định số lượng và giá trị.
Tôi có cần lấy dấu thời gian chính xác micrô giây do Google ghi lại để chỉnh sửa lượt chuyển đổi dựa trên thẻ trực tuyến không?
Đối với nội dung chỉnh sửa dựa trên mã so 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 phải nằm trong vòng 1 phút kể từ 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 thẻ trực tuyến ghi lại lượt chuyển đổi rồi mới nâng cao được lượt chuyển đổi đó?
Có thể mất đến 90 phút để API lập chỉ mục lượt chuyển đổi trực tuyến và bạn có thể chỉnh sửa lượt chuyển đổi này.
Tôi nên chú ý điều gì trong phản hồi của API?
Ngay cả khi API chuyển đổi CM360 trả về phản hồi thành công, một số lượt chuyển đổi riêng lẻ cũng có thể vẫn không tải lên hoặc cập nhật được. Kiểm tra từng trường ConversionStatus để biết lỗi:
  • Bạn có thể thử lại lỗi NOT_FOUND trong tối đa 6 giờ, nếu có độ trễ hơn bình thường trong quá trình xử lý lượt chuyển đổi. Ngoài ra, hãy xem phần Câu hỏi thường gặp để biết lý do các lỗi NOT_FOUND có thể tồn tại sau 6 giờ.
  • Bạn không nên thử lại các lỗi INVALID_ARGUMENT và PERMISSION_DENIED.