API ของ Conversion ออฟไลน์ของ CM360 รองรับการเพิ่มประสิทธิภาพ Conversion ตามแท็กเว็บไซต์ด้วยตัวระบุผู้ใช้
การตั้งค่าที่แนะนำ
- ยอมรับข้อกำหนดในการให้บริการของ Conversion ที่ปรับปรุงแล้วสำหรับการกำหนดค่า Floodlight ใน CM360
- ใช้รหัสการจับคู่เป็นเครื่องมือในเว็บไซต์
- บันทึก Conversion ของ Floodlight ที่เกิดขึ้นในเว็บไซต์ อย่าลืมบันทึกข้อมูลต่อไปนี้ทั้งหมดเนื่องจากเป็นช่องที่ต้องกรอกในการเรียก API ครั้งต่อๆ ไป
matchId
ordinal
timestampMicros
floodlightActivityId
floodlightConfigurationId
quantity
value
- หลังจากผ่านไป 90 นาทีนับตั้งแต่แท็กออนไลน์บันทึก Conversion ให้เรียกใช้
conversions.batchupdate
เพื่อเพิ่มประสิทธิภาพ Conversion เหล่านี้ด้วยตัวระบุผู้ใช้- ตัวระบุผู้ใช้ควรมีการจัดรูปแบบและแฮช แล้วเพิ่มลงในช่อง
userIdentifiers
ในออบเจ็กต์ Conversion - ต้องระบุจำนวนและค่า
คุณจะเลือกปรับจำนวนและมูลค่าของ Conversion ในการโทร
conversions.batchupdate
เดียวกันหรือจะระบุจำนวนและมูลค่าเดิมก็ได้ - ส่วนแทรกและการอัปเดตแต่ละชุดอาจมีทั้งความสำเร็จและความล้มเหลว คุณควรลองดำเนินการกับ
NOT_FOUND
อีกครั้งหากการประมวลผล Conversion มีความล่าช้านานกว่าปกติ สูงสุด 6 ชั่วโมง - ต้องมีการปรับปรุง Conversion ด้วยตัวระบุผู้ใช้ภายใน 24 ชั่วโมงหลังจากที่บันทึกโดยแท็กออนไลน์
- ตัวระบุผู้ใช้ควรมีการจัดรูปแบบและแฮช แล้วเพิ่มลงในช่อง
การปรับให้เป็นมาตรฐานและการแฮช
เพื่อช่วยปกป้องความเป็นส่วนตัว คุณต้องแฮชอีเมล หมายเลขโทรศัพท์ ชื่อ นามสกุล และที่อยู่โดยใช้อัลกอริทึม SHA-256 ก่อนที่จะอัปโหลด ก่อนแฮชค่าเหล่านี้ คุณต้องทำดังนี้เพื่อให้ผลลัพธ์การแฮชเป็นมาตรฐาน
- นําช่องว่างขึ้นต้นหรือต่อท้ายออก
- แปลงข้อความให้เป็นตัวพิมพ์เล็ก
- จัดรูปแบบหมายเลขโทรศัพท์ตามมาตรฐาน E164
นําจุด (.) ที่อยู่ก่อนชื่อโดเมนในอีเมล
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();
}
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
เพิ่มตัวระบุผู้ใช้ลงใน Conversion
ก่อนอื่นให้เตรียมออบเจ็กต์ 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"
}
]
}
ข้อผิดพลาดที่พบบ่อย
ต่อไปนี้คือข้อผิดพลาดที่คุณอาจเห็นเมื่อเพิ่มประสิทธิภาพ Conversion ด้วยตัวระบุผู้ใช้
- ช่อง hashed_X ไม่ใช่แฮช SHA-256 ที่ถูกต้อง
- ทุกช่องที่ขึ้นต้นด้วยการแฮชจะยอมรับเฉพาะแฮช SHA-256 ที่เข้ารหัสในรูปแบบเลขฐานสิบหกเท่านั้น
- รหัสประเทศ [country_code] มีความยาวไม่ถูกต้อง
country_code
ต้องเป็นตัวอักษร 2 ตัวเท่านั้น- การกำหนดค่า Floodlight ไม่ได้ลงนามในข้อกำหนดในการให้บริการของ Conversion ที่ปรับปรุงแล้ว
- รหัสการกำหนดค่า Floodlight ของคำขอไม่ยอมรับข้อกำหนดในการให้บริการของ Conversion ที่ปรับปรุงแล้ว
- มีการระบุ user_identifier มากกว่า 5 รายการ
- Conversion จะมีตัวระบุผู้ใช้ได้สูงสุด 5 รายการเท่านั้น
คำถามที่พบบ่อย
- เหตุใดจึงแนะนำรหัสการจับคู่
- การแก้ไขตามรหัสคลิกจะยกเว้น Conversion ที่ไม่ได้เกิดขึ้นหลังการคลิกและจำกัดมูลค่าของการผสานรวม Conversion ที่ปรับปรุงแล้ว
- เหตุใดจึงควรบันทึกจำนวนและมูลค่า
- API สำหรับ Conversion ออฟไลน์ของ CM360 กำหนดให้ต้องระบุจำนวนและมูลค่า
- ฉันต้องขอการประทับเวลาที่แน่นอนระดับไมโครวินาทีที่ Google บันทึกไว้เพื่อแก้ไข Conversion ที่อิงตามแท็กออนไลน์ไหม
- สำหรับการแก้ไขตามรหัสการจับคู่ ตอนนี้ API จะยอมรับการแก้ไขตราบใดที่การประทับเวลาที่ระบุไว้ในคำขออยู่ภายใน 1 นาทีนับจากการประทับเวลาที่ Google บันทึกไว้
- เหตุใดฉันจึงต้องรอ 90 นาทีหลังจากบันทึก Conversion โดยแท็กออนไลน์ก่อนที่จะปรับปรุง
- API อาจใช้เวลาถึง 90 นาทีจึงจะจัดทำดัชนี Conversion ออนไลน์และพร้อมสำหรับการแก้ไข
- ฉันควรให้ความสนใจกับสิ่งใดในการตอบกลับ API
- แม้ว่า Conversion API ของ CM360 จะแสดงการตอบสนองที่สำเร็จ แต่ Conversion บางรายการอาจอัปโหลดหรืออัปเดตไม่สำเร็จ ตรวจสอบช่อง
ConversionStatus
แต่ละช่องเพื่อดูข้อผิดพลาดNOT_FOUND
หากประมวลผล Conversion อาจใช้เวลานานกว่าปกติ คุณควรลองดำเนินการไม่สำเร็จอีกครั้ง นอกจากนี้ โปรดดูคำถามที่พบบ่อยเกี่ยวกับสาเหตุที่ข้อผิดพลาดNOT_FOUND
ยังคงอยู่หลังจากผ่านไปแล้ว 6 ชั่วโมง- ไม่ควรลองแก้ไขข้อผิดพลาด
INVALID_ARGUMENT
และPERMISSION_DENIED
ซ้ำ