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

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

راه اندازی توصیه شده

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

عادی سازی و هش کردن

برای کمک به محافظت از حریم خصوصی، آدرس های ایمیل، شماره تلفن، نام، نام خانوادگی و آدرس خیابان باید با استفاده از الگوریتم 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);
}

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

پایتون

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 باید دقیقا 2 حرف باشد.

پیکربندی Floodlight شرایط خدمات تبدیل پیشرفته را امضا نکرده است

شرایط خدمات تبدیل پیشرفته برای شناسه پیکربندی Floodlight درخواست پذیرفته نشده است.

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

یک تبدیل فقط می تواند حداکثر 5 شناسه کاربر داشته باشد.

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

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

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

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

CM360 Offline Conversions API نیاز به تعیین مقدار و مقدار دارد.

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

برای ویرایش‌های مبتنی بر شناسه مطابقت، API اکنون ویرایش را می‌پذیرد تا زمانی که مهر زمانی ارائه‌شده در درخواست در 1 دقیقه از مهر زمانی ثبت‌شده Google باشد.

چرا باید 90 دقیقه بعد از ثبت تبدیل توسط یک برچسب آنلاین قبل از بهبود آن صبر کنم؟

ممکن است تا 90 دقیقه طول بکشد تا تبدیل آنلاین توسط API نمایه شود و برای ویرایش در دسترس باشد.

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

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

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