Java
// Copyright 2020 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.v10.errors.GoogleAdsError;
import com.google.ads.googleads.v10.errors.GoogleAdsException;
import com.google.ads.googleads.v10.errors.GoogleAdsFailure;
import com.google.ads.googleads.v10.services.ClickConversion;
import com.google.ads.googleads.v10.services.ClickConversionResult;
import com.google.ads.googleads.v10.services.ConversionUploadServiceClient;
import com.google.ads.googleads.v10.services.CustomVariable;
import com.google.ads.googleads.v10.services.UploadClickConversionsRequest;
import com.google.ads.googleads.v10.services.UploadClickConversionsResponse;
import com.google.ads.googleads.v10.utils.ErrorUtils;
import com.google.ads.googleads.v10.utils.ResourceNames;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.Arrays;
/** Imports offline conversion values for specific clicks to an account. */
public class UploadOfflineConversion {
private static class UploadOfflineConversionParams 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.GCLID,
required = false,
description =
"The Google Click identifier. If setting this value, do not set "
+ ArgumentNames.GBRAID
+ " or "
+ ArgumentNames.WBRAID
+ ".")
private String gclid;
@Parameter(
names = ArgumentNames.GBRAID,
required = false,
description =
"The GBRAID identifier for an iOS app conversion. If setting this value, do not set "
+ ArgumentNames.GCLID
+ " or "
+ ArgumentNames.WBRAID
+ ".")
private String gbraid;
@Parameter(
names = ArgumentNames.WBRAID,
required = false,
description =
"The WBRAID identifer for an iOS web conversion. If setting this value, do not set "
+ ArgumentNames.GCLID
+ " or "
+ ArgumentNames.GBRAID
+ ".")
private String wbraid;
@Parameter(
names = ArgumentNames.CONVERSION_DATE_TIME,
required = true,
description =
"The date time at which the conversion 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'.")
private String conversionDateTime;
@Parameter(names = ArgumentNames.CONVERSION_VALUE, required = true)
private Double conversionValue;
// Optional: Specify the conversion custom variable ID and value you want to
// associate with the click conversion upload.
@Parameter(names = ArgumentNames.CONVERSION_CUSTOM_VARIABLE_ID)
private Long conversionCustomVariableId;
@Parameter(names = ArgumentNames.CONVERSION_CUSTOM_VARIABLE_VALUE)
private String conversionCustomVariableValue;
// Optional: Specify the unique order ID for the click conversion.
@Parameter(names = ArgumentNames.ORDER_ID)
private String orderId;
}
public static void main(String[] args) {
UploadOfflineConversionParams params = new UploadOfflineConversionParams();
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");
// Set exactly one of gclid, gbraid, or wbraid.
params.gclid = "INSERT_GCLID_HERE";
params.gbraid = null;
params.wbraid = null;
params.conversionDateTime = "INSERT_CONVERSION_DATE_TIME_HERE";
params.conversionValue = Double.parseDouble("INSERT_CONVERSION_VALUE_HERE");
// Optionally specify the conversion custom variable ID and value you want to
// associate with the click conversion upload.
params.conversionCustomVariableId = null;
params.conversionCustomVariableValue = null;
// Optionally specify the order ID for the click conversion.
params.orderId = 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 UploadOfflineConversion()
.runExample(
googleAdsClient,
params.customerId,
params.conversionActionId,
params.gclid,
params.gbraid,
params.wbraid,
params.conversionDateTime,
params.conversionValue,
params.conversionCustomVariableId,
params.conversionCustomVariableValue,
params.orderId);
} 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 gclid the GCLID for the conversion. If set, {@code gbraid} and {@code wbraid} must be
* null.
* @param gbraid the GBRAID for the iOS app conversion. If set, {@code gclid} and {@code wbraid}
* must be null.
* @param wbraid the WBRAID for the iOS web conversion. If set, {@code gclid} and {@code gbraid}
* must be null.
* @param conversionDateTime date and time of the conversion.
* @param conversionValue the value of the conversion.
* @param conversionCustomVariableId the ID of the conversion custom variable to associate with
* the upload.
* @param conversionCustomVariableValue the value of the conversion custom variable to associate
* with the upload.
* @param orderId the unique ID (transaction ID) of the conversion.
*/
private void runExample(
GoogleAdsClient googleAdsClient,
long customerId,
long conversionActionId,
String gclid,
String gbraid,
String wbraid,
String conversionDateTime,
Double conversionValue,
Long conversionCustomVariableId,
String conversionCustomVariableValue,
String orderId) {
// Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
// See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
long numberOfIdsSpecified =
Arrays.asList(gclid, gbraid, wbraid).stream().filter(idField -> idField != null).count();
if (numberOfIdsSpecified != 1) {
throw new IllegalArgumentException(
"Exactly 1 of gclid, gbraid, or wbraid is required, but "
+ numberOfIdsSpecified
+ " ID values were provided");
}
// Constructs the conversion action resource name from the customer and conversion action IDs.
String conversionActionResourceName =
ResourceNames.conversionAction(customerId, conversionActionId);
// Creates the click conversion.
ClickConversion.Builder clickConversionBuilder =
ClickConversion.newBuilder()
.setConversionAction(conversionActionResourceName)
.setConversionDateTime(conversionDateTime)
.setConversionValue(conversionValue)
.setCurrencyCode("USD");
// Sets the single specified ID field.
if (gclid != null) {
clickConversionBuilder.setGclid(gclid);
} else if (gbraid != null) {
clickConversionBuilder.setGbraid(gbraid);
} else {
clickConversionBuilder.setWbraid(wbraid);
}
if (conversionCustomVariableId != null && conversionCustomVariableValue != null) {
// Sets the custom variable and value, if provided.
clickConversionBuilder.addCustomVariables(
CustomVariable.newBuilder()
.setConversionCustomVariable(
ResourceNames.conversionCustomVariable(customerId, conversionCustomVariableId))
.setValue(conversionCustomVariableValue));
}
if (orderId != null) {
// Sets the order ID (unique transaction ID), if provided. An order ID is required in order to
// upload enhancements as shown in the UploadConversionEnhancement example.
clickConversionBuilder.setOrderId(orderId);
}
ClickConversion clickConversion = clickConversionBuilder.build();
// Creates the conversion upload service client.
try (ConversionUploadServiceClient conversionUploadServiceClient =
googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) {
// Uploads the click conversion. Partial failure should always be set to true.
UploadClickConversionsResponse response =
conversionUploadServiceClient.uploadClickConversions(
UploadClickConversionsRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.addConversions(clickConversion)
// Enables partial failure (must be true).
.setPartialFailure(true)
.build());
// Prints any partial errors returned.
if (response.hasPartialFailureError()) {
GoogleAdsFailure googleAdsFailure =
ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
googleAdsFailure
.getErrorsList()
.forEach(e -> System.out.println("Partial failure occurred: " + e.getMessage()));
}
// Prints the result.
ClickConversionResult result = response.getResults(0);
// Only prints valid results.
if (result.hasGclid()) {
System.out.printf(
"Uploaded conversion that occurred at '%s' from Google Click ID '%s' to '%s'.%n",
result.getConversionDateTime(), result.getGclid(), result.getConversionAction());
}
}
}
}
C#
// Copyright 2020 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.V10.Errors;
using Google.Ads.GoogleAds.V10.Services;
using System;
using System.Collections.Generic;
using System.Linq;
namespace Google.Ads.GoogleAds.Examples.V10
{
/// <summary>
/// This code example imports offline conversion values for specific clicks to your account.
/// To get Google Click ID for a click, use the "click_view" resource:
/// https://developers.google.com/google-ads/api/fields/latest/click_view.
/// To set up a conversion action, run the AddConversionAction.cs example.
/// </summary>
public class UploadOfflineConversion : ExampleBase
{
/// <summary>
/// Command line options for running the <see cref="UploadOfflineConversion"/> example.
/// </summary>
public class Options : OptionsBase
{
/// <summary>
/// The Google Ads customer ID for the conversion action is added.
/// </summary>
[Option("customerId", Required = true, HelpText =
"The Google Ads customer ID for the conversion action is added.")]
public long CustomerId { get; set; }
/// <summary>
/// The conversion action ID.
/// </summary>
[Option("conversionActionId", Required = true, HelpText =
"The conversion action ID.")]
public long ConversionActionId { get; set; }
/// <summary>
/// The conversion time in "yyyy-mm-dd hh:mm:ss+|-hh:mm" format.
/// </summary>
[Option("conversionTime", Required = true, HelpText =
"The conversion time.")]
public string ConversionTime { get; set; }
/// <summary>
/// The click ID.
/// </summary>
[Option("gclid", Required = false, HelpText =
"The Google Click identifier. If setting this value, do not set gbraid or " +
"wbraid parameters.")]
public string Gclid { get; set; }
/// <summary>
/// The click ID.
/// </summary>
[Option("wbraid", Required = false, HelpText =
"The WBRAID identifer for an iOS web conversion. If setting this value, do not " +
"set gclid or gbraid parameters.")]
public string Wbraid { get; set; }
/// <summary>
/// The click ID.
/// </summary>
[Option("gbraid", Required = false, HelpText =
"The GBRAID identifier for an iOS app conversion. If setting this value, do " +
"not set gclid or wbraid parameters.")]
public string Gbraid { get; set; }
/// <summary>
/// The convsersion value.
/// </summary>
[Option("conversionValue", Required = true, HelpText =
"The convsersion value.")]
public double ConversionValue { 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 = new Options();
CommandLine.Parser.Default.ParseArguments<Options>(args).MapResult(
delegate (Options o)
{
options = o;
return 0;
}, delegate (IEnumerable<Error> errors)
{
// The Google Ads customer ID for the conversion action is added.
options.CustomerId = long.Parse("INSERT_CUSTOMER_ID_HERE");
// The conversion action ID.
options.ConversionActionId = long.Parse("INSERT_CONVERSION_ACTION_ID_HERE");
// The conversion time in "yyyy-mm-dd hh:mm:ss+|-hh:mm" format.
options.ConversionTime = "INSERT_CONVERSION_TIME_HERE";
// Set exactly one of gclid, gbraid, or wbraid.
options.Gclid = "INSERT_GCLID_HERE";
options.Wbraid = null;
options.Gbraid = null;
// The convsersion value.
options.ConversionValue = double.Parse("INSERT_CONVERSION_VALUE_HERE");
return 0;
});
UploadOfflineConversion codeExample = new UploadOfflineConversion();
Console.WriteLine(codeExample.Description);
codeExample.Run(new GoogleAdsClient(), options.CustomerId, options.ConversionActionId,
options.ConversionTime, options.Gclid, options.Gbraid, options.Wbraid,
options.ConversionValue);
}
/// <summary>
/// Returns a description about the code example.
/// </summary>
public override string Description =>
"This code example imports offline conversion values for specific clicks to your " +
"account. To get Google Click ID for a click, use the 'click_view' resource: " +
"https://developers.google.com/google-ads/api/fields/latest/click_view. To set up a " +
"conversion action, run the AddConversionAction.cs example.";
/// <summary>
/// Runs the code example.
/// </summary>
/// <param name="client">The Google Ads client.</param>
/// <param name="customerId">The Google Ads customer ID for the conversion action is
/// added.</param>
/// <param name="conversionActionId">The conversion action ID.</param>
/// <param name="conversionTime">The conversion time in "yyyy-mm-dd hh:mm:ss+|-hh:mm"
/// format.</param>
/// <param name="gclid">The GCLID for the conversion. If set, <code>gbraid</code> and
/// <code>wbraid</code> must be null.</param>
/// <param name="gbraid">The GBRAID for the iOS app conversion. If set, <code>gclid</code>
/// and <code>wbraid</code> must be null.</param>
/// <param name="wbraid">The WBRAID for the iOS web conversion. If set, <code>gclid</code>
/// and <code>gbraid</code> must be null.</param>
/// <param name="conversionValue">The convsersion value.</param>
public void Run(GoogleAdsClient client, long customerId, long conversionActionId,
string gclid, string gbraid, string wbraid, string conversionTime,
double conversionValue)
{
// Get the ConversionActionService.
ConversionUploadServiceClient conversionUploadService =
client.GetService(Services.V10.ConversionUploadService);
// Creates a click conversion by specifying currency as USD.
ClickConversion clickConversion = new ClickConversion()
{
ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
ConversionValue = conversionValue,
ConversionDateTime = conversionTime,
CurrencyCode = "USD"
};
// Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
// See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks
// for details.
string[] ids = { gclid, gbraid, wbraid };
int idCount = ids.Where(id => !string.IsNullOrEmpty(id)).Count();
if (idCount != 1)
{
throw new ArgumentException($"Exactly 1 of gclid, gbraid, or wbraid is " +
$"required, but {idCount} ID values were provided");
}
// Sets the single specified ID field.
if (!string.IsNullOrEmpty(gclid))
{
clickConversion.Gclid = gclid;
}
else if (!string.IsNullOrEmpty(wbraid))
{
clickConversion.Wbraid = wbraid;
}
else if (!string.IsNullOrEmpty(gbraid))
{
clickConversion.Gbraid = gbraid;
}
try
{
// Issues a request to upload the click conversion.
UploadClickConversionsResponse response =
conversionUploadService.UploadClickConversions(
new UploadClickConversionsRequest()
{
CustomerId = customerId.ToString(),
Conversions = { clickConversion },
PartialFailure = true,
ValidateOnly = false
});
// Prints the result.
ClickConversionResult uploadedClickConversion = response.Results[0];
Console.WriteLine($"Uploaded conversion that occurred at " +
$"'{uploadedClickConversion.ConversionDateTime}' from Google " +
$"Click ID '{uploadedClickConversion.Gclid}' to " +
$"'{uploadedClickConversion.ConversionAction}'.");
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
}
}
PHP
<?php
/**
* Copyright 2019 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\V10\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V10\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V10\GoogleAdsException;
use Google\Ads\GoogleAds\Util\V10\ResourceNames;
use Google\Ads\GoogleAds\V10\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V10\Services\ClickConversion;
use Google\Ads\GoogleAds\V10\Services\ClickConversionResult;
use Google\Ads\GoogleAds\V10\Services\CustomVariable;
use Google\Ads\GoogleAds\V10\Services\UploadClickConversionsResponse;
use Google\ApiCore\ApiException;
/**
* This code example imports offline conversion values for specific clicks to your account.
* To get Google Click ID for a click, use the "click_view" resource:
* https://developers.google.com/google-ads/api/fields/latest/click_view.
* To set up a conversion action, run the AddConversionAction.php example.
*/
class UploadOfflineConversion
{
private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE';
private const CONVERSION_ACTION_ID = 'INSERT_CONVERSION_ACTION_ID_HERE';
// Set exactly one of GCLID, GBRAID, or WBRAID.
// The Google Click ID for which conversions are uploaded.
private const GCLID = null;
// The GBRAID identifier for an iOS app conversion.
private const GBRAID = null;
// The WBRAID identifier for an iOS web conversion.
private const WBRAID = null;
// The conversion date time in "yyyy-mm-dd hh:mm:ss+|-hh:mm" format.
private const CONVERSION_DATE_TIME = 'INSERT_CONVERSION_DATE_TIME_HERE';
private const CONVERSION_VALUE = 'INSERT_CONVERSION_VALUE_HERE';
// Optional: Specify the conversion custom variable ID and value you want to
// associate with the click conversion upload.
private const CONVERSION_CUSTOM_VARIABLE_ID = null;
private const CONVERSION_CUSTOM_VARIABLE_VALUE = 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::GCLID => GetOpt::OPTIONAL_ARGUMENT,
ArgumentNames::GBRAID => GetOpt::OPTIONAL_ARGUMENT,
ArgumentNames::WBRAID => GetOpt::OPTIONAL_ARGUMENT,
ArgumentNames::CONVERSION_DATE_TIME => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::CONVERSION_VALUE => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::CONVERSION_CUSTOM_VARIABLE_ID => GetOpt::OPTIONAL_ARGUMENT,
ArgumentNames::CONVERSION_CUSTOM_VARIABLE_VALUE => 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)
->build();
try {
self::runExample(
$googleAdsClient,
$options[ArgumentNames::CUSTOMER_ID] ?: self::CUSTOMER_ID,
$options[ArgumentNames::CONVERSION_ACTION_ID] ?: self::CONVERSION_ACTION_ID,
$options[ArgumentNames::GCLID] ?: self::GCLID,
$options[ArgumentNames::GBRAID] ?: self::GBRAID,
$options[ArgumentNames::WBRAID] ?: self::WBRAID,
$options[ArgumentNames::CONVERSION_DATE_TIME] ?: self::CONVERSION_DATE_TIME,
$options[ArgumentNames::CONVERSION_VALUE] ?: self::CONVERSION_VALUE,
$options[ArgumentNames::CONVERSION_CUSTOM_VARIABLE_ID]
?: self::CONVERSION_CUSTOM_VARIABLE_ID,
$options[ArgumentNames::CONVERSION_CUSTOM_VARIABLE_VALUE]
?: self::CONVERSION_CUSTOM_VARIABLE_VALUE
);
} 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 to upload to
* @param string|null $gclid the GCLID for the conversion (should be newer than the number of
* days set on the conversion window of the conversion action). If set, GBRAID and WBRAID
* must be null
* @param string|null $gbraid The GBRAID identifier for an iOS app conversion. If set, GCLID and
* WBRAID must be null
* @param string|null $wbraid The WBRAID identifier for an iOS web conversion. If set, GCLID and
* GBRAID must be null
* @param string $conversionDateTime the date and time of the conversion (should be after the
* click time). The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", e.g.
* “2019-01-01 12:32:45-08:00”
* @param float $conversionValue the value of the conversion
* @param string|null $conversionCustomVariableId the ID of the conversion custom variable to
* associate with the upload
* @param string|null $conversionCustomVariableValue the value of the conversion custom
* variable to associate with the upload
*/
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $conversionActionId,
?string $gclid,
?string $gbraid,
?string $wbraid,
string $conversionDateTime,
float $conversionValue,
?string $conversionCustomVariableId,
?string $conversionCustomVariableValue
) {
// Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
// See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
$nonNullFields = array_filter(
[$gclid, $gbraid, $wbraid],
function ($field) {
return !is_null($field);
}
);
if (count($nonNullFields) !== 1) {
throw new \UnexpectedValueException(
sprintf(
"Exactly 1 of gclid, gbraid or wbraid is required, but %d ID values were "
. "provided",
count($nonNullFields)
)
);
}
// Creates a click conversion by specifying currency as USD.
$clickConversion = new ClickConversion([
'conversion_action' =>
ResourceNames::forConversionAction($customerId, $conversionActionId),
'conversion_value' => $conversionValue,
'conversion_date_time' => $conversionDateTime,
'currency_code' => 'USD'
]);
// Sets the single specified ID field.
if (!is_null($gclid)) {
$clickConversion->setGclid($gclid);
} elseif (!is_null($gbraid)) {
$clickConversion->setGbraid($gbraid);
} else {
$clickConversion->setWbraid($wbraid);
}
if (!is_null($conversionCustomVariableId) && !is_null($conversionCustomVariableValue)) {
$clickConversion->setCustomVariables([new CustomVariable([
'conversion_custom_variable' => ResourceNames::forConversionCustomVariable(
$customerId,
$conversionCustomVariableId
),
'value' => $conversionCustomVariableValue
])]);
}
// Issues a request to upload the click conversion.
$conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
/** @var UploadClickConversionsResponse $response */
$response = $conversionUploadServiceClient->uploadClickConversions(
$customerId,
[$clickConversion],
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.
if ($response->hasPartialFailureError()) {
printf(
"Partial failures occurred: '%s'.%s",
$response->getPartialFailureError()->getMessage(),
PHP_EOL
);
} else {
// Prints the result if exists.
/** @var ClickConversionResult $uploadedClickConversion */
$uploadedClickConversion = $response->getResults()[0];
printf(
"Uploaded click conversion that occurred at '%s' from Google Click ID '%s' " .
"to '%s'.%s",
$uploadedClickConversion->getConversionDateTime(),
$uploadedClickConversion->getGclid(),
$uploadedClickConversion->getConversionAction(),
PHP_EOL
);
}
}
}
UploadOfflineConversion::main();
Python
#!/usr/bin/env python
# Copyright 2020 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.
"""This example imports offline conversion values for specific clicks.
To get Google Click ID for a click, use the "click_view" resource:
https://developers.google.com/google-ads/api/fields/latest/click_view.
To set up a conversion action, run the add_conversion_action.py example.
"""
import argparse
import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
def main(
client,
customer_id,
conversion_action_id,
gclid,
conversion_date_time,
conversion_value,
conversion_custom_variable_id,
conversion_custom_variable_value,
gbraid,
wbraid,
):
"""Creates a click conversion with a default currency of USD.
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.
gclid: The Google Click Identifier ID. If set, the wbraid and gbraid
parameters must be None.
conversion_date_time: The the date and time of the conversion (should be
after the click time). The format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm',
e.g. '2021-01-01 12:32:45-08:00'.
conversion_value: The conversion value in the desired currency.
conversion_custom_variable_id: The ID of the conversion custom
variable to associate with the upload.
conversion_custom_variable_value: The str value of the conversion custom
variable to associate with the upload.
gbraid: The GBRAID for the iOS app conversion. If set, the gclid and
wbraid parameters must be None.
wbraid: The WBRAID for the iOS app conversion. If set, the gclid and
gbraid parameters must be None.
"""
click_conversion = client.get_type("ClickConversion")
conversion_action_service = client.get_service("ConversionActionService")
click_conversion.conversion_action = conversion_action_service.conversion_action_path(
customer_id, conversion_action_id
)
# Sets the single specified ID field.
if gclid:
click_conversion.gclid = gclid
elif gbraid:
click_conversion.gbraid = gbraid
else:
click_conversion.wbraid = wbraid
click_conversion.conversion_value = float(conversion_value)
click_conversion.conversion_date_time = conversion_date_time
click_conversion.currency_code = "USD"
if conversion_custom_variable_id and conversion_custom_variable_value:
conversion_custom_variable = client.get_type("CustomVariable")
conversion_custom_variable.conversion_custom_variable = (
conversion_custom_variable_id
)
conversion_custom_variable.value = conversion_custom_variable_value
click_conversion.custom_variables.append(conversion_custom_variable)
conversion_upload_service = client.get_service("ConversionUploadService")
request = client.get_type("UploadClickConversionsRequest")
request.customer_id = customer_id
request.conversions = [click_conversion]
request.partial_failure = True
conversion_upload_response = conversion_upload_service.upload_click_conversions(
request=request,
)
uploaded_click_conversion = conversion_upload_response.results[0]
print(
f"Uploaded conversion that occurred at "
f'"{uploaded_click_conversion.conversion_date_time}" from '
f'Google Click ID "{uploaded_click_conversion.gclid}" '
f'to "{uploaded_click_conversion.conversion_action}"'
)
if __name__ == "__main__":
# GoogleAdsClient will read the google-ads.yaml configuration file in the
# home directory if none is specified.
googleads_client = GoogleAdsClient.load_from_storage(version="v10")
parser = argparse.ArgumentParser(
description="Uploads an offline conversion."
)
# 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 conversion action ID.",
)
parser.add_argument(
"-t",
"--conversion_date_time",
type=str,
required=True,
help="The date and time of the "
"conversion (should be after the click time). The "
'format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", e.g. '
"“2019-01-01 12:32:45-08:00”",
)
parser.add_argument(
"-v",
"--conversion_value",
type=str,
required=True,
help="The conversion value.",
)
parser.add_argument(
"-w",
"--conversion_custom_variable_id",
type=str,
help="The ID of the conversion custom variable to associate with the upload.",
)
parser.add_argument(
"-x",
"--conversion_custom_variable_value",
type=str,
help="The value of the conversion custom variable to associate with the upload.",
)
group = parser.add_mutually_exclusive_group(required=True)
group.add_argument(
"-g",
"--gclid",
type=str,
help="The Google Click Identifier (gclid) which should be newer than "
"the number of days set on the conversion window of the conversion "
"action. Only one of either a gclid, WBRAID, or GBRAID identifier can "
"be passed into this example. See the following for more details: "
"https://developers.google.com/google-ads/api/docs/conversions/upload-clicks",
)
group.add_argument(
"-b",
"--gbraid",
type=str,
help="The GBRAID identifier for an iOS app conversion. Only one of "
"either a gclid, WBRAID, or GBRAID identifier can be passed into this "
"example. See the following for more details: "
"https://developers.google.com/google-ads/api/docs/conversions/upload-clicks",
)
group.add_argument(
"-d",
"--wbraid",
type=str,
help="The WBRAID identifier for an iOS app conversion. Only one of "
"either a gclid, WBRAID, or GBRAID identifier can be passed into this "
"example. See the following for more details: "
"https://developers.google.com/google-ads/api/docs/conversions/upload-clicks",
)
args = parser.parse_args()
try:
main(
googleads_client,
args.customer_id,
args.conversion_action_id,
args.gclid,
args.conversion_date_time,
args.conversion_value,
args.conversion_custom_variable_id,
args.conversion_custom_variable_value,
args.gbraid,
args.wbraid,
)
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
# Encoding: utf-8
#
# Copyright 2020 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.
#
# This example imports offline conversion values for specific clicks.
#
# To get Google Click ID for a click, use the "click_view" resource:
# https://developers.google.com/google-ads/api/fields/latest/click_view.
# To set up a conversion action, run the add_conversion_action.rb example.
require 'optparse'
require 'google/ads/google_ads'
def upload_offline_conversion(
customer_id,
conversion_action_id,
gclid,
gbraid,
wbraid,
conversion_date_time,
conversion_value,
conversion_custom_variable_id,
conversion_custom_variable_value)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
# See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
identifiers_specified = [gclid, gbraid, wbraid].reject {|v| v.nil?}.count
if identifiers_specified != 1
raise "Must specify exactly one of GCLID, GBRAID, and WBRAID. " \
"#{identifiers_specified} values were provided."
end
click_conversion = client.resource.click_conversion do |cc|
cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
# Sets the single specified ID field.
if !gclid.nil?
cc.gclid = gclid
elsif !gbraid.nil?
cc.gbraid = gbraid
else
cc.wbraid = wbraid
end
cc.conversion_value = conversion_value.to_f
cc.conversion_date_time = conversion_date_time
cc.currency_code = 'USD'
if conversion_custom_variable_id && conversion_custom_variable_value
cc.custom_variables << client.resource.custom_variable do |cv|
cv.conversion_custom_variable = client.path.conversion_custom_variable(
customer_id, conversion_custom_variable_id)
cv.value = conversion_custom_variable_value
end
end
end
response = client.service.conversion_upload.upload_click_conversions(
customer_id: customer_id,
conversions: [click_conversion],
partial_failure: true,
)
if response.partial_failure_error.nil?
result = response.results.first
puts "Uploaded conversion that occurred at #{result.conversion_date_time} " \
"from Google Click ID #{result.gclid} to #{result.conversion_action}."
else
failures = client.decode_partial_failure_error(response.partial_failure_error)
puts "Request failed. Failure details:"
failures.each do |failure|
failure.errors.each do |error|
puts "\t#{error.error_code.error_code}: #{error.message}"
end
end
end
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[:gclid] = nil
options[:gbraid] = nil
options[:wbraid] = nil
options[:conversion_date_time] = 'INSERT_CONVERSION_DATE_TIME_HERE'
options[:conversion_value] = 'INSERT_CONVERSION_VALUE_HERE'
# Optional: Specify the conversion custom variable ID and value you want to
# associate with the click conversion upload.
options[:conversion_custom_variable_id] = nil;
options[:conversion_custom_variable_value] = nil;
OptionParser.new do |opts|
opts.banner = sprintf('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('-g', '--gclid GCLID', String,
'Google Click ID (should be newer than the number of days set ' \
'on the conversion window of the conversion action).' \
'If setting this option, don\'t set GBRAID or WBRAID') do |v|
options[:gclid] = v
end
opts.on('-G', '--gbraid GBRAID', String,
'The GBRAID identifier for an iOS app conversion. If setting this value, ' \
'do not set GCLID or WBRAID.') do |v|
options[:gbraid] = v
end
opts.on('w', '--wbraid WBRAID', String,
'The WBRAID identifier for an iOS app conversion. If setting this value, ' \
'do not set GCLID or GBRAID.') do |v|
options[:wbraid] = v
end
opts.on('-t', '--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", ' \
'for example: “2019-01-01 12:32:45-08:00”') do |v|
options[:conversion_date_time] = v
end
opts.on('-v', '--conversion-value CONVERSION-VALUE', String, 'Conversion Value') do |v|
options[:conversion_value] = v
end
opts.on('-d', '--conversion-custom-variable-id CONVERSION-CUSTOM-VARIABLE-ID', \
String, '(Optional) The ID of the conversion custom variable to ' \
'associate with the upload') do |v|
options[:conversion_custom_variable_id] = v
end
opts.on('-u', '--conversion-custom-variable-value CONVERSION-CUSTOM-VARIABLE-VALUE', \
String, '(Optional) The value of the conversion custom ' \
'variable to associate with the upload') do |v|
options[:conversion_custom_variable_value] = v
end
opts.separator ''
opts.separator 'Help:'
opts.on_tail('-h', '--help', 'Show this message') do
puts opts
exit
end
end.parse!
begin
upload_offline_conversion(
options.fetch(:customer_id).tr("-", ""),
options.fetch(:conversion_action_id),
options[:gclid],
options[:gbraid],
options[:wbraid],
options.fetch(:conversion_date_time),
options.fetch(:conversion_value),
options[:conversion_custom_variable_id],
options[:conversion_custom_variable_value],
)
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
e.failure.errors.each do |error|
STDERR.printf("Error with message: %s\n", error.message)
if error.location
error.location.field_path_elements.each do |field_path_element|
STDERR.printf("\tOn field: %s\n", field_path_element.field_name)
end
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
end
end
Perl
#!/usr/bin/perl -w
#
# Copyright 2019, 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.
#
# This example imports offline conversion values for specific clicks to your account.
# To get Google Click ID for a click, use the "click_view" resource:
# https://developers.google.com/google-ads/api/fields/latest/click_view.
# To set up a conversion action, run the add_conversion_action.pl example.
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::V10::Services::ConversionUploadService::ClickConversion;
use
Google::Ads::GoogleAds::V10::Services::ConversionUploadService::CustomVariable;
use Google::Ads::GoogleAds::V10::Utils::ResourceNames;
use Getopt::Long qw(:config auto_help);
use Pod::Usage;
use Cwd qw(abs_path);
# 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";
# Set exactly one of gclid, gbraid, or wbraid.
my $gclid = "INSERT_GCLID_HERE";
my $gbraid = undef;
my $wbraid = undef;
my $conversion_date_time = "INSERT_CONVERSION_DATE_TIME_HERE";
my $conversion_value = "INSERT_CONVERSION_VALUE_HERE";
# Optional: Specify the conversion custom variable ID and value you want to
# associate with the click conversion upload.
my $conversion_custom_variable_id = undef;
my $conversion_custom_variable_value = undef;
# Optional: Specify the unique order ID for the click conversion.
my $order_id = undef;
sub upload_offline_conversion {
my (
$api_client, $customer_id,
$conversion_action_id, $gclid,
$gbraid, $wbraid,
$conversion_date_time, $conversion_value,
$conversion_custom_variable_id, $conversion_custom_variable_value,
$order_id
) = @_;
# Verify that exactly one of gclid, gbraid, and wbraid is specified, as required.
# See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
my $number_of_ids_specified = grep { defined $_ } ($gclid, $gbraid, $wbraid);
if ($number_of_ids_specified != 1) {
die sprintf "Exactly 1 of gclid, gbraid, or wbraid is required, " .
"but %d ID values were provided.\n",
$number_of_ids_specified;
}
# Create a click conversion by specifying currency as USD.
my $click_conversion =
Google::Ads::GoogleAds::V10::Services::ConversionUploadService::ClickConversion
->new({
conversionAction =>
Google::Ads::GoogleAds::V10::Utils::ResourceNames::conversion_action(
$customer_id, $conversion_action_id
),
conversionDateTime => $conversion_date_time,
conversionValue => $conversion_value,
currencyCode => "USD"
});
# Set the single specified ID field.
if (defined $gclid) {
$click_conversion->{gclid} = $gclid;
} elsif (defined $gbraid) {
$click_conversion->{gbraid} = $gbraid;
} else {
$click_conversion->{wbraid} = $wbraid;
}
if ($conversion_custom_variable_id && $conversion_custom_variable_value) {
$click_conversion->{customVariables} = [
Google::Ads::GoogleAds::V10::Services::ConversionUploadService::CustomVariable
->new({
conversionCustomVariable =>
Google::Ads::GoogleAds::V10::Utils::ResourceNames::conversion_custom_variable(
$customer_id, $conversion_custom_variable_id
),
value => $conversion_custom_variable_value
})];
}
if (defined $order_id) {
# Set the order ID (unique transaction ID), if provided. An order ID is
# required in order to upload enhancements as shown in the
# upload_conversion_enhancement.pl example.
$click_conversion->{orderId} = $order_id;
}
# Issue a request to upload the click conversion.
my $upload_click_conversions_response =
$api_client->ConversionUploadService()->upload_click_conversions({
customerId => $customer_id,
conversions => [$click_conversion],
partialFailure => "true"
});
# Print any partial errors returned.
if ($upload_click_conversions_response->{partialFailureError}) {
printf "Partial error encountered: '%s'.\n",
$upload_click_conversions_response->{partialFailureError}{message};
}
# Print the result if valid.
my $uploaded_click_conversion =
$upload_click_conversions_response->{results}[0];
if (%$uploaded_click_conversion) {
printf
"Uploaded conversion that occurred at '%s' from Google Click ID '%s' " .
"to the conversion action with resource name '%s'.\n",
$uploaded_click_conversion->{conversionDateTime},
$uploaded_click_conversion->{gclid},
$uploaded_click_conversion->{conversionAction};
}
return 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,
"gclid=s" => \$gclid,
"gbraid=s" => \$gbraid,
"wbraid=s" => \$wbraid,
"conversion_date_time=s" => \$conversion_date_time,
"conversion_value=f" => \$conversion_value,
"conversion_custom_variable_id=s" => \$conversion_custom_variable_id,
"conversion_custom_variable_value=s" => \$conversion_custom_variable_value,
"order_id=s" => \$order_id
);
# 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,
$conversion_date_time, $conversion_value
);
# Call the example.
upload_offline_conversion(
$api_client, $customer_id =~ s/-//gr,
$conversion_action_id, $gclid,
$gbraid, $wbraid,
$conversion_date_time, $conversion_value,
$conversion_custom_variable_id, $conversion_custom_variable_value,
$order_id
);
=pod
=head1 NAME
upload_offline_conversion
=head1 DESCRIPTION
This example imports offline conversion values for specific clicks to your account.
To get Google Click ID for a click, use the "click_view" resource:
https://developers.google.com/google-ads/api/fields/latest/click_view.
To set up a conversion action, run the add_conversion_action.pl example.
=head1 SYNOPSIS
upload_offline_conversion.pl [options]
-help Show the help message.
-customer_id The Google Ads customer ID.
-conversion_action_id The ID of the conversion action to upload to.
-gclid [optional] The GCLID for the conversion. If setting this value, do not
set -gbraid or -wbraid.
-gbraid [optional] The GBRAID for the iOS app conversion. If setting this value,
do not set -gclid or -wbraid.
-wbraid [optional] The WBRAID for the iOS web conversion. If setting this value,
do not set -gclid or -gbraid.
-conversion_date_time The date and time of the conversion (should be after the click time).
The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", e.g. "2019-01-01 12:32:45-08:00".
-conversion_value The value of the conversion.
-conversion_custom_variable_id [optional] The ID of the conversion custom variable to associate with the upload.
-conversion_custom_variable_value [optional] The value of the conversion custom variable to associate with the upload.
-order_id [optional] The unique ID (transaction ID) of the conversion.
=cut
