Google Ads API を使用して オフライン クリック コンバージョンを Google 広告 にアップロードすると、電話や営業担当者経由など、オフラインでの売上につながった広告をトラッキングできます。
設定
オフライン コンバージョンを設定するには、いくつかの前提条件があります。実装に進む前に、すべての前提条件を満たしていることを確認してください。
Google 広告のコンバージョン顧客でコンバージョン トラッキングを有効にします。
タグを設定してクリック ID を保存します。
1. Google 広告のコンバージョン顧客でコンバージョン トラッキングを有効にする
コンバージョンのスタートガイド を完了し、コンバージョン トラッキングが有効になっている場合は、 ステップ 2 のタグの設定に進んでください。
コンバージョン トラッキングの設定に関する情報を取得する
アカウントのコンバージョン トラッキングの設定を確認し、コンバージョン
トラッキングが有効になっていることを確認するには、Customer リソース
に対して ConversionTrackingSetting のクエリを実行します。
GoogleAdsService.SearchStream を使用して次のクエリを発行します。
SELECT
customer.conversion_tracking_setting.google_ads_conversion_customer,
customer.conversion_tracking_setting.conversion_tracking_status,
customer.conversion_tracking_setting.conversion_tracking_id,
customer.conversion_tracking_setting.cross_account_conversion_tracking_id
FROM customer
google_ads_conversion_customer フィールドは、この顧客のコンバージョンを作成して管理する Google 広告アカウントを示します。クロスアカウント コンバージョン トラッキングを使用している顧客の場合、これはクライアント センター(MCC)アカウントの ID です。コンバージョンを作成して管理するには、Google 広告のコンバージョン顧客 ID を Google Ads API リクエストの customer_id として指定する必要があります。
このフィールドは、コンバージョン トラッキングが有効になっていない場合でも入力されます。
The
conversion_tracking_status
フィールドは、コンバージョン トラッキングが有効になっているかどうか、アカウント
がクロスアカウント コンバージョン トラッキングを使用しているかどうかを示します。
Google 広告のコンバージョン顧客でコンバージョン アクションを作成する
conversion_tracking_status の値が NOT_CONVERSION_TRACKED の場合、アカウントでコンバージョン トラッキングが有効になっていません。次の例のように、Google 広告のコンバージョン アカウントで 1 つ以上の ConversionAction を作成して、コンバージョン トラッキングを有効にします。または、有効にするコンバージョン タイプについて
ヘルプセンターの手順に沿って、UI でコンバージョン アクションを作成することもできます。
拡張コンバージョンは、Google Ads API を介して送信されると自動的に有効になりますが、Google 広告の UI で無効にできます。
サンプルコード
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) { // Creates a ConversionAction. ConversionAction conversionAction = ConversionAction.newBuilder() // Note that conversion action names must be unique. If a conversion action already // exists with the specified conversion_action_name the create operation will fail with // a ConversionActionError.DUPLICATE_NAME error. .setName("Earth to Mars Cruises Conversion #" + getPrintableDateTime()) .setCategory(ConversionActionCategory.DEFAULT) .setType(ConversionActionType.WEBPAGE) .setStatus(ConversionActionStatus.ENABLED) .setViewThroughLookbackWindowDays(15L) .setValueSettings( ValueSettings.newBuilder() .setDefaultValue(23.41) .setAlwaysUseDefaultValue(true) .build()) .build(); // Creates the operation. ConversionActionOperation operation = ConversionActionOperation.newBuilder().setCreate(conversionAction).build(); try (ConversionActionServiceClient conversionActionServiceClient = googleAdsClient.getLatestVersion().createConversionActionServiceClient()) { MutateConversionActionsResponse response = conversionActionServiceClient.mutateConversionActions( Long.toString(customerId), Collections.singletonList(operation)); System.out.printf("Added %d conversion actions:%n", response.getResultsCount()); for (MutateConversionActionResult result : response.getResultsList()) { System.out.printf( "New conversion action added with resource name: '%s'%n", result.getResourceName()); } } }
C#
public void Run(GoogleAdsClient client, long customerId) { // Get the ConversionActionService. ConversionActionServiceClient conversionActionService = client.GetService(Services.V23.ConversionActionService); // Note that conversion action names must be unique. // If a conversion action already exists with the specified name the create operation // will fail with a ConversionAction.DUPLICATE_NAME error. string ConversionActionName = "Earth to Mars Cruises Conversion #" + ExampleUtilities.GetRandomString(); // Add a conversion action. ConversionAction conversionAction = new ConversionAction() { Name = ConversionActionName, Category = ConversionActionCategory.Default, Type = ConversionActionType.Webpage, Status = ConversionActionStatus.Enabled, ViewThroughLookbackWindowDays = 15, ValueSettings = new ConversionAction.Types.ValueSettings() { DefaultValue = 23.41, AlwaysUseDefaultValue = true } }; // Create the operation. ConversionActionOperation operation = new ConversionActionOperation() { Create = conversionAction }; try { // Create the conversion action. MutateConversionActionsResponse response = conversionActionService.MutateConversionActions(customerId.ToString(), new ConversionActionOperation[] { operation }); // Display the results. foreach (MutateConversionActionResult newConversionAction in response.Results) { Console.WriteLine($"New conversion action with resource name = " + $"'{newConversionAction.ResourceName}' was added."); } } 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) { // Creates a conversion action. $conversionAction = new ConversionAction([ // Note that conversion action names must be unique. // If a conversion action already exists with the specified conversion_action_name // the create operation will fail with a ConversionActionError.DUPLICATE_NAME error. 'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(), 'category' => ConversionActionCategory::PBDEFAULT, 'type' => ConversionActionType::WEBPAGE, 'status' => ConversionActionStatus::ENABLED, 'view_through_lookback_window_days' => 15, 'value_settings' => new ValueSettings([ 'default_value' => 23.41, 'always_use_default_value' => true ]) ]); // Creates a conversion action operation. $conversionActionOperation = new ConversionActionOperation(); $conversionActionOperation->setCreate($conversionAction); // Issues a mutate request to add the conversion action. $conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient(); $response = $conversionActionServiceClient->mutateConversionActions( MutateConversionActionsRequest::build($customerId, [$conversionActionOperation]) ); printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL); foreach ($response->getResults() as $addedConversionAction) { /** @var ConversionAction $addedConversionAction */ printf( "New conversion action added with resource name: '%s'%s", $addedConversionAction->getResourceName(), PHP_EOL ); } }
Python
def main(client: GoogleAdsClient, customer_id: str) -> None: conversion_action_service: ConversionActionServiceClient = ( client.get_service("ConversionActionService") ) # Create the operation. conversion_action_operation: ConversionActionOperation = client.get_type( "ConversionActionOperation" ) # Create conversion action. conversion_action: ConversionAction = conversion_action_operation.create # Note that conversion action names must be unique. If a conversion action # already exists with the specified conversion_action_name, the create # operation will fail with a ConversionActionError.DUPLICATE_NAME error. conversion_action.name = f"Earth to Mars Cruises Conversion {uuid.uuid4()}" conversion_action.type_ = ( client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS ) conversion_action.category = ( client.enums.ConversionActionCategoryEnum.DEFAULT ) conversion_action.status = client.enums.ConversionActionStatusEnum.ENABLED conversion_action.view_through_lookback_window_days = 15 # Create a value settings object. value_settings: ConversionAction.ValueSettings = ( conversion_action.value_settings ) value_settings.default_value = 15.0 value_settings.always_use_default_value = True # Add the conversion action. conversion_action_response: MutateConversionActionsResponse = ( conversion_action_service.mutate_conversion_actions( customer_id=customer_id, operations=[conversion_action_operation], ) ) print( "Created conversion action " f'"{conversion_action_response.results[0].resource_name}".' )
Ruby
def add_conversion_action(customer_id) # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new # Add a conversion action. conversion_action = client.resource.conversion_action do |ca| ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}" ca.type = :UPLOAD_CLICKS ca.category = :DEFAULT ca.status = :ENABLED ca.view_through_lookback_window_days = 15 # Create a value settings object. ca.value_settings = client.resource.value_settings do |vs| vs.default_value = 15 vs.always_use_default_value = true end end # Create the operation. conversion_action_operation = client.operation.create_resource.conversion_action(conversion_action) # Add the ad group ad. response = client.service.conversion_action.mutate_conversion_actions( customer_id: customer_id, operations: [conversion_action_operation], ) puts "New conversion action with resource name = #{response.results.first.resource_name}." end
Perl
sub add_conversion_action { my ($api_client, $customer_id) = @_; # Note that conversion action names must be unique. # If a conversion action already exists with the specified conversion_action_name, # the create operation fails with error ConversionActionError.DUPLICATE_NAME. my $conversion_action_name = "Earth to Mars Cruises Conversion #" . uniqid(); # Create a conversion action. my $conversion_action = Google::Ads::GoogleAds::V24::Resources::ConversionAction->new({ name => $conversion_action_name, category => DEFAULT, type => WEBPAGE, status => ENABLED, viewThroughLookbackWindowDays => 15, valueSettings => Google::Ads::GoogleAds::V24::Resources::ValueSettings->new({ defaultValue => 23.41, alwaysUseDefaultValue => "true" })}); # Create a conversion action operation. my $conversion_action_operation = Google::Ads::GoogleAds::V24::Services::ConversionActionService::ConversionActionOperation ->new({create => $conversion_action}); # Add the conversion action. my $conversion_actions_response = $api_client->ConversionActionService()->mutate({ customerId => $customer_id, operations => [$conversion_action_operation]}); printf "New conversion action added with resource name: '%s'.\n", $conversion_actions_response->{results}[0]{resourceName}; return 1; }
curl
conversion_action_type が正しい
ConversionActionType 値に設定されていることを確認します。
Google Ads API でコンバージョン アクションを作成する方法について詳しくは、コンバージョン アクションを作成するをご覧ください。
既存のコンバージョン アクションを取得する
次のクエリを発行すると、既存のコンバージョン アクションの詳細を取得できます。リクエストの顧客 ID が、上記で特定した Google 広告の
コンバージョン顧客に設定され、コンバージョン アクション タイプが正しい
ConversionActionType
値に設定されていることを確認します。
SELECT
conversion_action.resource_name,
conversion_action.name,
conversion_action.status
FROM conversion_action
WHERE conversion_action.type = 'INSERT_CONVERSION_ACTION_TYPE'
2. タグを設定してクリック ID を保存する
手順に沿って自動タグ設定が有効になっていることを確認します。Google 広告アカウント、ウェブサイト、リード トラッキング システムを設定して、各インプレッションの GCLID と、広告の GBRAID または WBRAID の URL パラメータを取得して保存します。自動タグ設定は、アカウントを新規に作成するとデフォルトで有効になります。
リクエストを作成する
このガイダンスに沿って
UploadClickConversionsRequest
を作成し、そのフィールドを適切な値に設定します。
customer_idアップロードする Google 広告アカウントを識別します。これを、クリックのソースとなるアカウントの Google 広告 コンバージョン顧客 に設定します。
job_idアップロード リクエストをオフライン データ診断のジョブごとの 情報に 関連付けるメカニズムを提供します。
このフィールドを設定しない場合、Google Ads API は各リクエストに
[2^31, 2^63)の範囲で一意の値を割り当てます。複数のリクエストを 1 つの論理ジョブにグループ化する場合は、ジョブ内のすべてのリクエストで、このフィールドを[0, 2^31)の範囲で同じ値に設定します。job_idは、値を指定したか、Google Ads API に値を割り当てさせたかに関係なく、リクエストのジョブ ID を含んでいます。partial_failure_enabledGoogle Ads API がオペレーションのエラーを処理する方法を決定します。
このフィールドは
trueに設定する必要があります。レスポンスを処理する際は、部分的なエラー に関するガイドラインに沿って進めてください。debug_enabledリードの拡張コンバージョンのアップロードのエラーレポートの動作を決定します。Google Ads API は、
gclid、gbraid、wbraidの URL パラメータを使用してクリック コンバージョンのアップロードを処理する際に、このフィールドを無視します。
クリック コンバージョン オペレーションを作成する
内の ClickConversion オブジェクトのコレクションは、アップロードするコンバージョンのセットを定義します。UploadClickConversionRequestこのガイダンスに沿って各 ClickConversion を作成し、そのフィールドを適切な値に設定します。
各コンバージョン オペレーションの必須フィールドを設定する
次の手順に沿って、ClickConversion の必須フィールドを適切な値に設定します。
gclid、gbraid、wbraidユーザーが広告をクリックしてウェブサイトまたはアプリにアクセスしたときに取得する GCLID または URL パラメータ。次のいずれかが必要です。
gclidgbraidwbraid
conversion_date_timeコンバージョンの日時。
値にはタイムゾーンを指定する必要があります。形式は
yyyy-mm-dd HH:mm:ss+|-HH:mmにする必要があります(例:2022-01-01 19:32:45-05:00(夏時間は無視) )。タイムゾーンには有効な値を指定できます。アカウントのタイムゾーンと一致させる必要はありません 。ただし、アップロードしたコンバージョン データを Google 広告の UI のデータと比較する場合は、コンバージョン数が一致するように、Google 広告アカウントと同じタイムゾーンを使用することをおすすめします。 詳細と例については、ヘルプ センターをご覧ください。有効なタイムゾーン ID の一覧については、 コードと形式をご覧ください。
user_identifiersクリック ID のみを使用してコンバージョンをアップロードする場合は、このフィールドを設定しないでください。この フィールドが設定されている場合、Google 広告はアップロード オペレーションをリードの拡張 コンバージョンのアップロードとして扱います。
conversion_actionクリック コンバージョンの
ConversionActionのリソース名。コンバージョン アクションの
typeはUPLOAD_CLICKSである必要があり、クリックに関連付けられた Google 広告アカウントの Google 広告のコンバージョン顧客に存在する必要があります。conversion_valueコンバージョンの値。
currency_code通貨コードは
conversion_valueです。
各コンバージョン オペレーションのオプション フィールドを設定する
オプション フィールドの次のリストを確認し、必要に応じて ClickConversion に設定します。
order_id- コンバージョンのトランザクション ID。このフィールドは省略可能ですが、設定することを強くおすすめします。アップロード時に設定した場合は、コンバージョンに対して行われた 調整にも使用する必要があります 。トランザクション ID を使用して重複 コンバージョンを最小限に減らす方法について詳しくは、こちらのヘルプセンター記事をご覧ください。
external_attribution_dataサードパーティのツールや自社開発のソリューションを使用してコンバージョンをトラッキングする場合は、コンバージョンの貢献度の一部のみを Google 広告に付与したり、コンバージョンの貢献度を複数のクリックに分配したりできます。 外部システムによって貢献度の割り当てられたコンバージョン インポートを使用すると、各クリックに割り当てられた小数値の貢献度を含むコンバージョンをアップロードできます。
貢献度の一部をアップロードするには、このフィールドを
ExternalAttributionDataオブジェクト に設定します。値はexternal_attribution_modelとexternal_attribution_creditです。custom_variables-
Google 広告では、カスタム コンバージョン変数を
wbraidまたはgbraidと組み合わせて使用することはできません。
cart_data
ショッピング カートのデータ
を ClickConversion の cart_data
フィールドに含めることができます。このフィールドは次の属性で構成されます。
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: アイテムの単価。
conversion_environment
このコンバージョンが記録された環境を示します。たとえば、アプリ やウェブなどです。
サンプルコード
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, ConsentStatus adUserDataConsent) throws InvalidProtocolBufferException { // 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. clickConversionBuilder.setOrderId(orderId); } // Sets the consent information, if provided. if (adUserDataConsent != null) { // Specifies whether user consent was obtained for the data you are uploading. See // https://www.google.com/about/company/user-consent-policy for details. clickConversionBuilder.setConsent(Consent.newBuilder().setAdUserData(adUserDataConsent)); } 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. // NOTE: This request contains a single conversion as a demonstration. However, if you have // multiple conversions to upload, it's best to upload multiple conversions per request // instead of sending a separate request per conversion. See the following for per-request // limits: // https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service UploadClickConversionsResponse response = conversionUploadServiceClient.uploadClickConversions( UploadClickConversionsRequest.newBuilder() .setCustomerId(Long.toString(customerId)) .addConversions(clickConversion) // Enables partial failure (must be true). .setPartialFailure(true) .build()); // Prints any partial errors returned. if (response.hasPartialFailureError()) { GoogleAdsFailure googleAdsFailure = ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError()); // Constructs a protocol buffer printer that will print error details in a concise format. Printer errorPrinter = JsonFormat.printer().omittingInsignificantWhitespace(); for (int operationIndex = 0; operationIndex < response.getResultsCount(); operationIndex++) { ClickConversionResult conversionResult = response.getResults(operationIndex); if (ErrorUtils.getInstance().isPartialFailureResult(conversionResult)) { // Prints the errors for the failed operation. System.out.printf("Operation %d failed with the following errors:%n", operationIndex); for (GoogleAdsError resultError : ErrorUtils.getInstance().getGoogleAdsErrors(operationIndex, googleAdsFailure)) { // Prints the error with newlines and extra spaces removed. System.out.printf(" %s%n", errorPrinter.print(resultError)); } } else { // Prints the information about the successful operation. StringBuilder clickInfoBuilder = new StringBuilder("conversion that occurred at ") .append(String.format("'%s' ", conversionResult.getConversionDateTime())) .append("with "); if (conversionResult.hasGclid()) { clickInfoBuilder.append(String.format("gclid '%s'", conversionResult.getGclid())); } else if (!conversionResult.getGbraid().isEmpty()) { clickInfoBuilder.append(String.format("gbraid '%s'", conversionResult.getGbraid())); } else if (!conversionResult.getWbraid().isEmpty()) { clickInfoBuilder.append(String.format("wbraid '%s'", conversionResult.getWbraid())); } else { clickInfoBuilder.append("no click ID"); } System.out.printf("Operation %d for %s succeeded.%n", operationIndex, clickInfoBuilder); } } } } }
C#
public void Run(GoogleAdsClient client, long customerId, long conversionActionId, string gclid, string gbraid, string wbraid, string conversionTime, double conversionValue, ConsentStatus? adUserDataConsent) { // Get the ConversionActionService. ConversionUploadServiceClient conversionUploadService = client.GetService(Services.V23.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", }; // Sets the consent information, if provided. if (adUserDataConsent != null) { // Specifies whether user consent was obtained for the data you are uploading. See // https://www.google.com/about/company/user-consent-policy // for details. clickConversion.Consent = new Consent() { AdUserData = (ConsentStatus)adUserDataConsent }; } // 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 $orderId, string $conversionDateTime, float $conversionValue, ?string $conversionCustomVariableId, ?string $conversionCustomVariableValue, ?int $adUserDataConsent ) { // 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 ])]); } // Sets the consent information, if provided. if (!empty($adUserDataConsent)) { // Specifies whether user consent was obtained for the data you are uploading. See // https://www.google.com/about/company/user-consent-policy for details. $clickConversion->setConsent(new Consent(['ad_user_data' => $adUserDataConsent])); } if (!empty($orderId)) { // Sets the order ID (unique transaction ID), if provided. $clickConversion->setOrderId($orderId); } // Issues a request to upload the click conversion. $conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient(); /** @var UploadClickConversionsResponse $response */ // NOTE: This request contains a single conversion as a demonstration. However, if you have // multiple conversions to upload, it's best to upload multiple conversions per request // instead of sending a separate request per conversion. See the following for per-request // limits: // https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service $response = $conversionUploadServiceClient->uploadClickConversions( // Uploads the click conversion. Partial failure should always be set to true. UploadClickConversionsRequest::build($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: GoogleAdsClient, customer_id: str, conversion_action_id: str, gclid: Optional[str], conversion_date_time: str, conversion_value: str, conversion_custom_variable_id: Optional[str], conversion_custom_variable_value: Optional[str], gbraid: Optional[str], wbraid: Optional[str], order_id: Optional[str], ad_user_data_consent: Optional[str], ) -> None: """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. order_id: The order ID for the click conversion. ad_user_data_consent: The ad user data consent for the click. """ click_conversion: ClickConversion = client.get_type("ClickConversion") conversion_upload_service: ConversionUploadServiceClient = ( client.get_service("ConversionUploadService") ) conversion_action_service: ConversionActionServiceClient = ( 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: CustomVariable = 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) if order_id: click_conversion.order_id = order_id # Sets the consent information, if provided. if ad_user_data_consent: # Specifies whether user consent was obtained for the data you are # uploading. For more details, see: # https://www.google.com/about/company/user-consent-policy click_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[ ad_user_data_consent ] # Uploads the click conversion. Partial failure must be set to True here. # # NOTE: This request only uploads a single conversion, but if you have # multiple conversions to upload, it's most efficient to upload them in a # single request. See the following for per-request limits for reference: # https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service request: UploadClickConversionsRequest = client.get_type( "UploadClickConversionsRequest" ) request.customer_id = customer_id request.conversions.append(click_conversion) request.partial_failure = True conversion_upload_response: UploadClickConversionsResponse = ( conversion_upload_service.upload_click_conversions( request=request, ) ) uploaded_click_conversion: ClickConversionResult = ( 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, ad_user_data_consent) # 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 # Sets the consent information, if provided. unless ad_user_data_consent.nil? cc.consent = client.resource.consent do |c| # Specifies whether user consent was obtained for the data you are # uploading. For more details, see: # https://www.google.com/about/company/user-consent-policy c.ad_user_data = ad_user_data_consent end end end response = client.service.conversion_upload.upload_click_conversions( customer_id: customer_id, # NOTE: This request contains a single conversion as a demonstration. # However, if you have multiple conversions to upload, it's best to upload # multiple conversions per request instead of sending a separate request per # conversion. See the following for per-request limits: # https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service 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, $ad_user_data_consent ) = @_; # 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::V24::Services::ConversionUploadService::ClickConversion ->new({ conversionAction => Google::Ads::GoogleAds::V24::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::V24::Services::ConversionUploadService::CustomVariable ->new({ conversionCustomVariable => Google::Ads::GoogleAds::V24::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. $click_conversion->{orderId} = $order_id; } # Set the consent information, if provided. if ($ad_user_data_consent) { # Specify whether user consent was obtained for the data you are uploading. # See https://www.google.com/about/company/user-consent-policy for details. $click_conversion->{consent} = Google::Ads::GoogleAds::V24::Common::Consent->new({ adUserData => $ad_user_data_consent }); } # Issue a request to upload the click conversion. Partial failure should # always be set to true. # # NOTE: This request contains a single conversion as a demonstration. # However, if you have multiple conversions to upload, it's best to # upload multiple conversions per request instead of sending a separate # request per conversion. See the following for per-request limits: # https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service my $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; }
curl
# This code example uploads a click conversion. # # Variables: # API_VERSION, # CUSTOMER_ID, # DEVELOPER_TOKEN, # MANAGER_CUSTOMER_ID, # OAUTH2_ACCESS_TOKEN: # See https://developers.google.com/google-ads/api/rest/auth#request_headers # for details. # # CONVERSION_ACTION_RESOURCE_NAME: Resource name of the conversion action # associated with this conversion. # GCLID: The Google click ID (gclid) associated with this conversion. # CONVERSION_VALUE: The value of the conversion for the advertiser. # CONVERSION_DATE_TIME: The date time at which the conversion occurred. The # format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", for example, # "2019-01-01 12:32:45-08:00". # CURRENCY_CODE: The currency code of the conversion value. This is the # ISO 4217 3-character currency code. For example: USD, EUR. # CONVERSION_CUSTOM_VARIABLE: The name of the conversion custom variable. # CONVERSION_CUSTOM_VARIABLE_VALUE: The value of the conversion custom # variable. # ORDER_ID: The order ID of the conversion. curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}:uploadClickConversions" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "conversions": [ { "conversionAction": "${CONVERSION_ACTION_RESOURCE_NAME}", "gclid": "${GCLID}", "conversionValue": ${CONVERSION_VALUE}, "conversionDateTime": "${CONVERSION_DATE_TIME}", "currencyCode": "${CURRENCY_CODE}", "customVariables": [ { "conversionCustomVariable": "${CONVERSION_CUSTOM_VARIABLE}", "value": "${CONVERSION_CUSTOM_VARIABLE_VALUE}" } ], "orderId": "${ORDER_ID}", "consent": { "adUserData": "GRANTED" } } ], "partialFailure": true } EOF
トラブルシューティング
オフライン データ診断では、アップロードの全体的な健全性を継続的に確認するための
単一のリソースが提供されます。ただし、実装中に、この
セクションの情報を使用して、レスポンスの
partial_failure_error
フィールドで報告されたエラーを調査できます。
コンバージョン アクションのアップロード時に発生する最も一般的なエラーには、USER_PERMISSION_DENIED などの認証エラーがあります。リクエストの顧客 ID が、コンバージョン アクションを所有する Google 広告のコンバージョン顧客に設定されていることを再確認してください。詳しくは、
認証ガイドをご覧ください。また、さまざまなエラーのデバッグ方法については、
一般的なエラーに関するガイドをご覧ください。
一般的なエラーをデバッグする
| エラー | |
|---|---|
INVALID_CONVERSION_ACTION_TYPE
|
指定されたコンバージョン アクションの
タイプ
は、クリック コンバージョンのアップロードには無効です。アップロード リクエストで指定された ConversionAction
のタイプが UPLOAD_CLICKS であることを確認してください。
|
NO_CONVERSION_ACTION_FOUND
|
指定されたコンバージョン アクションが有効になっていないか、アップロードする customer_id 内で見つかりません
。コンバージョンの設定に関する情報を取得して
アップロードのコンバージョン アクションが有効になっており、アップロード リクエストの
customer_id によって所有されていることを確認します。
|
TOO_RECENT_CONVERSION_ACTION
|
コンバージョン アクションが新しく作成されました。アクションの作成後、少なくとも 6 時間待ってから、失敗したコンバージョンを再試行してください。 |
INVALID_CUSTOMER_FOR_CLICK
|
リクエストの customer_id は、クリック時に Google Ads API のコンバージョン アカウント
であった顧客 ID
と同じではありません。リクエストの customer_id を正しい顧客に更新します。 |
EVENT_NOT_FOUND
|
Google 広告でクリック ID と
customer_id の組み合わせが見つかりません。の要件を確認し、customer_id正しい Google 広告アカウントを使用してアップロードしていることを確認します。 |
DUPLICATE_CLICK_CONVERSION_IN_REQUEST
|
リクエスト内の複数のコンバージョンで、クリック ID、conversion_date_time
、conversion_action の組み合わせが同じです。リクエストから重複するコンバージョンを削除します。
|
CLICK_CONVERSION_ALREADY_EXISTS
|
クリック ID、
conversion_date_time、および conversion_action の組み合わせが同じコンバージョンが以前にアップロードされています。アップロードを再試行していて、この
コンバージョンが以前に成功した場合は、このエラーを無視してください。以前にアップロードしたコンバージョンに加えて別のコンバージョンを追加する場合は、以前にアップロードしたコンバージョンが重複しないように、conversion_date_time の ClickConversion を調整します。 |
EVENT_NOT_FOUND
|
Google 広告でクリック ID と
customer_id の組み合わせが見つかりません。の要件を確認し、customer_id正しい Google 広告アカウントを使用してアップロードしていることを確認します。 |
EXPIRED_EVENT
|
インポートされたクリックは、
click_through_lookback_window_days フィールドで指定された期間より前に発生しました。A
click_through_lookback_window_days の変更は、変更後に記録されたクリックにのみ影響するため、ルックバック ウィンドウを変更しても、特定のクリックでこのエラーは解決されません。必要に応じて、
conversion_action をルックバック
ウィンドウが長い別のアクションに変更します。 |
CONVERSION_PRECEDES_EVENT
|
conversion_date_time がクリックの日時より前です。conversion_date_time を後の値に更新します。
|
GBRAID_WBRAID_BOTH_SET
|
ClickConversion に
gbraid と wbraid の両方の値が設定されています。コンバージョンを更新して、
1 つのクリック ID または URL パラメータのみを使用するようにします。また、複数のクリックを同じコンバージョンに結合していないことを確認します。各クリックには、クリック ID
または URL パラメータが 1 つだけあります。
|
VALUE_MUST_BE_UNSET
|
location の
GoogleAdsError を確認して、次のどの問題がエラーの原因となったかを特定します。
|
レポートのコンバージョン
アップロードされたコンバージョンは、アップロード リクエストの日付や conversion_date_time の ClickConversionの日付ではなく、元のクリックの表示回数の日付のレポートに反映されます。
インポートされたコンバージョン データがラストクリック アトリビューションの Google 広告アカウントに表示されるまで、最大で 3 時間かかります。他の検索アトリビューション モデルの場合、3 時間以上かかることがあります。詳しくは、データの更新速度 に関するガイドをご覧ください。