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

API lượt chuyển đổi ngoại tuyến CM360 hỗ trợ nâng cao chất lượng dựa trên thẻ trên trang web lượt chuyển đổi có 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 của tính năng Lượt chuyển đổi nâng cao Dịch vụ dành cho Floodlight của bạn trên CM360.
  • Đo lường trang web của bạn bằng mã trùng 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 âm tất cả các trường 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 lượt chuyển đổi, gọi conversions.batchupdate để cải thiện lượt chuyển đổi có 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 Lượt 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 ban đầu và giá trị.
    • Mỗi lô chèn và cập nhật có thể bao gồm cả những thành công và lỗi. Bạn nên thử lại NOT_FOUND lỗi phòng trường hợp vẫn xảy ra lỗi độ trễ so với bình thường trong quá trình xử lý lượt chuyển đổi, lên tới 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 đó chúng được các thẻ trực tuyến ghi lại.

Chuẩn hoá và băm

Để giúp bảo vệ quyền riêng tư, địa chỉ email, số điện thoại, tên, họ tên và địa chỉ đường phố phải được băm bằng thuật toán SHA-256 trước đang được tải lên. Để chuẩn hoá kết quả băm, trước khi băm một kết quả trong số 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 gmail.com và googlemail.com địa chỉ email.

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, rồi đí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"
      }
    }
  ]
}

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 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 cho người dùng giá trị nhận 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 số thập lục phân.
Trường country_code 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 hơn 5 user_identifier
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

Vì sao nên dùng mã nhận dạng để so khớp?
Các 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 bắt đầu bằng 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 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 số lượng và giá trị phải là được chỉ định.
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 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ã trùng khớp, API hiện sẽ 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 là trong vòng 1 phút kể từ khi Google ghi lại .
Tại sao tôi cần phải đợi 90 phút sau khi một thẻ trực tuyến ghi nhận lượt chuyển đổi rồi mới cải thiện lượt chuyển đổi đó?
Có thể mất đến 90 phút để Google Play lập chỉ mục lượt chuyển đổi trực tuyến API và có thể chỉnh sửa được.
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, vẫn có một số không thể tải lên hoặc cập nhật chuyển đổi riêng lẻ. Kiểm tra trường ConversionStatus riêng lẻ để tìm lỗi:
  • NOT_FOUND lỗi có thể và nên được thử lại, tối đa 6 giờ, trong trường hợp thì quá trình xử lý lượt chuyển đổi sẽ mất nhiều thời gian hơn bình thường. Ngoài ra, hãy xem Câu hỏi thường gặp về lý do tại sao NOT_FOUND lỗi có thể vẫn tồn tại hơn 6 giờ.
  • Bạn không nên thử lại các lỗi INVALID_ARGUMENT và PERMISSION_DENIED.