تبدیل های پیشرفته

رابط برنامه‌نویسی کاربردی تبدیل آفلاین CM360 از تبدیل‌های بهبودیافته مبتنی بر برچسب وب‌سایت با شناسه‌های کاربر پشتیبانی می‌کند.

تنظیمات پیشنهادی

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

نرمال‌سازی و هشینگ

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

• فاصله‌های خالیِ ابتدا یا انتهای عبارت را حذف کنید.
• متن را به حروف کوچک تبدیل کنید.
• شماره تلفن‌ها را طبق استاندارد E164 قالب‌بندی کنید.

• تمام نقطه‌ها (.) که قبل از نام دامنه در آدرس‌های ایمیل gmail.com و googlemail.com قرار دارند را حذف کنید.

سی شارپ

/// <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);
}

پی اچ پی

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);
}

پایتون

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()

روبی

# 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 درخواست پذیرفته نشده است.

بیش از پنج شناسه کاربری مشخص شده است

یک تبدیل فقط می‌تواند تا ۵ شناسه کاربری داشته باشد.

سوالات متداول

چرا استفاده از شناسه تطبیق توصیه می‌شود؟

ویرایش‌های مبتنی بر شناسه کلیک، تبدیل‌هایی را که قبل از آنها کلیکی انجام نشده است، حذف می‌کنند و ارزش ادغام تبدیل‌های پیشرفته را محدود می‌کنند.

چرا باید کمیت و ارزش ثبت شوند؟

API تبدیل‌های آفلاین CM360 نیاز به مشخص کردن مقدار و مقدار دارد.

آیا برای ویرایش تبدیل آنلاین مبتنی بر برچسب، باید دقیقاً همان برچسب زمانی میکروثانیه‌ای که توسط گوگل ثبت شده است را دریافت کنم؟

برای ویرایش‌های مبتنی بر شناسه تطبیق، API اکنون ویرایشی را می‌پذیرد که برچسب زمانی ارائه شده در درخواست، حداکثر ۱ دقیقه با برچسب زمانی ثبت شده گوگل فاصله داشته باشد.

چرا باید ۹۰ دقیقه پس از ثبت یک تبدیل توسط یک تگ آنلاین، قبل از بهبود آن صبر کنم؟

ممکن است تا ۹۰ دقیقه طول بکشد تا تبدیل آنلاین توسط API فهرست‌بندی شود و برای ویرایش در دسترس قرار گیرد.

در پاسخ API به چه نکاتی باید توجه کنم؟

حتی زمانی که API تبدیل CM360 پاسخ موفقیت‌آمیزی را برمی‌گرداند، ممکن است آپلود یا به‌روزرسانی برخی از تبدیل‌های منفرد با شکست مواجه شده باشد. فیلدهای ConversionStatus منفرد را برای یافتن خطا بررسی کنید:

• در صورتی که تأخیر بیش از حد معمول در پردازش تبدیل وجود داشته باشد، می‌توان و باید تا ۶ ساعت دوباره به خطاهای NOT_FOUND رسیدگی کرد. همچنین به بخش سوالات متداول در مورد اینکه چرا خطاهای NOT_FOUND می‌توانند بیش از ۶ ساعت ادامه داشته باشند، مراجعه کنید.
• خطاهای INVALID_ARGUMENT و PERMISSION_DENIED نباید دوباره امتحان شوند.