تبدیل‌های بهبودیافته

‫CM360 offline conversion API از بهبود تبدیل‌های مبتنی بر برچسب وب‌سایت با شناسه‌های کاربر پشتیبانی می‌کند.

تبدیل بهبودیافته

  • شرایط خدمات تبدیل‌های بهبودیافته را برای پیکربندی Floodlight در CM360 بپذیرید.
  • وب‌سایت‌هایتان را با شناسه مطابقت مجهز کنید.
  • تبدیل‌های Floodlight را که در وب‌سایت شما رخ می‌دهد ثبت کنید. حتماً همه موارد زیر را ضبط کنید زیرا این موارد فیلدهای الزامی در فراخوانی‌های بعدی API هستند:
    • matchId
    • ordinal
    • timestampMicros
    • floodlightActivityId
    • floodlightConfigurationId
    • quantity
    • value
  • پس‌از گذشت ۹۰ دقیقه از زمانی که برچسب آنلاین تبدیل را ثبت کرد، conversions.batchupdate را فراخوانی کنید تا این تبدیل‌ها را با شناسه‌های کاربر بهبود دهید.
    • شناسه‌های کاربر باید قالب‌بندی و درهم‌سازی شوند و به فیلد userIdentifiers در اشیای «تبدیل» اضافه شوند.
    • مقدار و ارزش باید مشخص شود. می‌توانید به‌طور اختیاری تعداد و مقدار تبدیل را در همان فراخوانی conversions.batchupdate تنظیم کنید، یا تعداد و مقدار اصلی را ارائه دهید.
    • هر دسته از درج‌ها و به‌روزرسانی‌ها می‌تواند شامل ترکیبی از موفقیت‌ها و شکست‌ها باشد. درصورت وجود تأخیر طولانی‌تر از حد معمول در پردازش تبدیل، موارد ناموفق NOT_FOUND و INTERNAL باید تا ۶ ساعت دوباره امتحان شوند.
    • تبدیل‌ها باید ظرف ۲۴ ساعت پس‌از ضبط شدن توسط برچسب‌های آنلاین، با شناسه‌های کاربر بهبود یابند.

نرمال‌سازی و درهم‌سازی

برای کمک به محافظت از حریم خصوصی، نشانی‌های ایمیل، شماره‌های تلفن، نام‌ها، نام‌های خانوادگی، و نشانی‌های خیابان باید پیش‌از بارگذاری بااستفاده از الگوریتم SHA-256 درهم‌سازی شوند. برای استانداردسازی نتایج درهم‌سازی، قبل‌از درهم‌سازی یکی از این مقادیر باید:

  • فاصله‌های سفید اضافی در ابتدا یا انتهای متن را بردارید.
  • نوشتار را به حروف کوچک تبدیل کن.
  • شماره تلفن‌ها را طبق استاندارد E164 قالب‌بندی کنید. علامت مثبت (+) و کد کشور را وارد کنید. برای مثال، شماره تلفن ایالات متحده (800)555-0200 باید به +18005550200 قالب‌بندی و نرمال‌سازی شود

  • همه نقطه‌های (.) قبل‌از نام دامنه را در نشانی‌های ایمیل gmail.com و 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();
}

جاوا

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

افزودن شناسه‌های کاربر به تبدیل‌ها

ابتدا شیء Conversion را برای بارگذاری یا ویرایش به‌صورت عادی آماده کنید، سپس شناسه کاربر را به‌صورت زیر پیوست کنید:

{
  "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"
      }
    }
  ]
}

پاسخ موفق باید به این شکل باشد:

{
  "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"
    }
  ]
}

خطاهای رایج

در اینجا برخی‌از خطاهایی که ممکن است هنگام بهبود تبدیل با شناسه‌های کاربر ببینید آورده شده است:

فیلد hashed_X درهم‌سازی SHA-256 معتبر نیست
همه فیلدهایی که پیشوند درهم‌سازی‌شده دارند فقط درهم‌سازی‌های SHA-256 کدگذاری‌شده در دستگاه شانزده‌شانزدهی را می‌پذیرند.
طول فیلد country_code نادرست است
country_code باید دقیقاً ۲ حرف باشد.
پیکربندی Floodlight شرایط خدمات تبدیل بهبودیافته را امضا نکرده است
«شرایط خدمات تبدیل‌های بهسازی‌شده» برای شناسه پیکربندی Floodlight درخواست پذیرفته نشده است.
بیش‌از پنج user_identifiers مشخص شده است
تبدیل فقط می‌تواند تا ۵ شناسه کاربر داشته باشد.

پرسشگان

چرا شناسه منطبق توصیه می‌شود؟
ویرایش‌های مبتنی بر شناسه کلیک، تبدیل‌هایی را که قبل‌از آن‌ها کلیک انجام نشده است مستثنی می‌کند و ارزش ادغام تبدیل بهبودیافته را محدود می‌کند.
چرا باید مقدار و ارزش ثبت شود؟
در CM360 Offline Conversions API، باید مقدار و ارزش مشخص شود.
آیا برای ویرایش تبدیل آنلاین مبتنی بر برچسب باید مُهر زمان دقیق میکروثانیه‌ای را که Google ثبت کرده است دریافت کنم؟
برای ویرایش‌های مبتنی بر شناسه مسابقه، API اکنون ویرایش را می‌پذیرد، به‌شرطی که مُهر زمان ارائه‌شده در درخواست در فاصله ۱ دقیقه‌ای از مُهر زمان ثبت‌شده توسط Google باشد.
چرا باید ۹۰ دقیقه پس‌از ثبت تبدیل توسط برچسب آنلاین صبر کنم تا بتوانم آن را بهبود دهم؟
ممکن است تا ۹۰ دقیقه طول بکشد تا تبدیل آنلاین توسط میانای برنامه‌سازی کاربردی نمایه‌گذاری شود و برای ویرایش دردسترس قرار گیرد.
در پاسخ میانای برنامه‌سازی کاربردی به چه چیزی باید توجه کنم؟
حتی وقتی میانای برنامه‌سازی کاربردی تبدیل CM360 پاسخ موفقیت‌آمیز برمی‌گرداند، ممکن است برخی‌از تبدیل‌های تکی بارگذاری یا به‌روزرسانی نشده باشند. فیلدهای ConversionStatus را به‌صورت جداگانه برای یافتن خطاها بررسی کنید:
  • درصورت وجود تأخیر طولانی‌تر از حد معمول در پردازش تبدیل، می‌توان و باید خطاهای NOT_FOUND و INTERNAL را تا ۶ ساعت دوباره امتحان کرد.
  • خطاهای INVALID_ARGUMENT و PERMISSION_DENIED نباید دوباره امتحان شوند.
  • برای جزئیات بیشتر، به پرسشگان مراجعه کنید.