Google Ads API を使ってオフライン クリック コンバージョンを Google 広告にアップロードすることで、電話や営業担当者を通じたオフライン販売につながった広告をトラッキングできます。
設定
オフライン コンバージョンを設定するには、いくつかの前提条件があります。実装に進む前に、すべての前提条件を満たしていることを確認してください。
Google 広告のコンバージョンの顧客でコンバージョン トラッキングを有効にします。
タグ設定を構成し、クリック ID を保存する。
1. Google 広告コンバージョンの顧客のコンバージョン トラッキングを有効にする
コンバージョンのスタートガイドを完了し、コンバージョン トラッキングを有効にしている場合は、ステップ 2: タグ設定を行うに進んでください。
コンバージョン トラッキングの設定に関する情報を取得する
ConversionTrackingSetting
の Customer
リソースをクエリすると、アカウントのコンバージョン トラッキング設定をチェックし、コンバージョン トラッキングが有効になっているかどうかを確認できます。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
として指定する必要があります。このフィールドは、コンバージョン トラッキングが有効になっていない場合でも入力されます。
conversion_tracking_status
フィールドは、コンバージョン トラッキングが有効かどうか、アカウントでクロスアカウント コンバージョン トラッキングを使用しているかどうかを示します。
Google 広告のコンバージョン ユーザーにコンバージョン アクションを作成する
conversion_tracking_status
の値が NOT_CONVERSION_TRACKED
の場合、アカウントでコンバージョン トラッキングは有効になっていません。コンバージョン トラッキングを有効にするには、次の例に示すように、Google 広告コンバージョン アカウントで ConversionAction
を少なくとも 1 つ作成します。または、有効にするコンバージョンの種類に応じたヘルプセンターの手順に沿って、管理画面でコンバージョン アクションを作成することもできます。
拡張コンバージョンは Google Ads API を使って送信すると自動的に有効になりますが、Google 広告の管理画面から無効にすることもできます。
サンプルコード
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.V17.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, customer_id): conversion_action_service = client.get_service("ConversionActionService") # Create the operation. conversion_action_operation = client.get_type("ConversionActionOperation") # Create conversion action. conversion_action = 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 = conversion_action.value_settings value_settings.default_value = 15.0 value_settings.always_use_default_value = True # Add the conversion action. conversion_action_response = ( 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::V17::Resources::ConversionAction->new({ name => $conversion_action_name, category => DEFAULT, type => WEBPAGE, status => ENABLED, viewThroughLookbackWindowDays => 15, valueSettings => Google::Ads::GoogleAds::V17::Resources::ValueSettings->new({ defaultValue => 23.41, alwaysUseDefaultValue => "true" })}); # Create a conversion action operation. my $conversion_action_operation = Google::Ads::GoogleAds::V17::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; }
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 の設定
instructionsに沿って自動タグ設定が有効になっていることを確認し、Google 広告アカウント、ウェブサイト、見込み顧客トラッキング システムを設定して、広告に対する各インプレッションとクリックの GCLID、GBRAID、または WBRAID をキャプチャして保存してください。自動タグ設定は、アカウントを新規に作成するとデフォルトで有効になります。
リクエストを作成する
以下のガイダンスに沿って UploadClickConversionsRequest
を作成し、各フィールドに適切な値を設定します。
customer_id
アップロードの Google 広告アカウントを識別します。クリックの発生元であるアカウントの Google 広告コンバージョン客に設定します。
job_id
オフライン データ診断のジョブごとの情報にアップロード リクエストを関連付けるメカニズムを提供します。
このフィールドを設定しない場合、Google Ads API により、各リクエストに
[2^31, 2^63)
の範囲内で一意の値が割り当てられます。複数のリクエストを 1 つの論理ジョブにグループ化する場合は、ジョブのすべてのリクエストでこのフィールドを[0, 2^31)
の範囲内の同じ値に設定します。レスポンスの
job_id
にはリクエストのジョブ ID が含まれます。値を指定したか、Google Ads API に値を割り当てたかは関係ありません。partial_failure_enabled
Google Ads API でオペレーションのエラーを処理する方法を指定します。
このフィールドは
true
に設定する必要があります。レスポンスを処理する際は、部分障害に関するガイドラインに従ってください。debug_enabled
リードの拡張コンバージョンのアップロードのエラーレポート動作を指定します。
gclid
、gbraid
、wbraid
を使ってクリック コンバージョンのアップロードを処理する場合、Google Ads API はこのフィールドを無視します。
クリック コンバージョン オペレーションを作成する
UploadClickConversionRequest
内の ClickConversion
オブジェクトのコレクションにより、アップロードする一連のコンバージョンが定義されます。以下のガイダンスに沿って、各 ClickConversion
を作成し、各フィールドに適切な値を設定します。
各コンバージョン オペレーションの必須フィールドを設定する
以下の手順に沿って、ClickConversion
の必須フィールドに適切な値を設定します。
gclid
、gbraid
、wbraid
- コンバージョンのクリックまたはインプレッションのクリック時に取得された識別子。これらのフィールドのうち 1 つのみを設定します。
conversion_date_time
コンバージョンが発生した日時。
値にはタイムゾーンを指定し、形式は
yyyy-mm-dd HH:mm:ss+|-HH:mm
にする必要があります(例:2022-01-01 19:32:45-05:00
(夏時間なし))。タイムゾーンには、任意の有効な値を指定できます。アカウントのタイムゾーンと一致する必要はありません。ただし、アップロードしたコンバージョン データを Google 広告管理画面のデータと比較する場合は、コンバージョン数を一致させるために、Google 広告アカウントと同じタイムゾーンを使用することをおすすめします。詳細と例については、ヘルプセンターをご覧ください。有効なタイムゾーン ID のリストについては、コードと形式をご覧ください。
user_identifiers
クリック ID のみを使用してコンバージョンをアップロードする場合は、このフィールドを設定しないでください。このフィールドを設定すると、アップロード操作はリードの拡張コンバージョンのアップロードとして扱われます。
conversion_action
クリック コンバージョンの
ConversionAction
のリソース名。コンバージョン アクションの
type
は「UPLOAD_CLICKS
」で、クリックに関連付けられた Google 広告アカウントの Google 広告コンバージョン ユーザーに存在している必要があります。conversion_value
コンバージョン値。
currency_code
conversion_value
の通貨コード。
各コンバージョン オペレーションのオプション フィールドを設定する
以下のオプション フィールドのリストを確認し、必要に応じて ClickConversion
で設定します。
order_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.V17.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, customer_id, conversion_action_id, gclid, conversion_date_time, conversion_value, conversion_custom_variable_id, conversion_custom_variable_value, gbraid, wbraid, order_id, ad_user_data_consent, ): """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 = 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) 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 = 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, 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::V17::Services::ConversionUploadService::ClickConversion ->new({ conversionAction => Google::Ads::GoogleAds::V17::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::V17::Services::ConversionUploadService::CustomVariable ->new({ conversionCustomVariable => Google::Ads::GoogleAds::V17::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::V17::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; }
トラブルシューティング
オフライン データ診断では、アップロードの全体的な健全性を継続的に確認するための単一のリソースが提供されます。ただし、実装中にこのセクションの情報を使用して、レスポンスの partial_failure_error
フィールドで報告されたエラーを調査できます。
コンバージョン アクションをアップロードする際に最もよくあるエラーは、USER_PERMISSION_DENIED
などの承認エラーです。リクエストのお客様 ID が、そのコンバージョン アクションを所有する Google 広告コンバージョンの顧客に設定されていることを再度確認してください。詳しくは認証ガイドをご覧ください。また、さまざまなエラーのデバッグ方法のヒントについては、一般的なエラーのガイドをご覧ください。
一般的なエラーをデバッグする
エラー | |
---|---|
ConversionUploadError.INVALID_CONVERSION_ACTION_TYPE
|
指定されたコンバージョン アクションのタイプは、クリック コンバージョンのアップロードに使用できません。アップロード リクエストで指定された ConversionAction のタイプが UPLOAD_CLICKS であることを確認してください。 |
ConversionUploadError.NO_CONVERSION_ACTION_FOUND
|
指定されたコンバージョン アクションが有効になっていないか、アップロード中のcustomer_id 内に見つかりません。アップロード内のコンバージョン アクションが有効になっていて、アップロード リクエストの customer_id によって所有されていることを確認してください。
|
ConversionUploadError.TOO_RECENT_CONVERSION_ACTION
|
コンバージョン アクションが新たに作成された場合。アクションの作成後 6 時間以上経過してから、失敗したコンバージョンを再試行してください。 |
ConversionUploadError.INVALID_CUSTOMER_FOR_CLICK
|
リクエストの customer_id のお客様 ID が、クリック時に Google 広告コンバージョンのお客様だったお客様 ID と一致しません。リクエストの customer_id を適切なお客様に更新します。 |
ConversionUploadError.EVENT_NOT_FOUND
|
クリック ID と customer_id の組み合わせは検出できません。customer_id の要件を確認し、正しい Google 広告アカウントを使用してアップロードしていることを確認してください。
|
ConversionUploadError.DUPLICATE_CLICK_CONVERSION_IN_REQUEST
|
リクエスト内の複数のコンバージョンで、クリック ID、conversion_date_time 、conversion_action の組み合わせが同じです。重複するコンバージョンをリクエストから削除してください。
|
ConversionUploadError.CLICK_CONVERSION_ALREADY_EXISTS
|
クリック ID、conversion_date_time 、conversion_action の組み合わせと同じコンバージョンが以前にアップロードされています。アップロードを再試行していて、以前にこの変換が成功している場合は、このエラーを無視してください。以前にアップロードしたコンバージョンに加えて別のコンバージョンを追加する場合は、以前にアップロードしたコンバージョンが重複しないように、ClickConversion の conversion_date_time を調整します。 |
ConversionUploadError.EVENT_NOT_FOUND
|
クリック ID と customer_id の組み合わせは検出できません。customer_id の要件を確認し、正しい Google 広告アカウントを使用してアップロードしていることを確認してください。
|
ConversionUploadError.EXPIRED_EVENT
|
インポートされたクリックが、click_through_lookback_window_days フィールドで指定された期間より前に発生しています。click_through_lookback_window_days を変更すると、変更後に記録されたクリックにのみ影響するため、ルックバック ウィンドウを変更しても、そのクリックのエラーは解決されません。必要に応じて、conversion_action をルックバック ウィンドウの長いアクションに変更します。 |
ConversionUploadError.CONVERSION_PRECEDES_GCLID
|
conversion_date_time がクリックの日時よりも前である。conversion_date_time を後の値に更新します。 |
ConversionUploadError.GBRAID_WBRAID_BOTH_SET
|
ClickConversion は gbraid と wbraid の両方に設定された値を持ちます。コンバージョンを更新して、1 つのクリック ID のみが使用されるようにします。また、複数のクリックが 1 つのコンバージョンに結合されないようにします。各クリックにはクリック ID が 1 つしか割り当てられません。
|
FieldError.VALUE_MUST_BE_UNSET
|
GoogleAdsError の location を確認して、次のどの問題がエラーにつながったかを判断します。
|
レポート内のコンバージョン
アップロードされたコンバージョンは、アップロード リクエストの日付や ClickConversion
の conversion_date_time
の日付ではなく、元のクリックのインプレッション日のレポートに反映されます。
インポートしたコンバージョンのデータは、ラストクリック アトリビューションについては Google 広告アカウントに表示されるまで最大 3 時間かかります。他の検索アトリビューション モデルでは、3 時間以上かかることがあります。詳しくは、データの更新頻度に関するガイドをご覧ください。