待開發客戶強化轉換功能可讓您上傳點擊轉換，其中包含經雜湊處理的使用者 ID 和一些選用的額外詳細資料，有助 Google Ads 將轉換與帶來待開發客戶的廣告建立關聯。
請務必先參閱「開始使用」指南，並導入待開發客戶強化轉換的必要條件，再繼續導入。
您可以透過 Google Ads 使用者介面 (如說明中心所述) 或 Google Ads API (如本指南所述) 上傳待開發客戶強化轉換。
設計整合
您可以設計整合作業。
使用流程
以下是 Google Ads API 中上傳待開發客戶強化轉換的整體流程。
請確認您已實作必要條件，包括：
啟用轉換追蹤。
接受顧客數位資料條款。
設定網站待開發客戶表單的代碼。
如需詳細指引，請參閱「實作必要條件」。
將待開發客戶資料 (例如電子郵件地址、電話號碼和郵寄地址) 標準化並雜湊處理。
將經過正規化和雜湊處理的待開發客戶資料放入
ClickConversion物件。針對每個ClickConversion：使用經過正規化和雜湊處理的待開發客戶資料，填入
user_identifiers。如果您有多個使用者 ID，請為每個 ID 建立個別的UserIdentifier，最多可建立五個 ID。(選用，但強烈建議) 填入
order_id。(選用) 填入
gclid，以便取得最準確的評估資料。請務必填入
ClickConversion物件的consent欄位。將
conversion_action設為ConversionAction的資源名稱，並將type設為UPLOAD_CLICKS。這應該是您在實作必要條件時建立的ConversionAction資源名稱。
將
ClickConversion建立作業上傳至ConversionUploadService，並將partial_failure設為true。查看上傳內容。
最佳做法
導入待開發客戶的進階轉換時，請遵循下列最佳做法。
檢查客戶 ID
上傳轉換時，客戶 ID 必須設為包含轉換動作並執行轉換追蹤的帳戶。如要查看這項設定，請查詢 ConversionTrackingSetting 的 Google Ads 服務資源 Customer。請使用 GoogleAdsService.SearchStream 發出以下查詢，找出 customer.conversion_tracking_setting.google_ads_conversion_customer 的值。
如有，請加入多個 ID
如果您將 order_id 指派給轉換，強烈建議您一併提供。如果您有轉換的 gclid，建議您除了傳送 user_identifiers 之外，也傳送 gclid，以提升成效。此外，如果轉換有超過一個 UserIdentifier，加入多個 UserIdentifier 可以提高比對成功的機率。在同一個 ClickConversion 中加入所有 ID。
設定整合時查看部分失敗錯誤
首次設定待開發客戶強化轉換整合功能時，請檢查並解決回應中 partial_failure_error 欄位中的任何部分錯誤。如果設定有問題，您需要檢查這個欄位，調查並解決問題。如需部分失敗錯誤處理的更多詳細資訊和範例，請參閱專屬的部分失敗指南。
查看部分失敗錯誤時，請參閱疑難排解指南中的常見錯誤表格。解決部分失敗錯誤所顯示的問題，並完成整合後，請改用離線資料診斷功能，定期查看轉換的健康狀況。
在單一要求中批次處理多個轉換
如果您要上傳多筆轉換，請將作業批次處理成一個 UploadClickConversionsRequest，而不要為每筆轉換傳送上傳要求。
請參閱配額指南，瞭解每項要求的轉換次數限制。
如果您希望離線資料診斷功能將一組要求歸類為同一個邏輯工作，請將所有要求的 job_id 設為相同值。如果您有單一工作或程序，使用多個要求上傳大量轉換，這項功能就很實用。如果您將每個要求的 job_id 設為相同值，就可以從 job_summaries 擷取工作相關的單一項目。如果您改為讓 Google Ads API 將系統產生的值指派給每項要求的 job_id，job_summaries 就會為每項要求提供個別的項目，這可能會使分析工作整體健康狀況的難度提高。
上傳所有可用的離線轉換事件
為確保轉換報表完整且準確，請上傳所有可用的離線轉換事件，包括可能不是來自 Google Ads 的事件。
上傳所有轉換事件後，系統會針對任何非 Google Ads 事件產生 CLICK_NOT_FOUND 錯誤。由於上傳所有轉換事件時會發生這些錯誤，因此 UploadClickConversionsRequest 會包含 debug_enabled 欄位。
如果
debug_enabled為false或未設定，Google Ads API 只會執行基本輸入驗證，略過後續上傳檢查，即使系統找不到所提供user_identifiers的點擊，也會傳回成功。此為預設值。
如果
debug_enabled為true，Google Ads API 會執行所有驗證，並針對任何ClickConversion傳回CLICK_NOT_FOUND錯誤，因為這些ClickConversion沒有提供的user_identifiers的 Google Ads 轉換。
在開發和測試期間，您可以將 debug_enabled 設為 true，以利找出問題。舉例來說，如果您有一系列轉換和 user_identifiers，且您知道這些轉換來自 Google Ads 轉換，則可以使用 true 設定驗證這些上傳內容不會導致 CLICK_NOT_FOUND 錯誤。不過，在開發和測試完成後，建議您將 debug_enabled 設為 false，以免發生過多錯誤。
請勿使用外部歸因資料
請勿在 ClickConversion 上設定 external_attribution_data，或指定使用外部歸因模式的 conversion_action。Google Ads 不支援使用 ID 上傳資料時，外部歸因的轉換。
準備要上傳的資料
基於隱私權考量，下列資料必須先使用 SHA-256 進行雜湊處理，才能上傳：
- 電子郵件地址
- 電話號碼
- 名字
- 姓氏
- 街道地址
請勿雜湊處理下列資料：
- 國家/地區
- 州
- 城市
- 郵遞區號
為了使雜湊處理結果標準化，在對下列任一值進行雜湊處理前，您必須先完成下列事項：
- 移除開頭和結尾的空白字元。
- 將文字轉換為小寫。
- 根據 E164 標準設定電話號碼格式。
- 移除
gmail.com和googlemail.com電子郵件地址中網域名稱前的所有半形句號 (.)。
Java
private String normalizeAndHash(MessageDigest digest, String s)
throws UnsupportedEncodingException {
// Normalizes by first converting all characters to lowercase, then trimming spaces.
String normalized = s.toLowerCase();
// Removes leading, trailing, and intermediate spaces.
normalized = normalized.replaceAll("\\s+", "");
// 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, Google Ads
* 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);
}
C#
/// <summary>
/// Normalizes the email address and hashes it. For this use case, Google Ads 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();
}
PHP
private static function normalizeAndHash(string $hashAlgorithm, string $value): string
{
// Normalizes by first converting all characters to lowercase, then trimming spaces.
$normalized = strtolower($value);
// Removes leading, trailing, and intermediate spaces.
$normalized = str_replace(' ', '', $normalized);
return hash($hashAlgorithm, strtolower(trim($normalized)));
}
/**
* Returns the result of normalizing and hashing an email address. For this use case, Google
* Ads 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, Google Ads 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, Google Ads 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
Perl
sub normalize_and_hash {
my $value = shift;
# Removes leading, trailing, and intermediate spaces.
$value =~ s/\s+//g;
return sha256_hex(lc $value);
}
# Returns the result of normalizing and hashing an email address. For this use
# case, Google Ads requires removal of any '.' characters preceding 'gmail.com'
# or 'googlemail.com'.
sub normalize_and_hash_email_address {
my $email_address = shift;
my $normalized_email = lc $email_address;
my @email_parts = split('@', $normalized_email);
if (scalar @email_parts > 1
&& $email_parts[1] =~ /^(gmail|googlemail)\.com\s*/)
{
# Remove any '.' characters from the portion of the email address before the
# domain if the domain is 'gmail.com' or 'googlemail.com'.
$email_parts[0] =~ s/\.//g;
$normalized_email = sprintf '%s@%s', $email_parts[0], $email_parts[1];
}
return normalize_and_hash($normalized_email);
}
上傳強化轉換
以下程式碼片段示範如何建構轉換上傳內容，其中包含電子郵件地址和電話號碼的 ID，並視需要套用標準化和雜湊運算。最佳做法是將 gclid 和 order_id 納入轉換 (如果可用)。
在 ClickConversion 中加入使用者 ID
Java
// Creates an empty builder for constructing the click conversion.
ClickConversion.Builder clickConversionBuilder = ClickConversion.newBuilder();
// Extracts user email and phone from the raw data, normalizes and hashes it, then wraps it in
// UserIdentifier objects.
// Creates a separate UserIdentifier object for each. The data in this example is hardcoded, but
// in your application you might read the raw data from an input file.
// IMPORTANT: Since the identifier attribute of UserIdentifier
// (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) is a
// oneof
// (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set only ONE of
// hashedEmail, hashedPhoneNumber, mobileId, thirdPartyUserId, or addressInfo. Setting more
// than one of these attributes on the same UserIdentifier will clear all the other members
// of the oneof. For example, the following code is INCORRECT and will result in a
// UserIdentifier with ONLY a hashedPhoneNumber.
//
// UserIdentifier incorrectlyPopulatedUserIdentifier =
// UserIdentifier.newBuilder()
// .setHashedEmail("...")
// .setHashedPhoneNumber("...")
// .build();
ImmutableMap.Builder<String, String> rawRecordBuilder =
ImmutableMap.<String, String>builder()
.put("email", "alex.2@example.com")
// Phone number to be converted to E.164 format, with a leading '+' as required.
.put("phone", "+1 800 5550102")
// This example lets you put conversion details as arguments, but in reality you might
// store this data alongside other user data, so we include it in this sample user
// record.
.put("conversionActionId", Long.toString(conversionActionId))
.put("conversionDateTime", conversionDateTime)
.put("conversionValue", Double.toString(conversionValue))
.put("currencyCode", "USD");
// Adds entries for the optional fields.
if (orderId != null) {
rawRecordBuilder.put("orderId", orderId);
}
if (gclid != null) {
rawRecordBuilder.put("gclid", gclid);
}
if (adUserDataConsent != null) {
rawRecordBuilder.put("adUserDataConsent", adUserDataConsent.name());
}
// Builds the map representing the record.
Map<String, String> rawRecord = rawRecordBuilder.build();
// Creates a SHA256 message digest for hashing user identifiers in a privacy-safe way, as
// described at https://support.google.com/google-ads/answer/9888656.
MessageDigest sha256Digest = MessageDigest.getInstance("SHA-256");
// Creates a list for the user identifiers.
List<UserIdentifier> userIdentifiers = new ArrayList<>();
// Creates a user identifier using the hashed email address, using the normalize and hash method
// specifically for email addresses.
UserIdentifier emailIdentifier =
UserIdentifier.newBuilder()
// Optional: specify the user identifier source.
.setUserIdentifierSource(UserIdentifierSource.FIRST_PARTY)
// Uses the normalize and hash method specifically for email addresses.
.setHashedEmail(normalizeAndHashEmailAddress(sha256Digest, rawRecord.get("email")))
.build();
userIdentifiers.add(emailIdentifier);
// Creates a user identifier using normalized and hashed phone info.
UserIdentifier hashedPhoneNumberIdentifier =
UserIdentifier.newBuilder()
.setHashedPhoneNumber(normalizeAndHash(sha256Digest, rawRecord.get("phone")))
.build();
// Adds the hashed phone number identifier to the UserData object's list.
userIdentifiers.add(hashedPhoneNumberIdentifier);
// Adds the user identifiers to the conversion.
clickConversionBuilder.addAllUserIdentifiers(userIdentifiers);
C#
// Adds a user identifier using the hashed email address, using the normalize
// and hash method specifically for email addresses.
clickConversion.UserIdentifiers.Add(new UserIdentifier()
{
HashedEmail = NormalizeAndHashEmailAddress("alex.2@example.com"),
// Optional: Specifies the user identifier source.
UserIdentifierSource = UserIdentifierSource.FirstParty
});
// Adds a user identifier using normalized and hashed phone info.
clickConversion.UserIdentifiers.Add(new UserIdentifier()
{
HashedPhoneNumber = NormalizeAndHash("+1 800 5550102"),
// Optional: Specifies the user identifier source.
UserIdentifierSource = UserIdentifierSource.FirstParty
});
// Adds a user identifier with all the required mailing address elements.
clickConversion.UserIdentifiers.Add(new UserIdentifier()
{
AddressInfo = new OfflineUserAddressInfo()
{
// FirstName and LastName must be normalized and hashed.
HashedFirstName = NormalizeAndHash("Alex"),
HashedLastName = NormalizeAndHash("Quinn"),
// CountryCode and PostalCode are sent in plain text.
CountryCode = "US",
PostalCode = "94045"
}
});
PHP
// Creates a click conversion with the specified attributes.
$clickConversion = new ClickConversion();
// Extract user email and phone from the raw data, normalize and hash it, then wrap it in
// UserIdentifier objects. Creates a separate UserIdentifier object for each.
// The data in this example is hardcoded, but in your application you might read the raw
// data from an input file.
// IMPORTANT: Since the identifier attribute of UserIdentifier
// (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) is a
// oneof
// (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set only ONE
// of hashedEmail, hashedPhoneNumber, mobileId, thirdPartyUserId, or addressInfo. Setting
// more than one of these attributes on the same UserIdentifier will clear all the other
// members of the oneof. For example, the following code is INCORRECT and will result in a
// UserIdentifier with ONLY a hashedPhoneNumber.
//
// $incorrectlyPopulatedUserIdentifier = new UserIdentifier([
// 'hashed_email' => '...',
// 'hashed_phone_number' => '...'
// ]);
$rawRecord = [
// Email address that includes a period (.) before the Gmail domain.
'email' => 'alex.2@example.com',
// Phone number to be converted to E.164 format, with a leading '+' as required.
'phone' => '+1 800 5550102',
// This example lets you input conversion details as arguments, but in reality you might
// store this data alongside other user data, so we include it in this sample user
// record.
'orderId' => $orderId,
'gclid' => $gclid,
'conversionActionId' => $conversionActionId,
'conversionDateTime' => $conversionDateTime,
'conversionValue' => $conversionValue,
'currencyCode' => 'USD',
'adUserDataConsent' => $adUserDataConsent
];
// Creates a list for the user identifiers.
$userIdentifiers = [];
// Uses the SHA-256 hash algorithm for hashing user identifiers in a privacy-safe way, as
// described at https://support.google.com/google-ads/answer/9888656.
$hashAlgorithm = "sha256";
// Creates a user identifier using the hashed email address, using the normalize and hash
// method specifically for email addresses.
$emailIdentifier = new UserIdentifier([
// Uses the normalize and hash method specifically for email addresses.
'hashed_email' => self::normalizeAndHashEmailAddress(
$hashAlgorithm,
$rawRecord['email']
),
// Optional: Specifies the user identifier source.
'user_identifier_source' => UserIdentifierSource::FIRST_PARTY
]);
$userIdentifiers[] = $emailIdentifier;
// Checks if the record has a phone number, and if so, adds a UserIdentifier for it.
if (array_key_exists('phone', $rawRecord)) {
$hashedPhoneNumberIdentifier = new UserIdentifier([
'hashed_phone_number' => self::normalizeAndHash(
$hashAlgorithm,
$rawRecord['phone'],
true
)
]);
// Adds the hashed email identifier to the user identifiers list.
$userIdentifiers[] = $hashedPhoneNumberIdentifier;
}
// Adds the user identifiers to the conversion.
$clickConversion->setUserIdentifiers($userIdentifiers);
Python
# Extract user email and phone from the raw data, normalize and hash it,
# then wrap it in UserIdentifier objects. Create a separate UserIdentifier
# object for each. The data in this example is hardcoded, but in your
# application you might read the raw data from an input file.
# IMPORTANT: Since the identifier attribute of UserIdentifier
# (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
# is a oneof
# (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must
# set only ONE of hashed_email, hashed_phone_number, mobile_id,
# third_party_user_id, or address_info. Setting more than one of these
# attributes on the same UserIdentifier will clear all the other members of
# the oneof. For example, the following code is INCORRECT and will result in
# a UserIdentifier with ONLY a hashed_phone_number:
#
# incorrectly_populated_user_identifier = client.get_type("UserIdentifier")
# incorrectly_populated_user_identifier.hashed_email = "...""
# incorrectly_populated_user_identifier.hashed_phone_number = "...""
raw_record = {
# Email address that includes a period (.) before the Gmail domain.
"email": "alex.2@example.com",
# Phone number to be converted to E.164 format, with a leading '+' as
# required.
"phone": "+1 800 5550102",
# This example lets you input conversion details as arguments,
# but in reality you might store this data alongside other user data,
# so we include it in this sample user record.
"order_id": order_id,
"gclid": gclid,
"conversion_action_id": conversion_action_id,
"conversion_date_time": conversion_date_time,
"conversion_value": conversion_value,
"currency_code": "USD",
"ad_user_data_consent": ad_user_data_consent,
}
# Constructs the click conversion.
click_conversion = client.get_type("ClickConversion")
# Creates a user identifier using the hashed email address, using the
# normalize and hash method specifically for email addresses.
email_identifier = client.get_type("UserIdentifier")
# Optional: Specifies the user identifier source.
email_identifier.user_identifier_source = (
client.enums.UserIdentifierSourceEnum.FIRST_PARTY
)
# Uses the normalize and hash method specifically for email addresses.
email_identifier.hashed_phone_number = normalize_and_hash_email_address(
raw_record["email"]
)
# Adds the user identifier to the conversion.
click_conversion.user_identifiers.append(email_identifier)
# Checks if the record has a phone number, and if so, adds a UserIdentifier
# for it.
if raw_record.get("phone") is not None:
phone_identifier = client.get_type("UserIdentifier")
phone_identifier.hashed_phone_number = normalize_and_hash(
raw_record["phone"]
)
# Adds the phone identifier to the conversion adjustment.
click_conversion.user_identifiers.append(phone_identifier)
小茹
# Extract user email and phone from the raw data, normalize and hash it,
# then wrap it in UserIdentifier objects. Create a separate UserIdentifier
# object for each. The data in this example is hardcoded, but in your
# application you might read the raw data from an input file.
# IMPORTANT: Since the identifier attribute of UserIdentifier
# (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
# is a oneof
# (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must
# set only ONE of hashed_email, hashed_phone_number, mobile_id,
# third_party_user_id, or address_info. Setting more than one of these
# attributes on the same UserIdentifier will clear all the other members of
# the oneof. For example, the following code is INCORRECT and will result in
# a UserIdentifier with ONLY a hashed_phone_number:
#
# incorrectly_populated_user_identifier.hashed_email = "...""
# incorrectly_populated_user_identifier.hashed_phone_number = "...""
raw_record = {
# Email address that includes a period (.) before the Gmail domain.
"email" => "alex.2@example.com",
# Phone number to be converted to E.164 format, with a leading '+' as
# required.
"phone" => "+1 800 5550102",
# This example lets you input conversion details as arguments,
# but in reality you might store this data alongside other user data,
# so we include it in this sample user record.
"order_id" => order_id,
"gclid" => gclid,
"conversion_action_id" => conversion_action_id,
"conversion_date_time" => conversion_date_time,
"conversion_value" => conversion_value,
"currency_code" => "USD",
"ad_user_data_consent" => ad_user_data_consent,
}
click_conversion = client.resource.click_conversion do |cc|
cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
cc.conversion_date_time = conversion_date_time
cc.conversion_value = conversion_value.to_f
cc.currency_code = 'USD'
unless order_id.nil?
cc.order_id = order_id
end
unless raw_record["gclid"].nil?
cc.gclid = gclid
end
# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
unless raw_record["ad_user_data_consent"].nil?
cc.consent = client.resource.consent do |c|
c.ad_user_data = ad_user_data_consent
end
end
# Creates a user identifier using the hashed email address, using the
# normalize and hash method specifically for email addresses.
# If using a phone number, use the normalize_and_hash method instead.
cc.user_identifiers << client.resource.user_identifier do |ui|
ui.hashed_phone_number = normalize_and_hash_email(raw_record["email"])
# Optional: Specifies the user identifier source.
ui.user_identifier_source = :FIRST_PARTY
end
# Checks if the record has a phone number, and if so, adds a UserIdentifier
# for it.
unless raw_record["phone"].nil?
cc.user_identifiers << client.resource.user_identifier do |ui|
ui.hashed_phone_number = normalize_and_hash_email(raw_record["phone"])
end
end
end
Perl
# Create an empty click conversion.
my $click_conversion =
Google::Ads::GoogleAds::V18::Services::ConversionUploadService::ClickConversion
->new({});
# Extract user email and phone from the raw data, normalize and hash it,
# then wrap it in UserIdentifier objects. Create a separate UserIdentifier
# object for each.
# The data in this example is hardcoded, but in your application
# you might read the raw data from an input file.
#
# IMPORTANT: Since the identifier attribute of UserIdentifier
# (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
# is a oneof
# (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set
# only ONE of hashed_email, hashed_phone_number, mobile_id, third_party_user_id,
# or address-info. Setting more than one of these attributes on the same UserIdentifier
# will clear all the other members of the oneof. For example, the following code is
# INCORRECT and will result in a UserIdentifier with ONLY a hashed_phone_number:
#
# my $incorrect_user_identifier = Google::Ads::GoogleAds::V18::Common::UserIdentifier->new({
# hashedEmail => '...',
# hashedPhoneNumber => '...',
# });
my $raw_record = {
# Email address that includes a period (.) before the Gmail domain.
email => 'alex.2@example.com',
# Phone number to be converted to E.164 format, with a leading '+' as
# required.
phone => '+1 800 5550102',
# This example lets you input conversion details as arguments,
# but in reality you might store this data alongside other user data,
# so we include it in this sample user record.
orderId => $order_id,
gclid => $gclid,
conversionActionId => $conversion_action_id,
conversionDateTime => $conversion_date_time,
conversionValue => $conversion_value,
currencyCode => "USD",
adUserDataConsent => $ad_user_data_consent
};
my $user_identifiers = [];
# Create a user identifier using the hashed email address, using the normalize
# and hash method specifically for email addresses.
my $hashed_email = normalize_and_hash_email_address($raw_record->{email});
push(
@$user_identifiers,
Google::Ads::GoogleAds::V18::Common::UserIdentifier->new({
hashedEmail => $hashed_email,
# Optional: Specify the user identifier source.
userIdentifierSource => FIRST_PARTY
}));
# Create a user identifier using normalized and hashed phone info.
my $hashed_phone = normalize_and_hash($raw_record->{phone});
push(
@$user_identifiers,
Google::Ads::GoogleAds::V18::Common::UserIdentifier->new({
hashedPhone => $hashed_phone,
# Optional: Specify the user identifier source.
userIdentifierSource => FIRST_PARTY
}));
# Add the user identifiers to the conversion.
$click_conversion->{userIdentifiers} = $user_identifiers;
在 ClickConversion 中新增轉換詳細資料
Java
// Adds details of the conversion.
clickConversionBuilder.setConversionAction(
ResourceNames.conversionAction(
customerId, Long.parseLong(rawRecord.get("conversionActionId"))));
clickConversionBuilder.setConversionDateTime(rawRecord.get("conversionDateTime"));
clickConversionBuilder.setConversionValue(Double.parseDouble(rawRecord.get("conversionValue")));
clickConversionBuilder.setCurrencyCode(rawRecord.get("currencyCode"));
// Sets the order ID if provided.
if (rawRecord.containsKey("orderId")) {
clickConversionBuilder.setOrderId(rawRecord.get("orderId"));
}
// Sets the Google click ID (gclid) if provided.
if (rawRecord.containsKey("gclid")) {
clickConversionBuilder.setGclid(rawRecord.get("gclid"));
}
// Sets the consent information, if provided.
if (rawRecord.containsKey("adUserDataConsent")) {
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy for details.
clickConversionBuilder.setConsent(
Consent.newBuilder()
.setAdUserData(ConsentStatus.valueOf(rawRecord.get("adUserDataConsent"))));
}
// Calls build to build the conversion.
ClickConversion clickConversion = clickConversionBuilder.build();
C#
// Adds details of the conversion.
clickConversion.ConversionAction =
ResourceNames.ConversionAction(customerId, conversionActionId);
clickConversion.ConversionDateTime = conversionDateTime;
clickConversion.ConversionValue = conversionValue;
clickConversion.CurrencyCode = "USD";
// Sets the order ID if provided.
if (!string.IsNullOrEmpty(orderId))
{
clickConversion.OrderId = orderId;
}
// Sets the Google click ID (gclid) if provided.
if (!string.IsNullOrEmpty(gclid))
{
clickConversion.Gclid = gclid;
}
PHP
// Adds details of the conversion.
$clickConversion->setConversionAction(
ResourceNames::forConversionAction($customerId, $rawRecord['conversionActionId'])
);
$clickConversion->setConversionDateTime($rawRecord['conversionDateTime']);
$clickConversion->setConversionValue($rawRecord['conversionValue']);
$clickConversion->setCurrencyCode($rawRecord['currencyCode']);
// Sets the order ID if provided.
if (!empty($rawRecord['orderId'])) {
$clickConversion->setOrderId($rawRecord['orderId']);
}
// Sets the Google click ID (gclid) if provided.
if (!empty($rawRecord['gclid'])) {
$clickConversion->setGclid($rawRecord['gclid']);
}
// Sets the ad user data consent if provided.
if (!empty($rawRecord['adUserDataConsent'])) {
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy for details.
$clickConversion->setConsent(
new Consent(['ad_user_data' => $rawRecord['adUserDataConsent']])
);
}
Python
# Add details of the conversion.
# Gets the conversion action resource name.
conversion_action_service = client.get_service("ConversionActionService")
click_conversion.conversion_action = (
conversion_action_service.conversion_action_path(
customer_id, raw_record["conversion_action_id"]
)
)
click_conversion.conversion_date_time = raw_record["conversion_date_time"]
click_conversion.conversion_value = raw_record["conversion_value"]
click_conversion.currency_code = raw_record["currency_code"]
# Sets the order ID if provided.
if raw_record.get("order_id"):
click_conversion.order_id = raw_record["order_id"]
# Sets the gclid if provided.
if raw_record.get("gclid"):
click_conversion.gclid = raw_record["gclid"]
# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
if raw_record["ad_user_data_consent"]:
click_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[
raw_record["ad_user_data_consent"]
]
小茹
cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
cc.conversion_date_time = conversion_date_time
cc.conversion_value = conversion_value.to_f
cc.currency_code = 'USD'
unless order_id.nil?
cc.order_id = order_id
end
unless raw_record["gclid"].nil?
cc.gclid = gclid
end
# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
unless raw_record["ad_user_data_consent"].nil?
cc.consent = client.resource.consent do |c|
c.ad_user_data = ad_user_data_consent
end
end
Perl
# Add details of the conversion.
$click_conversion->{conversionAction} =
Google::Ads::GoogleAds::V18::Utils::ResourceNames::conversion_action(
$customer_id, $raw_record->{conversionActionId});
$click_conversion->{conversionDateTime} = $raw_record->{conversionDateTime};
$click_conversion->{conversionValue} = $raw_record->{conversionValue};
$click_conversion->{currencyCode} = $raw_record->{currencyCode};
# Set the order ID if provided.
if (defined $raw_record->{orderId}) {
$click_conversion->{orderId} = $raw_record->{orderId};
}
# Set the Google click ID (gclid) if provided.
if (defined $raw_record->{gclid}) {
$click_conversion->{gclid} = $raw_record->{gclid};
}
# Set the consent information, if provided.
if (defined $raw_record->{adUserDataConsent}) {
$click_conversion->{consent} =
Google::Ads::GoogleAds::V18::Common::Consent->new({
adUserData => $raw_record->{adUserDataConsent}});
}
上傳點擊轉換
Java
// Creates the conversion upload service client.
try (ConversionUploadServiceClient conversionUploadServiceClient =
googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) {
// Uploads the click conversion. Partial failure should always be set to true.
// NOTE: This request contains a single conversion as a demonstration. However, if you have
// multiple conversions to upload, it's best to upload multiple conversions per request
// instead of sending a separate request per conversion. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
UploadClickConversionsResponse response =
conversionUploadServiceClient.uploadClickConversions(
UploadClickConversionsRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.addConversions(clickConversion)
// Enables partial failure (must be true).
.setPartialFailure(true)
.build());
C#
// Uploads the click conversion. Partial failure should always be set to true.
// NOTE: This request contains a single conversion as a demonstration.
// However, if you have multiple conversions to upload, it's best to upload multiple
// conversions per request instead of sending a separate request per conversion.
// See the following for per-request limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload
UploadClickConversionsResponse response =
conversionUploadService.UploadClickConversions(
new UploadClickConversionsRequest()
{
CustomerId = customerId.ToString(),
Conversions = { clickConversion },
// Enables partial failure (must be true).
PartialFailure = true
});
PHP
// Issues a request to upload the click conversion.
$conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
// NOTE: This request contains a single conversion as a demonstration. However, if you have
// multiple conversions to upload, it's best to upload multiple conversions per request
// instead of sending a separate request per conversion. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
$response = $conversionUploadServiceClient->uploadClickConversions(
// Enables partial failure (must be true).
UploadClickConversionsRequest::build($customerId, [$clickConversion], true)
);
Python
# Creates the conversion upload service client.
conversion_upload_service = client.get_service("ConversionUploadService")
# Uploads the click conversion. Partial failure should always be set to
# True.
# NOTE: This request only uploads a single conversion, but if you have
# multiple conversions to upload, it's most efficient to upload them in a
# single request. See the following for per-request limits for reference:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
response = conversion_upload_service.upload_click_conversions(
customer_id=customer_id,
conversions=[click_conversion],
# Enables partial failure (must be true).
partial_failure=True,
)
小茹
response = client.service.conversion_upload.upload_click_conversions(
customer_id: customer_id,
conversions: [click_conversion],
# Partial failure must be true.
partial_failure: true,
)
if response.partial_failure_error
puts "Partial failure encountered: #{response.partial_failure_error.message}"
else
result = response.results.first
puts "Uploaded click conversion that happened at #{result.conversion_date_time} " \
"to #{result.conversion_action}."
end
Perl
# Upload the click conversion. Partial failure should always be set to true.
#
# NOTE: This request contains a single conversion as a demonstration.
# However, if you have multiple conversions to upload, it's best to
# upload multiple conversions per request instead of sending a separate
# request per conversion. See the following for per-request limits:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
my $response =
$api_client->ConversionUploadService()->upload_click_conversions({
customerId => $customer_id,
conversions => [$click_conversion],
# Enable partial failure (must be true).
partialFailure => "true"
});
查看上傳內容
使用離線資料診斷功能，查看最近上傳內容的整體健康狀況。請注意，上傳成功不一定代表上傳內容與目標相符。
在報表中顯示廣告活動的轉換指標時，請參閱「對應使用者介面指標」，將 Google Ads UI 指標與 Google Ads API 報表欄位建立關聯。您也可以查詢 conversion_action 資源，查看指定轉換動作的轉換總數和轉換總價值。
後續步驟
如需調整轉換，請參閱上傳轉換調整指南。
如需待開發客戶強化轉換整合功能的疑難排解指南，請參閱疑難排解指南。