Google Ads API を使用して、オフライン クリック コンバージョンを Google 広告にアップロードし、Google 広告の管理画面で [アップロード] のコンバージョン ソースにマッピングしてから、[クリックに起因するコンバージョン] にマッピングできます。これにより、クリックをコンバージョンに関連付ける柔軟性が高まります。電話や営業担当者など、オフライン環境での売り上げにつながった広告をトラッキングできます。
ID パラメータ
ウェブサイトとリード トラッキング システムで GCLID（Google 広告のすべてのインプレッションに付与される一意の ID）を取得し、保存できるようにする必要があります。クリック コンバージョンが Google 広告の管理画面にアップロードされると、自動タグ設定が自動的に有効になります。これにより、GCLID が URL パラメータとしてウェブサイトに送信されます。ただし、Google Ads API を使用する場合は発生しないため、Customer の auto_tagging_enabled 属性を更新して、自動タグ設定を有効にしてください。
iOS 14 以降の場合、クリックには gclid パラメータの代わりに、wbraid パラメータ（ウェブ コンバージョンに関連付けられたクリックの場合）または gbraid パラメータ（アプリ コンバージョンに関連付けられたクリックの場合）を含めることができます。
ClickConversion に wbraid、gbraid、gclid、user_identifiers の組み合わせを指定する場合は、次の制限に留意してください。
wbraidとgbraidの両方を指定すると、エラーが発生します。GBRAID_WBRAID_BOTH_SETwbraidまたはgbraidを指定してgclidまたはuser_identifiersを含めると、VALUE_MUST_BE_UNSETエラーが発生します。wbraidとgbraidは指定せず、gclidとuser_identifiersの両方を指定します。gclidが優先されます。
また、カスタム コンバージョン変数は、wbraid または gbraid との組み合わせではサポートされません。そのため、custom_variables も含めながら wbraid または gbraid を指定すると、VALUE_MUST_BE_UNSET というエラーが発生します。
サンプルコード
gclid、gbraid、または wbraid の識別子を渡して、オフライン クリック コンバージョンをコンバージョン アクションに関連付ける必要があります。さらに、コンバージョンの日時とコンバージョン アクションのリソース名を指定します。必要に応じて、コンバージョン値と通貨を ConversionUploadService に指定します。
Java
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#
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.V14.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
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
);
}
}
Python
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_upload_service = client.get_service("ConversionUploadService")
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_upload_service.conversion_custom_variable_path(
customer_id, conversion_custom_variable_id
)
conversion_custom_variable.value = conversion_custom_variable_value
click_conversion.custom_variables.append(conversion_custom_variable)
request = client.get_type("UploadClickConversionsRequest")
request.customer_id = customer_id
request.conversions.append(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}"'
)
Ruby
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
Perl
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::V14::Services::ConversionUploadService::ClickConversion
->new({
conversionAction =>
Google::Ads::GoogleAds::V14::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::V14::Services::ConversionUploadService::CustomVariable
->new({
conversionCustomVariable =>
Google::Ads::GoogleAds::V14::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;
}
外部で貢献度が割り当てられたコンバージョンをインポートする
サードパーティのツールや独自のソリューションを使用してコンバージョンをトラッキングする場合は、コンバージョンに対する貢献度の一部だけを Google 広告に割り当てましょう。場合によっては、コンバージョンのクレジットを複数のクリックに分配したい場合もあります。外部で貢献度が割り当てられたコンバージョンのインポートを使用すると、各クリックに小数値の貢献度が割り当てられたコンバージョンをアップロードできます。
小数値のクレジットをアップロードするには、upload_offline_conversion のコード例を使用し、ClickConversion の作成時に ExternalAttributionData の external_attribution_model 属性と external_attribution_credit 属性を指定する必要があります。
コンバージョンにカートデータを含める
cart_data フィールドに次の属性の ClickConversion のショッピング カート情報を含めることができます。
merchant_id: 関連付けられている Merchant Center アカウントの ID。feed_country_code: Merchant Center フィードの ISO 3166 2 文字の地域コード。feed_language_code: Merchant Center フィードの ISO 639-1 言語コード。local_transaction_cost:ClickConversionのcurrency_codeにおけるすべてのトランザクション レベルの割引の合計。items: ショッピング カート内の商品。
items の各項目は次の属性で構成されています。
product_id: 商品の ID。特典 ID またはアイテム ID と呼ばれることもあります。quantity: 商品アイテムの数量。unit_price: アイテムの単価。
ClickConversion のアップロード
ClickConversion をアップロードする際は、いくつかの要件を満たす必要があります。
ConversionUploadError.INVALID_CONVERSION_ACTION エラーを回避するには、conversion_action 属性が ConversionAction を参照している必要があります。
ConversionActionTypeはUPLOAD_CLICKSです。ConversionActionのstatusはENABLEDです。ConversionActionは、クリックの Google 広告アカウントの有効なコンバージョン アカウントに存在します。- クリック時に、クリックの Google 広告アカウントの有効なコンバージョン アカウントでコンバージョン トラッキングが有効になったこと。
UploadClickConversionsRequestのcustomer_idは、各クリック コンバージョンのconversion_actionのowner_customerのお客様 ID である必要があります。
これに加えて次の条件を満たす必要があります。
UploadClickConversionsRequestのcustomer_idは、クリックの Google 広告アカウントの有効なコンバージョン トラッキング アカウントのお客様 ID にする必要があります。そうしないと、コンバージョンのアップロードによりConversionUploadError.INVALID_CUSTOMER_FOR_CLICKエラーが発生します。ConversionUploadError.CONVERSION_PRECEDES_GCLIDエラーを回避するため、conversion_date_timeはインプレッション発生後に行う必要があります。ConversionUploadError.EXPIRED_GCLIDエラーを回避するため、ConversionActionに指定したclick_through_lookback_window_daysの前にconversion_date_timeを設定する必要があります。conversion_valueは 0 以上である必要があります。conversion_date_timeにはタイムゾーンを指定する必要があります。形式はyyyy-mm-dd HH:mm:ss+|-HH:mmです（例:2022-01-01 19:32:45-05:00は夏時間を無視します）。タイムゾーンには有効な値を使用できます。アカウントのタイムゾーンと一致させる必要はありません。ただし、アップロードしたコンバージョン データを Google 広告管理画面のものと比較する場合は、コンバージョンのカウント結果が同じになるように、Google 広告アカウントと同じタイムゾーンを使用することをおすすめします。
ClickConversion を作成
ClickConversion を作成する際の注意点:
UploadClickConversionsRequestのpartial_failure属性は常にtrueに設定する必要があります。有効なオペレーションと失敗したオペレーションを同時に処理する場合は、部分的な障害に関するガイドラインをご覧ください。コンバージョンを重複してアップロードすると（つまり、以前にアップロードされた
gclid、conversion_date_time、conversion_actionのClickConversion）、CLICK_CONVERSION_ALREADY_EXISTSエラーが返されます。1 つのリクエストに、同じコンバージョンに対するオペレーションが複数含まれている場合は、
DUPLICATE_CLICK_CONVERSION_IN_REQUESTエラーが返されます。アップロードされたコンバージョンは、アップロード リクエストの日付や
ClickConversionのconversion_date_timeの日付ではなく、元のクリックのインプレッションの日付に反映されます。アップロード コンバージョン リクエストに対して
TOO_RECENT_CONVERSION_ACTIONまたはTOO_RECENT_EVENTレスポンス メッセージが表示された場合は、アクションの作成またはイベントから少なくとも 6 時間待ってから、失敗した行を再試行してください。ラストクリック アトリビューションの場合、インポートしたコンバージョンの統計情報が Google 広告アカウントに表示されるまでに最大 3 時間かかります。他の検索アトリビューション モデルの場合、3 時間以上かかる場合があります。
複数のアカウントのクリック コンバージョンをアップロードする場合は、共通の MCC アカウントの
customer_idを指定し、複数のアカウントの GCLID を含むコンバージョンを含めることができます。コンバージョンは、GCLID の生成元に基づいて、適切なアカウントに関連付けられます。この方法は、次の条件を両方とも満たしている場合にのみ成功します。
- GCLID のクライアント アカウントの有効なコンバージョン アカウントが、リクエストの
customer_idで指定されたマネージャーに設定されている。 ClickConversionのconversion_actionは、リクエストのcustomer_idで指定されたマネージャーによって所有されます。
- GCLID のクライアント アカウントの有効なコンバージョン アカウントが、リクエストの
クロスアカウント コンバージョン トラッキングを有効にしてクリック コンバージョンをアップロードする場合、コンバージョン アクションは、GCLID に関連付けられたアカウントではなく MCC アカウントにある必要があります。
拡張コンバージョンの自社データ調整をアップロードする場合は、
ClickConversionごとにorder_idを指定する必要があります。