Java
// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.ads.googleads.examples.remarketing;
import com.beust.jcommander.Parameter;
import com.google.ads.googleads.examples.utils.ArgumentNames;
import com.google.ads.googleads.examples.utils.CodeSampleParams;
import com.google.ads.googleads.lib.GoogleAdsClient;
import com.google.ads.googleads.v16.common.OfflineUserAddressInfo;
import com.google.ads.googleads.v16.common.UserIdentifier;
import com.google.ads.googleads.v16.enums.ConversionAdjustmentTypeEnum.ConversionAdjustmentType;
import com.google.ads.googleads.v16.enums.UserIdentifierSourceEnum.UserIdentifierSource;
import com.google.ads.googleads.v16.errors.GoogleAdsError;
import com.google.ads.googleads.v16.errors.GoogleAdsException;
import com.google.ads.googleads.v16.services.ConversionAdjustment;
import com.google.ads.googleads.v16.services.ConversionAdjustmentResult;
import com.google.ads.googleads.v16.services.ConversionAdjustmentUploadServiceClient;
import com.google.ads.googleads.v16.services.GclidDateTimePair;
import com.google.ads.googleads.v16.services.UploadConversionAdjustmentsRequest;
import com.google.ads.googleads.v16.services.UploadConversionAdjustmentsResponse;
import com.google.ads.googleads.v16.utils.ResourceNames;
import com.google.common.collect.ImmutableMap;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* Enhances a web conversion by uploading a {@link ConversionAdjustment} containing hashed user
* identifiers and an order ID.
*/
public class UploadEnhancedConversionsForWeb {
private static class UploadEnhancedConversionsForWebParams extends CodeSampleParams {
@Parameter(names = ArgumentNames.CUSTOMER_ID, required = true)
private long customerId;
@Parameter(names = ArgumentNames.CONVERSION_ACTION_ID, required = true)
private long conversionActionId;
@Parameter(names = ArgumentNames.ORDER_ID, required = true)
private String orderId;
@Parameter(
names = ArgumentNames.CONVERSION_DATE_TIME,
required = false,
description =
"The date time at which the conversion with the specified order ID occurred. "
+ "Must be after the click time, and must include the time zone offset. "
+ "The format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm', e.g. '2019-01-01 12:32:45-08:00'. "
+ "Setting this field is optional, but recommended.")
private String conversionDateTime;
@Parameter(names = ArgumentNames.USER_AGENT, required = false)
private String userAgent;
}
public static void main(String[] args)
throws UnsupportedEncodingException, NoSuchAlgorithmException {
UploadEnhancedConversionsForWebParams params = new UploadEnhancedConversionsForWebParams();
if (!params.parseArguments(args)) {
// Either pass the required parameters for this example on the command line, or insert them
// into the code here. See the parameter class definition above for descriptions.
params.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
params.conversionActionId = Long.parseLong("INSERT_CONVERSION_ACTION_ID_HERE");
params.orderId = "INSERT_ORDER_ID_HERE";
// Optional: Specify the conversion date/time and user agent.
params.conversionDateTime = null;
params.userAgent = null;
}
GoogleAdsClient googleAdsClient = null;
try {
googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
System.err.printf(
"Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
System.exit(1);
} catch (IOException ioe) {
System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
System.exit(1);
}
try {
new UploadEnhancedConversionsForWeb()
.runExample(
googleAdsClient,
params.customerId,
params.conversionActionId,
params.orderId,
params.conversionDateTime,
params.userAgent);
} catch (GoogleAdsException gae) {
// GoogleAdsException is the base class for most exceptions thrown by an API request.
// Instances of this exception have a message and a GoogleAdsFailure that contains a
// collection of GoogleAdsErrors that indicate the underlying causes of the
// GoogleAdsException.
System.err.printf(
"Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
gae.getRequestId());
int i = 0;
for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
System.err.printf(" Error %d: %s%n", i++, googleAdsError);
}
System.exit(1);
}
}
/**
* Runs the example.
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @param conversionActionId conversion action ID associated with this conversion.
* @param orderId unique order ID (transaction ID) of the conversion.
* @param conversionDateTime date and time of the conversion.
* @param userAgent the HTTP user agent of the conversion.
*/
private void runExample(
GoogleAdsClient googleAdsClient,
long customerId,
long conversionActionId,
String orderId,
String conversionDateTime,
String userAgent)
throws NoSuchAlgorithmException, UnsupportedEncodingException {
// Creates a builder for constructing the enhancement adjustment.
ConversionAdjustment.Builder enhancementBuilder =
ConversionAdjustment.newBuilder().setAdjustmentType(ConversionAdjustmentType.ENHANCEMENT);
// Extracts user email, phone, and address info 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();
Map<String, String> rawRecord =
ImmutableMap.<String, String>builder()
// Email address that includes a period (.) before the Gmail domain.
.put("email", "alex.2@example.com")
// Address that includes all four required elements: first name, last name, country
// code, and postal code.
.put("firstName", "Alex")
.put("lastName", "Quinn")
.put("countryCode", "US")
.put("postalCode", "94045")
// Phone number to be converted to E.164 format, with a leading '+' as required.
.put("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.
.put("orderId", orderId)
.put("conversionActionId", Long.toString(conversionActionId))
.put("conversionDateTime", conversionDateTime)
.put("currencyCode", "USD")
.put("userAgent", userAgent)
.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);
// Checks if the record has a phone number, and if so, adds a UserIdentifier for it.
if (rawRecord.containsKey("phone")) {
UserIdentifier hashedPhoneNumberIdentifier =
UserIdentifier.newBuilder()
.setHashedPhoneNumber(normalizeAndHash(sha256Digest, rawRecord.get("phone"), true))
.build();
// Adds the hashed phone number identifier to the UserData object's list.
userIdentifiers.add(hashedPhoneNumberIdentifier);
}
// Checks if the record has all the required mailing address elements, and if so, adds a
// UserIdentifier for the mailing address.
if (rawRecord.containsKey("firstName")) {
// Checks if the record contains all the other required elements of a mailing address.
Set<String> missingAddressKeys = new HashSet<>();
for (String addressKey : new String[] {"lastName", "countryCode", "postalCode"}) {
if (!rawRecord.containsKey(addressKey)) {
missingAddressKeys.add(addressKey);
}
}
if (!missingAddressKeys.isEmpty()) {
System.out.printf(
"Skipping addition of mailing address information because the following required keys"
+ " are missing: %s%n",
missingAddressKeys);
} else {
// Creates an OfflineUserAddressInfo object that contains all the required elements of a
// mailing address.
OfflineUserAddressInfo addressInfo =
OfflineUserAddressInfo.newBuilder()
.setHashedFirstName(
normalizeAndHash(sha256Digest, rawRecord.get("firstName"), false))
.setHashedLastName(normalizeAndHash(sha256Digest, rawRecord.get("lastName"), false))
.setCountryCode(rawRecord.get("countryCode"))
.setPostalCode(rawRecord.get("postalCode"))
.build();
UserIdentifier addressIdentifier =
UserIdentifier.newBuilder().setAddressInfo(addressInfo).build();
// Adds the address identifier to the UserData object's list.
userIdentifiers.add(addressIdentifier);
}
}
// Adds the user identifiers to the enhancement adjustment.
enhancementBuilder.addAllUserIdentifiers(userIdentifiers);
// Sets the conversion action.
enhancementBuilder.setConversionAction(
ResourceNames.conversionAction(
customerId, Long.parseLong(rawRecord.get("conversionActionId"))));
// Sets the order ID. Enhancements MUST use order ID instead of GCLID date/time pair.
enhancementBuilder.setOrderId(rawRecord.get("orderId"));
// Sets the conversion date and time if provided. Providing this value is optional but
// recommended.
if (rawRecord.get("conversionDateTime") != null) {
enhancementBuilder.setGclidDateTimePair(
GclidDateTimePair.newBuilder()
.setConversionDateTime(rawRecord.get("conversionDateTime")));
}
// Sets the user agent if provided. This should match the user agent of the request that sent
// the original conversion so the conversion and its enhancement are either both attributed as
// same-device or both attributed as cross-device.
if (rawRecord.get("userAgent") != null) {
enhancementBuilder.setUserAgent(rawRecord.get("userAgent"));
}
// Creates the conversion adjustment upload service client.
try (ConversionAdjustmentUploadServiceClient conversionUploadServiceClient =
googleAdsClient.getLatestVersion().createConversionAdjustmentUploadServiceClient()) {
// Uploads the enhancement adjustment. Partial failure should always be set to true.
// NOTE: This request contains a single adjustment as a demonstration. However, if you have
// multiple adjustments to upload, it's best to upload multiple adjustments per request
// instead of sending a separate request per adjustment. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_adjustment_upload_service
UploadConversionAdjustmentsResponse response =
conversionUploadServiceClient.uploadConversionAdjustments(
UploadConversionAdjustmentsRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.addConversionAdjustments(enhancementBuilder)
// Enables partial failure (must be true).
.setPartialFailure(true)
.build());
// Prints any partial errors returned.
// To review the overall health of your recent uploads, see:
// https://developers.google.com/google-ads/api/docs/conversions/upload-summaries
if (response.hasPartialFailureError()) {
System.out.printf(
"Partial error encountered: '%s'.%n", response.getPartialFailureError().getMessage());
} else {
// Prints the result.
ConversionAdjustmentResult result = response.getResults(0);
System.out.printf(
"Uploaded conversion adjustment of '%s' for order ID '%s'.%n",
result.getConversionAction(), result.getOrderId());
}
}
}
/**
* 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.
*
* @param digest the digest to use to hash the normalized string.
* @param s the string to normalize and hash.
* @param trimIntermediateSpaces if true, removes leading, trailing, and intermediate spaces from
* the string before hashing. If false, only removes leading and trailing spaces from the
* string before hashing.
*/
private String normalizeAndHash(MessageDigest digest, String s, boolean trimIntermediateSpaces)
throws UnsupportedEncodingException {
// Normalizes by first converting all characters to lowercase, then trimming spaces.
String normalized = s.toLowerCase();
if (trimIntermediateSpaces) {
// Removes leading, trailing, and intermediate spaces.
normalized = normalized.replaceAll("\\s+", "");
} else {
// Removes only leading and trailing spaces.
normalized = normalized.trim();
}
// 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, true);
}
}
C#
// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V16.Common;
using Google.Ads.GoogleAds.V16.Errors;
using Google.Ads.GoogleAds.V16.Resources;
using Google.Ads.GoogleAds.V16.Services;
using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using static Google.Ads.GoogleAds.V16.Enums.ConversionAdjustmentTypeEnum.Types;
using static Google.Ads.GoogleAds.V16.Enums.UserIdentifierSourceEnum.Types;
namespace Google.Ads.GoogleAds.Examples.V16
{
/// <summary>
/// This code example enhances a web conversion by uploading a {@link ConversionAdjustment}
/// containing hashed user identifiers and an order ID.
/// </summary>
public class UploadEnhancedConversionsForWeb : ExampleBase
{
/// <summary>
/// Command line options for running the <see cref="UploadEnhancedConversionsForWeb"/> example.
/// </summary>
public class Options : OptionsBase
{
/// <summary>
/// The Google Ads customer ID for which the conversion action is added.
/// </summary>
[Option("customerId", Required = true, HelpText =
"The Google Ads customer ID for which the conversion action is added.")]
public long CustomerId { get; set; }
/// <summary>
/// ID of the conversion action for which adjustments are uploaded.
/// </summary>
[Option("conversionActionId", Required = true, HelpText =
"ID of the conversion action for which adjustments are uploaded.")]
public long ConversionActionId { get; set; }
/// <summary>
/// The unique order ID (transaction ID) of the conversion.
/// </summary>
[Option("orderId", Required = true, HelpText =
"The unique order ID (transaction ID) of the conversion.")]
public string OrderId { get; set; }
/// <summary>
/// The date time at which the conversion with the specified order ID occurred. Must
/// be after the click time, and must include the time zone offset. The format is
/// 'yyyy-mm-dd hh:mm:ss+|-hh:mm', e.g. '2019-01-01 12:32:45-08:00'. Setting this
/// field is optional, but recommended.
/// </summary>
[Option("conversionDateTime", Required = false, HelpText =
"The date time at which the conversion with the specified order ID occurred. " +
"Must be after the click time, and must include the time zone offset. The " +
"format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm', e.g. '2019-01-01 12:32:45-08:00'. " +
"Setting this field is optional, but recommended.")]
public string ConversionDateTime { get; set; }
/// <summary>
/// The HTTP user agent of the conversion.
/// </summary>
[Option("userAgent", Required = true, HelpText =
"The HTTP user agent of the conversion.")]
public string UserAgent { get; set; }
}
/// <summary>
/// Main method, to run this code example as a standalone application.
/// </summary>
/// <param name="args">The command line arguments.</param>
public static void Main(string[] args)
{
Options options = ExampleUtilities.ParseCommandLine<Options>(args);
UploadEnhancedConversionsForWeb codeExample = new UploadEnhancedConversionsForWeb();
Console.WriteLine(codeExample.Description);
codeExample.Run(new GoogleAdsClient(), options.CustomerId, options.ConversionActionId,
options.OrderId, options.ConversionDateTime, options.UserAgent);
}
private static SHA256 digest = SHA256.Create();
/// <summary>
/// Returns a description about the code example.
/// </summary>
public override string Description =>
"This code example adjusts an existing conversion by supplying user identifiers so " +
"Google can enhance the conversion value.";
/// <summary>
/// Runs the code example.
/// </summary>
/// <param name="client">The Google Ads client.</param>
/// <param name="customerId">The Google Ads customer ID.</param>
/// <param name="conversionActionId">ID of the conversion action associated with this
/// conversion.</param>
/// <param name="orderId">The unique order ID (transaction ID) of the conversion.</param>
/// <param name="conversionDateTime">The date time at which the conversion with the
/// specified order ID occurred.</param>
/// <param name="userAgent">The HTTP user agent of the conversion.</param>
public void Run(GoogleAdsClient client, long customerId, long conversionActionId,
string orderId, string conversionDateTime, string userAgent)
{
// Get the ConversionAdjustmentUploadService.
ConversionAdjustmentUploadServiceClient conversionAdjustmentUploadService =
client.GetService(Services.V16.ConversionAdjustmentUploadService);
// Creates the enhancement adjustment.
ConversionAdjustment enhancement = new ConversionAdjustment()
{
AdjustmentType = ConversionAdjustmentType.Enhancement
};
// Normalize and hash the raw data, 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:
// UserIdentifier incorrectlyPopulatedUserIdentifier = new UserIdentifier()
// {
// HashedEmail = "..."
// HashedPhoneNumber = "..."
// }
UserIdentifier addressIdentifier = new UserIdentifier()
{
AddressInfo = new OfflineUserAddressInfo()
{
HashedFirstName = NormalizeAndHash("Dana"),
HashedLastName = NormalizeAndHash("Quinn"),
HashedStreetAddress = NormalizeAndHash("1600 Amphitheatre Pkwy"),
City = "Mountain View",
State = "CA",
PostalCode = "94043",
CountryCode = "US"
},
// Optional: Specifies the user identifier source.
UserIdentifierSource = UserIdentifierSource.FirstParty
};
// Creates a user identifier using the hashed email address.
UserIdentifier emailIdentifier = new UserIdentifier()
{
UserIdentifierSource = UserIdentifierSource.FirstParty,
// Uses the normalize and hash method specifically for email addresses.
HashedEmail = NormalizeAndHashEmailAddress("dana@example.com")
};
// Adds the user identifiers to the enhancement adjustment.
enhancement.UserIdentifiers.AddRange(new[] { addressIdentifier, emailIdentifier });
// Set the conversion action.
enhancement.ConversionAction =
ResourceNames.ConversionAction(customerId, conversionActionId);
// Set the order ID. Enhancements MUST use order ID instead of GCLID date/time pair.
enhancement.OrderId = orderId;
// Sets the conversion date and time if provided. Providing this value is optional but
// recommended.
if (string.IsNullOrEmpty(conversionDateTime))
{
enhancement.GclidDateTimePair = new GclidDateTimePair()
{
ConversionDateTime = conversionDateTime
};
}
// Sets optional fields where a value was provided.
if (!string.IsNullOrEmpty(userAgent))
{
// Sets the user agent. This should match the user agent of the request that
// sent the original conversion so the conversion and its enhancement are either
// both attributed as same-device or both attributed as cross-device.
enhancement.UserAgent = userAgent;
}
try
{
// Uploads the enhancement adjustment. Partial failure should always be set to true.
//
// NOTE: This request contains a single adjustment as a demonstration.
// However, if you have multiple adjustments to upload, it's best to upload
// multiple adjustmenst per request instead of sending a separate request per
// adjustment. See the following for per-request limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_adjust
UploadConversionAdjustmentsResponse response =
conversionAdjustmentUploadService.UploadConversionAdjustments(
new UploadConversionAdjustmentsRequest()
{
CustomerId = customerId.ToString(),
ConversionAdjustments = { enhancement },
// Enables partial failure (must be true).
PartialFailure = true,
});
// Prints the status message if any partial failure error is returned.
// To review the overall health of your recent uploads, see:
// https://developers.google.com/google-ads/api/docs/conversions/upload-summaries
if (response.PartialFailureError != null)
{
// Extracts the partial failure from the response status.
GoogleAdsFailure partialFailure = response.PartialFailure;
Console.WriteLine($"{partialFailure.Errors.Count} partial failure error(s) " +
$"occurred");
}
else
{
// Prints the result.
ConversionAdjustmentResult result = response.Results[0];
Console.WriteLine($"Uploaded conversion adjustment of " +
$"'{result.ConversionAction}' for order ID '{result.OrderId}'.");
}
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
/// <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
<?php
/**
* Copyright 2021 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
namespace Google\Ads\GoogleAds\Examples\Remarketing;
require __DIR__ . '/../../vendor/autoload.php';
use GetOpt\GetOpt;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentNames;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentParser;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V16\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V16\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V16\GoogleAdsException;
use Google\Ads\GoogleAds\Util\V16\ResourceNames;
use Google\Ads\GoogleAds\V16\Common\OfflineUserAddressInfo;
use Google\Ads\GoogleAds\V16\Common\UserIdentifier;
use Google\Ads\GoogleAds\V16\Enums\ConversionAdjustmentTypeEnum\ConversionAdjustmentType;
use Google\Ads\GoogleAds\V16\Enums\UserIdentifierSourceEnum\UserIdentifierSource;
use Google\Ads\GoogleAds\V16\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V16\Services\ConversionAdjustment;
use Google\Ads\GoogleAds\V16\Services\ConversionAdjustmentResult;
use Google\Ads\GoogleAds\V16\Services\GclidDateTimePair;
use Google\Ads\GoogleAds\V16\Services\UploadConversionAdjustmentsRequest;
use Google\ApiCore\ApiException;
/**
* Enhances a web conversion by uploading a ConversionAdjustment containing hashed user
* identifiers and an order ID.
*/
class UploadEnhancedConversionsForWeb
{
private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE';
private const CONVERSION_ACTION_ID = 'INSERT_CONVERSION_ACTION_ID_HERE';
private const ORDER_ID = 'INSERT_ORDER_ID_HERE';
// Optional parameters.
// The date time at which the conversion with the specified order ID occurred.
// Must be after the click time, and must include the time zone offset.
// The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", e.g. '2019-01-01 12:32:45-08:00'.
// Setting this field is optional, but recommended.
private const CONVERSION_DATE_TIME = null;
private const USER_AGENT = null;
public static function main()
{
// Either pass the required parameters for this example on the command line, or insert them
// into the constants above.
$options = (new ArgumentParser())->parseCommandArguments([
ArgumentNames::CUSTOMER_ID => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::CONVERSION_ACTION_ID => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::ORDER_ID => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::CONVERSION_DATE_TIME => GetOpt::OPTIONAL_ARGUMENT,
ArgumentNames::USER_AGENT => GetOpt::OPTIONAL_ARGUMENT
]);
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// Construct a Google Ads client configured from a properties file and the
// OAuth2 credentials above.
$googleAdsClient = (new GoogleAdsClientBuilder())
->fromFile()
->withOAuth2Credential($oAuth2Credential)
// We set this value to true to show how to use GAPIC v2 source code. You can remove the
// below line if you wish to use the old-style source code. Note that in that case, you
// probably need to modify some parts of the code below to make it work.
// For more information, see
// https://developers.devsite.corp.google.com/google-ads/api/docs/client-libs/php/gapic.
->usingGapicV2Source(true)
->build();
try {
self::runExample(
$googleAdsClient,
$options[ArgumentNames::CUSTOMER_ID] ?: self::CUSTOMER_ID,
$options[ArgumentNames::CONVERSION_ACTION_ID] ?: self::CONVERSION_ACTION_ID,
$options[ArgumentNames::ORDER_ID] ?: self::ORDER_ID,
$options[ArgumentNames::CONVERSION_DATE_TIME] ?: self::CONVERSION_DATE_TIME,
$options[ArgumentNames::USER_AGENT] ?: self::USER_AGENT
);
} catch (GoogleAdsException $googleAdsException) {
printf(
"Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
$googleAdsException->getRequestId(),
PHP_EOL,
PHP_EOL
);
foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
/** @var GoogleAdsError $error */
printf(
"\t%s: %s%s",
$error->getErrorCode()->getErrorCode(),
$error->getMessage(),
PHP_EOL
);
}
exit(1);
} catch (ApiException $apiException) {
printf(
"ApiException was thrown with message '%s'.%s",
$apiException->getMessage(),
PHP_EOL
);
exit(1);
}
}
/**
* Runs the example.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param int $conversionActionId the ID of the conversion action associated with this
* conversion
* @param string $orderId the unique order ID (transaction ID) of the conversion
* @param string|null $conversionDateTime the date and time of the conversion.
* The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", e.g. “2019-01-01 12:32:45-08:00”
* @param string|null $userAgent the HTTP user agent of the conversion
*/
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $conversionActionId,
string $orderId,
?string $conversionDateTime,
?string $userAgent
) {
// Creates the conversion enhancement.
$enhancement =
new ConversionAdjustment(['adjustment_type' => ConversionAdjustmentType::ENHANCEMENT]);
// Extracts user email, phone, and address info 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.
//
// $incorrectlyPopulatedUserIdentifier = new UserIdentifier([
// 'hashed_email' => '...',
// 'hashed_phone_number' => '...'
// ]);
$rawRecord = [
// Email address that includes a period (.) before the Gmail domain.
'email' => 'alex.2@example.com',
// Address that includes all four required elements: first name, last name, country
// code, and postal code.
'firstName' => 'Alex',
'lastName' => 'Quinn',
'countryCode' => 'US',
'postalCode' => '94045',
// 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,
'conversionActionId' => $conversionActionId,
'conversionDateTime' => $conversionDateTime,
'currencyCode' => 'USD'
];
// 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;
}
// Checks if the record has all the required mailing address elements, and if so, adds a
// UserIdentifier for the mailing address.
if (array_key_exists('firstName', $rawRecord)) {
// Checks if the record contains all the other required elements of a mailing
// address.
$missingAddressKeys = [];
foreach (['lastName', 'countryCode', 'postalCode'] as $addressKey) {
if (!array_key_exists($addressKey, $rawRecord)) {
$missingAddressKeys[] = $addressKey;
}
}
if (!empty($missingAddressKeys)) {
printf(
"Skipping addition of mailing address information because the "
. "following required keys are missing: %s%s",
json_encode($missingAddressKeys),
PHP_EOL
);
} else {
// Creates an OfflineUserAddressInfo object that contains all the required
// elements of a mailing address.
$addressIdentifier = new UserIdentifier([
'address_info' => new OfflineUserAddressInfo([
'hashed_first_name' => self::normalizeAndHash(
$hashAlgorithm,
$rawRecord['firstName'],
false
),
'hashed_last_name' => self::normalizeAndHash(
$hashAlgorithm,
$rawRecord['lastName'],
false
),
'country_code' => $rawRecord['countryCode'],
'postal_code' => $rawRecord['postalCode']
])
]);
// Adds the address identifier to the user identifiers list.
$userIdentifiers[] = $addressIdentifier;
}
}
// Adds the user identifiers to the conversion.
$enhancement->setUserIdentifiers($userIdentifiers);
// Sets the conversion action.
$enhancement->setConversionAction(
ResourceNames::forConversionAction($customerId, $rawRecord['conversionActionId'])
);
// Sets the order ID. Enhancements MUST use order ID instead of GCLID date/time pair.
if (!empty($rawRecord['orderId'])) {
$enhancement->setOrderId($rawRecord['orderId']);
}
// Sets the conversion date and time if provided. Providing this value is optional but
// recommended.
if (!empty($rawRecord['conversionDateTime'])) {
// Sets the conversion date and time if provided. Providing this value is optional but
// recommended.
$enhancement->setGclidDateTimePair(new GclidDateTimePair([
'conversion_date_time' => $rawRecord['conversionDateTime']
]));
}
// Sets the user agent if provided. This should match the user agent of the request that
// sent the original conversion so the conversion and its enhancement are either both
// attributed as same-device or both attributed as cross-device.
if (!empty($rawRecord['userAgent'])) {
$enhancement->setUserAgent($rawRecord['userAgent']);
}
// Issues a request to upload the conversion enhancement.
$conversionAdjustmentUploadServiceClient =
$googleAdsClient->getConversionAdjustmentUploadServiceClient();
// NOTE: This request contains a single adjustment as a demonstration. However, if you have
// multiple adjustments to upload, it's best to upload multiple adjustments per request
// instead of sending a separate request per adjustment. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_adjustment_upload_service
$response = $conversionAdjustmentUploadServiceClient->uploadConversionAdjustments(
// Enables partial failure (must be true).
UploadConversionAdjustmentsRequest::build($customerId, [$enhancement], true)
);
// Prints the status message if any partial failure error is returned.
// Note: The details of each partial failure error are not printed here, you can refer to
// the example HandlePartialFailure.php to learn more.
// To review the overall health of your recent uploads, see:
// https://developers.google.com/google-ads/api/docs/conversions/upload-summaries
if ($response->hasPartialFailureError()) {
printf(
"Partial failures occurred: '%s'.%s",
$response->getPartialFailureError()->getMessage(),
PHP_EOL
);
} else {
// Prints the result if exists.
/** @var ConversionAdjustmentResult $uploadedConversionAdjustment */
$uploadedConversionAdjustment = $response->getResults()[0];
printf(
"Uploaded conversion adjustment of '%s' for order ID '%s'.%s",
$uploadedConversionAdjustment->getConversionAction(),
$uploadedConversionAdjustment->getOrderId(),
PHP_EOL
);
}
}
/**
* Returns the result of normalizing and then hashing the string using the provided hash
* algorithm. Private customer data must be hashed during upload, as described at
* https://support.google.com/google-ads/answer/7474263.
*
* @param string $hashAlgorithm the hash algorithm to use
* @param string $value the value to normalize and hash
* @param bool $trimIntermediateSpaces if true, removes leading, trailing, and intermediate
* spaces from the string before hashing. If false, only removes leading and trailing
* spaces from the string before hashing.
* @return string the normalized and hashed value
*/
private static function normalizeAndHash(
string $hashAlgorithm,
string $value,
bool $trimIntermediateSpaces
): string {
// Normalizes by first converting all characters to lowercase, then trimming spaces.
$normalized = strtolower($value);
if ($trimIntermediateSpaces === true) {
// Removes leading, trailing, and intermediate spaces.
$normalized = str_replace(' ', '', $normalized);
} else {
// Removes only leading and trailing spaces.
$normalized = trim($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, true);
}
}
UploadEnhancedConversionsForWeb::main();
Python
#!/usr/bin/env python
# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Enhances a web conversion by uploading a ConversionAdjustment.
The conversion adjustment contains hashed user identifiers and an order ID.
"""
import argparse
import hashlib
import re
import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
def main(
client,
customer_id,
conversion_action_id,
order_id,
conversion_date_time,
user_agent,
):
"""The main method that creates all necessary entities for the example.
Args:
client: An initialized GoogleAdsClient instance.
customer_id: The client customer ID string.
conversion_action_id: The ID of the conversion action to upload to.
order_id: The unique ID (transaction ID) of the conversion.
conversion_date_time: The date and time of the conversion.
user_agent: The HTTP user agent of the conversion.
"""
# Extracts user email, phone, and address info 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 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",
# Address that includes all four required elements: first name, last
# name, country code, and postal code.
"first_name": "Alex",
"last_name": "Quinn",
"country_code": "US",
"postal_code": "94045",
# 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,
"conversion_action_id": conversion_action_id,
"conversion_date_time": conversion_date_time,
"currency_code": "USD",
"user_agent": user_agent,
}
# Constructs the enhancement adjustment.
conversion_adjustment = client.get_type("ConversionAdjustment")
conversion_adjustment.adjustment_type = (
client.enums.ConversionAdjustmentTypeEnum.ENHANCEMENT
)
# 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_email = normalize_and_hash_email_address(
raw_record["email"]
)
# Adds the email identifier to the conversion adjustment.
conversion_adjustment.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.
conversion_adjustment.user_identifiers.append(phone_identifier)
# Checks if the record has all the required mailing address elements, and if
# so, adds a UserIdentifier for the mailing address.
if raw_record.get("first_name") is not None:
# Checks if the record contains all the other required elements of a
# mailing address.
required_keys = ["last_name", "country_code", "postal_code"]
# Builds a new list of the required keys that are missing from
# raw_record.
missing_keys = [
key for key in required_keys if key not in raw_record.keys()
]
if len(missing_keys) > 0:
print(
"Skipping addition of mailing address information because the"
f"following required keys are missing: {missing_keys}"
)
else:
# Creates a user identifier using sample values for the user address,
# hashing where required.
address_identifier = client.get_type("UserIdentifier")
address_info = address_identifier.address_info
address_info.hashed_first_name = normalize_and_hash(
raw_record["first_name"]
)
address_info.hashed_last_name = normalize_and_hash(
raw_record["last_name"]
)
address_info.country_code = raw_record["country_code"]
address_info.postal_code = raw_record["postal_code"]
# Adds the address identifier to the conversion adjustment.
conversion_adjustment.user_identifiers.append(address_identifier)
conversion_action_service = client.get_service("ConversionActionService")
# Sets the conversion action.
conversion_adjustment.conversion_action = (
conversion_action_service.conversion_action_path(
customer_id, raw_record["conversion_action_id"]
)
)
# Sets the order ID. Enhancements MUST use order ID instead of GCLID
# date/time pair.
conversion_adjustment.order_id = order_id
# Sets the conversion date and time if provided. Providing this value is
# optional but recommended.
if raw_record.get("conversion_date_time"):
conversion_adjustment.gclid_date_time_pair.conversion_date_time = (
raw_record["conversion_date_time"]
)
# Sets optional fields where a value was provided
if raw_record.get("user_agent"):
# Sets the user agent. This should match the user agent of the request
# that sent the original conversion so the conversion and its
# enhancement are either both attributed as same-device or both
# attributed as cross-device.
conversion_adjustment.user_agent = user_agent
# Creates the conversion adjustment upload service client.
conversion_adjustment_upload_service = client.get_service(
"ConversionAdjustmentUploadService"
)
# Uploads the enhancement adjustment. 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 still best 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_adjustment_upload_service.upload_conversion_adjustments(
customer_id=customer_id,
conversion_adjustments=[conversion_adjustment],
# Enables partial failure (must be true).
partial_failure=True,
)
# Prints any partial errors returned.
# To review the overall health of your recent uploads, see:
# https://developers.google.com/google-ads/api/docs/conversions/upload-summaries
if response.partial_failure_error:
print(
"Partial error encountered: "
f"{response.partial_failure_error.message}"
)
else:
# Prints the result.
result = response.results[0]
print(
f"Uploaded conversion adjustment of {result.conversion_action} for "
f"order ID {result,order_id}."
)
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/9888656
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()
if __name__ == "__main__":
parser = argparse.ArgumentParser(
description="Imports offline call conversion values for calls related "
"to your ads."
)
# The following argument(s) should be provided to run the example.
parser.add_argument(
"-c",
"--customer_id",
type=str,
required=True,
help="The Google Ads customer ID.",
)
parser.add_argument(
"-a",
"--conversion_action_id",
type=str,
required=True,
help="The ID of the conversion action to upload to.",
)
parser.add_argument(
"-o",
"--order_id",
type=str,
required=True,
help="the unique ID (transaction ID) of the conversion.",
)
parser.add_argument(
"-d",
"--conversion_date_time",
type=str,
help="The date time at which the conversion with the specified order "
"ID occurred. Must be after the click time, and must include the time "
"zone offset. The format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm', "
"e.g. '2019-01-01 12:32:45-08:00'. Setting this field is optional, "
"but recommended",
)
parser.add_argument(
"-u",
"--user_agent",
type=str,
help="The HTTP user agent of the conversion.",
)
args = parser.parse_args()
# GoogleAdsClient will read the google-ads.yaml configuration file in the
# home directory if none is specified.
googleads_client = GoogleAdsClient.load_from_storage(version="v16")
try:
main(
googleads_client,
args.customer_id,
args.conversion_action_id,
args.order_id,
args.conversion_date_time,
args.user_agent,
)
except GoogleAdsException as ex:
print(
f"Request with ID '{ex.request_id}'' failed with status "
f"'{ex.error.code().name}' and includes the following errors:"
)
for error in ex.failure.errors:
print(f"\tError with message '{error.message}'.")
if error.location:
for field_path_element in error.location.field_path_elements:
print(f"\t\tOn field: {field_path_element.field_name}")
sys.exit(1)
Ruby
#!/usr/bin/env ruby
#
# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Enhances a web conversion by uploading a ConversionAdjustment.
# The conversion adjustment contains hashed user identifiers and an order ID.
require 'optparse'
require 'google/ads/google_ads'
require 'digest'
def upload_conversion_enhancement(
customer_id,
conversion_action_id,
order_id,
conversion_date_time,
user_agent
)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Extracts user email, phone, and address info 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 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",
# Address that includes all four required elements: first name, last
# name, country code, and postal code.
"first_name" => "Alex",
"last_name" => "Quinn",
"country_code" => "US",
"postal_code" => "94045",
# 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,
"conversion_action_id" => conversion_action_id,
"conversion_date_time" => conversion_date_time,
"currency_code" => "USD",
"user_agent" => user_agent,
}
enhancement = client.resource.conversion_adjustment do |ca|
ca.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
ca.adjustment_type = :ENHANCEMENT
ca.order_id = order_id
# Sets the conversion date and time if provided. Providing this value is
# optional but recommended.
unless conversion_date_time.nil?
ca.gclid_date_time_pair = client.resource.gclid_date_time_pair do |pair|
pair.conversion_date_time = conversion_date_time
end
end
# Creates a user identifier using the hashed email address, using the
# normalize and hash method specifically for email addresses.
ca.user_identifiers << client.resource.user_identifier do |ui|
# Uses the normalize and hash method specifically for email addresses.
ui.hashed_email = 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?
ca.user_identifiers << client.resource.user_identifier do |ui|
ui.hashed_phone_number = normalize_and_hash_email(raw_record["phone"])
end
end
# Checks if the record has all the required mailing address elements, and if
# so, adds a UserIdentifier for the mailing address.
unless raw_record["first_name"].nil?
# Checks if the record contains all the other required elements of a
# mailing address.
required_keys = ["last_name", "country_code", "postal_code"]
# Builds a new list of the required keys that are missing from
# raw_record.
missing_keys = required_keys - raw_record.keys
if missing_keys
puts(
"Skipping addition of mailing address information because the" \
"following required keys are missing: #{missing_keys}"
)
else
ca.user_identifiers << client.resource.user_identifier do |ui|
ui.address_info = client.resource.offline_user_address_info do |info|
# Certain fields must be hashed using SHA256 in order to handle
# identifiers in a privacy-safe way, as described at
# https://support.google.com/google-ads/answer/9888656.
info.hashed_first_name = normalize_and_hash( raw_record["first_name"])
info.hashed_last_name = normalize_and_hash( raw_record["last_name"])
info.postal_code = normalize_and_hash(raw_record["country_code"])
info.country_code = normalize_and_hash(raw_record["postal_code"])
end
end
end
end
# Sets optional fields where a value was provided.
unless user_agent.nil?
# Sets the user agent. This should match the user agent of the request
# that sent the original conversion so the conversion and its enhancement
# are either both attributed as same-device or both attributed as
# cross-device.
ca.user_agent = user_agent
end
end
response = client.service.conversion_adjustment_upload.upload_conversion_adjustments(
customer_id: customer_id,
# NOTE: This request only uploads a single conversion, but if you have
# multiple conversions to upload, it's still best 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
conversion_adjustments: [enhancement],
# Partial failure must be set to true.
partial_failure: true,
)
# Prints any partial errors returned.
# To review the overall health of your recent uploads, see:
# https://developers.google.com/google-ads/api/docs/conversions/upload-summaries
if response.partial_failure_error
puts "Partial failure encountered: #{response.partial_failure_error.message}."
else
result = response.results.first
puts "Uploaded conversion adjustment of #{result.conversion_action} for "\
"order ID #{result.order_id}."
end
end
# 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/9888656.
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
if __FILE__ == $0
options = {}
# The following parameter(s) should be provided to run the example. You can
# either specify these by changing the INSERT_XXX_ID_HERE values below, or on
# the command line.
#
# Parameters passed on the command line will override any parameters set in
# code.
#
# Running the example with -h will print the command line usage.
options[:customer_id] = 'INSERT_CUSTOMER_ID_HERE'
options[:conversion_action_id] = 'INSERT_CONVERSION_ACTION_ID_HERE'
options[:order_id] = 'INSERT_ORDER_ID_HERE'
OptionParser.new do |opts|
opts.banner = format('Usage: %s [options]', File.basename(__FILE__))
opts.separator ''
opts.separator 'Options:'
opts.on('-C', '--customer-id CUSTOMER-ID', String, 'Customer ID') do |v|
options[:customer_id] = v
end
opts.on('-c', '--conversion-action-id CONVERSION-ACTION-ID', String,
'Conversion Action ID') do |v|
options[:conversion_action_id] = v
end
opts.on('-o', '--order-id ORDER-ID', String, 'Order ID') do |v|
options[:order_id] = v
end
opts.on('-d', '--conversion-date-time CONVERSION-DATE-TIME', String,
'The date and time of the conversion (should be after click time).'\
' The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", '\
'e.g. "2019-01-01 12:32:45-08:00".') do |v|
options[:conversion_date_time] = v
end
opts.on('-u', '--user-agent USER-AGENT', String, 'User Agent') do |v|
options[:user_agent] = v
end
opts.separator ''
opts.separator 'Help:'
opts.on_tail('-h', '--help', 'Show this message') do
puts opts
exit
end
end.parse!
begin
upload_conversion_enhancement(
options.fetch(:customer_id).tr('-', ''),
options.fetch(:conversion_action_id),
options.fetch(:order_id),
options[:conversion_date_time],
options[:user_agent]
)
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
e.failure.errors.each do |error|
STDERR.printf("Error with message: %s\n", error.message)
error.location&.field_path_elements&.each do |field_path_element|
STDERR.printf("\tOn field: %s\n", field_path_element.field_name)
end
error.error_code.to_h.each do |k, v|
next if v == :UNSPECIFIED
STDERR.printf("\tType: %s\n\tCode: %s\n", k, v)
end
end
raise
end
end
Perl
#!/usr/bin/perl -w
#
# Copyright 2021, Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Enhances a web conversion by uploading a ConversionAdjustment containing
# a hashed user identifier and an order ID.
use strict;
use warnings;
use utf8;
use FindBin qw($Bin);
use lib "$Bin/../../lib";
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::Utils::GoogleAdsHelper;
use Google::Ads::GoogleAds::V16::Common::UserIdentifier;
use Google::Ads::GoogleAds::V16::Common::OfflineUserAddressInfo;
use Google::Ads::GoogleAds::V16::Enums::ConversionAdjustmentTypeEnum
qw(ENHANCEMENT);
use Google::Ads::GoogleAds::V16::Enums::UserIdentifierSourceEnum
qw(FIRST_PARTY);
use
Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::ConversionAdjustment;
use
Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::GclidDateTimePair;
use Google::Ads::GoogleAds::V16::Utils::ResourceNames;
use Getopt::Long qw(:config auto_help);
use Pod::Usage;
use Cwd qw(abs_path);
use Digest::SHA qw(sha256_hex);
# The following parameter(s) should be provided to run the example. You can
# either specify these by changing the INSERT_XXX_ID_HERE values below, or on
# the command line.
#
# Parameters passed on the command line will override any parameters set in
# code.
#
# Running the example with -h will print the command line usage.
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $conversion_action_id = "INSERT_CONVERSION_ACTION_ID_HERE";
my $order_id = "INSERT_ORDER_ID_HERE";
# Optional: Specify the conversion date/time and user agent.
my $conversion_date_time = undef;
my $user_agent = undef;
sub upload_enhanced_conversions_for_web {
my (
$api_client, $customer_id, $conversion_action_id,
$order_id, $conversion_date_time, $user_agent
) = @_;
# Construct the enhancement adjustment.
my $enhancement =
Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::ConversionAdjustment
->new({
adjustmentType => ENHANCEMENT
});
# Extract user email, phone, and address info 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::V16::Common::UserIdentifier->new({
# hashedEmail => '...',
# hashedPhoneNumber => '...',
# });
my $raw_record = {
# Email address that includes a period (.) before the Gmail domain.
email => 'alex.2@example.com',
# Address that includes all four required elements: first name, last
# name, country code, and postal code.
firstName => 'Alex',
lastName => 'Quinn',
countryCode => 'US',
postalCode => '94045',
# 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,
conversionActionId => $conversion_action_id,
conversionDateTime => $conversion_date_time,
currencyCode => "USD",
userAgent => $user_agent,
};
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::V16::Common::UserIdentifier->new({
hashedEmail => $hashed_email,
# Optional: Specify the user identifier source.
userIdentifierSource => FIRST_PARTY
}));
# Check if the record has a phone number, and if so, add a UserIdentifier for it.
if (defined $raw_record->{phone}) {
# Add the hashed phone number identifier to the list of UserIdentifiers.
push(
@$user_identifiers,
Google::Ads::GoogleAds::V16::Common::UserIdentifier->new({
hashedPhoneNumber => normalize_and_hash($raw_record->{phone}, 1)}));
}
# Confirm the record has all the required mailing address elements, and if so, add
# a UserIdentifier for the mailing address.
if (defined $raw_record->{firstName}) {
my $required_keys = ["lastName", "countryCode", "postalCode"];
my $missing_keys = [];
foreach my $key (@$required_keys) {
if (!defined $raw_record->{$key}) {
push(@$missing_keys, $key);
}
}
if (@$missing_keys) {
print
"Skipping addition of mailing address information because the following"
. "keys are missing: "
. join(",", @$missing_keys);
} else {
push(
@$user_identifiers,
Google::Ads::GoogleAds::V16::Common::UserIdentifier->new({
addressInfo =>
Google::Ads::GoogleAds::V16::Common::OfflineUserAddressInfo->new({
# First and last name must be normalized and hashed.
hashedFirstName => normalize_and_hash($raw_record->{firstName}),
hashedLastName => normalize_and_hash($raw_record->{lastName}),
# Country code and zip code are sent in plain text.
countryCode => $raw_record->{countryCode},
postalCode => $raw_record->{postalCode},
})}));
}
}
# Add the user identifiers to the enhancement adjustment.
$enhancement->{userIdentifiers} = $user_identifiers;
# Set the conversion action.
$enhancement->{conversionAction} =
Google::Ads::GoogleAds::V16::Utils::ResourceNames::conversion_action(
$customer_id, $raw_record->{conversionActionId});
# Set the order ID. Enhancements MUST use order ID instead of GCLID date/time pair.
$enhancement->{orderId} = $raw_record->{orderId};
# Set the conversion date and time if provided. Providing this value is optional
# but recommended.
if (defined $raw_record->{conversionDateTime}) {
$enhancement->{gclidDateTimePair} =
Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::GclidDateTimePair
->new({
conversionDateTime => $raw_record->{conversionDateTime}});
}
# Set the user agent if provided. This should match the user agent of the
# request that sent the original conversion so the conversion and its enhancement
# are either both attributed as same-device or both attributed as cross-device.
if (defined $raw_record->{userAgent}) {
$enhancement->{userAgent} = $raw_record->{userAgent};
}
# Upload the enhancement adjustment. Partial failure should always be set to true.
#
# NOTE: This request contains a single adjustment as a demonstration.
# However, if you have multiple adjustments to upload, it's best to
# upload multiple adjustments per request instead of sending a separate
# request per adjustment. See the following for per-request limits:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_adjustment_upload_service
my $response =
$api_client->ConversionAdjustmentUploadService()
->upload_conversion_adjustments({
customerId => $customer_id,
conversionAdjustments => [$enhancement],
# Enable partial failure (must be true).
partialFailure => "true"
});
# Print any partial errors returned.
# To review the overall health of your recent uploads, see:
# https://developers.google.com/google-ads/api/docs/conversions/upload-summaries
if ($response->{partialFailureError}) {
printf "Partial error encountered: '%s'.\n",
$response->{partialFailureError}{message};
} else {
# Print the result.
my $result = $response->{results}[0];
printf "Uploaded conversion adjustment of '%s' for order ID '%s'.\n",
$result->{conversionAction}, $result->{orderId};
}
return 1;
}
# Normalizes and hashes a string value.
# Private customer data must be hashed during upload, as described at
# https://support.google.com/google-ads/answer/7474263.
sub normalize_and_hash {
my $value = shift;
my $trim_intermediate_spaces = shift;
if ($trim_intermediate_spaces) {
$value =~ s/\s+//g;
} else {
$value =~ s/^\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, 1);
}
# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
return 1;
}
# Get Google Ads Client, credentials will be read from ~/googleads.properties.
my $api_client = Google::Ads::GoogleAds::Client->new();
# By default examples are set to die on any server returned fault.
$api_client->set_die_on_faults(1);
# Parameters passed on the command line will override any parameters set in code.
GetOptions(
"customer_id=s" => \$customer_id,
"conversion_action_id=i" => \$conversion_action_id,
"order_id=s" => \$order_id,
"conversion_date_time=s" => \$conversion_date_time,
"user_agent=s" => \$user_agent
);
# Print the help message if the parameters are not initialized in the code nor
# in the command line.
pod2usage(2)
if not check_params($customer_id, $conversion_action_id, $order_id);
# Call the example.
upload_enhanced_conversions_for_web($api_client, $customer_id =~ s/-//gr,
$conversion_action_id, $order_id, $conversion_date_time, $user_agent);
=pod
=head1 NAME
upload_enhanced_conversions_for_web
=head1 DESCRIPTION
Adjusts an existing conversion by supplying user identifiers so Google can
enhance the conversion value.
=head1 SYNOPSIS
upload_enhanced_conversions_for_web.pl [options]
-help Show the help message.
-customer_id The Google Ads customer ID.
-conversion_action_id The conversion action ID associated with this conversion.
-order_id The unique order ID (transaction ID) of the conversion.
-conversion_date_time [optional] The date time at which the conversion with the specified order ID
occurred. Must be after the click time, and must include the time zone offset.
The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", e.g. "2019-01-01 12:32:45-08:00".
Setting this field is optional, but recommended.
-user_agent [optional] The HTTP user agent of the conversion.
=cut
