您可以使用 Google Ads API 上傳離線點擊 轉換匯入 Google Ads 想要追蹤在現實世界中帶來銷售的廣告,例如 請透過電話或與業務代表聯絡。
設定
要設定有效的離線轉換,必須符合幾項先決條件。請確認 滿足所有必要條件,才能繼續實作程序:
在 Google Ads 轉換客戶中啟用轉換追蹤功能。
設定代碼並儲存點擊 ID。
1. 在 Google Ads 轉換顧客中啟用轉換追蹤
如果您已完成轉換 指南並啟用轉換追蹤 請跳至步驟 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
」欄位代表
為這位客戶建立及管理轉換。如果客戶使用
跨帳戶轉換追蹤,
這是指管理員帳戶的 ID。Google Ads 轉換客戶 ID 應為
在 Google Ads API 要求中以 customer_id
的形式提供,以建立及管理轉換。
請注意,即使您未啟用轉換追蹤,系統仍會在這個欄位填入資料。
conversion_tracking_status
敬上
欄位會指出轉換追蹤是否已啟用,以及帳戶是否已啟用
使用的是跨帳戶轉換追蹤。
在 Google Ads 轉換顧客下方建立轉換動作
如果 conversion_tracking_status
值為 NOT_CONVERSION_TRACKED
,
此帳戶未啟用轉換追蹤。啟用轉換追蹤
方法是在以下位置建立至少一個 ConversionAction
:
Google Ads 轉換帳戶,如下例所示。或者,您也可以
可以按照
說明中心
您想啟用的轉換類型
請注意,透過 Google Ads API,但可以透過 Google Ads 使用者介面停用。
程式碼範例
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}".' )
小茹
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 Ads
轉換動作類型,且已設定轉換動作類型
正確的
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 Ads 帳戶、網站和 待開發客戶追蹤系統,以擷取並儲存每個 Google 點擊 ID、GBRAID 或 WBRAID 曝光次數和點擊次數。系統預設會為新的 帳戶。
建立要求
請按照以下指引建立
UploadClickConversionsRequest
敬上
並將欄位設為適當的值
customer_id
指明您上傳的 Google Ads 帳戶。將此設為 Google Ads 轉換客戶 也就是點擊次數的來源帳戶。
job_id
提供將上傳要求與每項工作建立關聯的機制 資訊 離線資料診斷。
如果沒有設定這個欄位,Google Ads API 會為每項請求指定專屬的值。 範圍內:
[2^31, 2^63)
。如果希望將多項請求歸入同一個群組 為單一邏輯工作,請將這個欄位設為[0, 2^31)
。回應中的
job_id
包含要求的工作 ID,無論您是否已指定 值,或讓 Google Ads API 指定值。partial_failure_enabled
決定 Google Ads API 如何處理作業錯誤。
這個欄位必須設為
true
。依部分失敗做法操作 指南 回應。debug_enabled
決定強化轉換功能的錯誤報表行為 待開發客戶上傳資料。 Google Ads API 在使用以下方式處理點擊轉換的上傳時,會忽略這個欄位
gclid
、gbraid
或wbraid
。
建立點擊轉換作業
集合中的 ClickConversion
物件
UploadClickConversionRequest
會定義您想要的轉換組合
上傳。請按照以下指引建構各個 ClickConversion
並進行設定
欄位傳回適當的值
設定每項轉換動作的必填欄位
請按照以下操作說明設定「ClickConversion
」的必填欄位
傳回適當的值
gclid
、gbraid
、wbraid
- 點擊轉換時擷取的 ID 點擊或曝光請只設定上述其中「一個」欄位。
conversion_date_time
轉換的日期和時間。
值必須指定時區,且格式必須
yyyy-mm-dd HH:mm:ss+|-HH:mm
,例如:2022-01-01 19:32:45-05:00
(忽略日光節約時間) ,直接在 Google Cloud 控制台實際操作。時區可以包含任何有效值,但「不必」與 帳戶的時區不過,如果想比較 建議您以 Google Ads 使用者介面中的轉換資料為依據 時區做為 Google Ads 帳戶,如此轉換次數才會一致。 如需更多詳細資訊及範例,請前往 Help 中央,並查看 Google 行動應用程式的程式碼與格式 有效時區編號清單。
user_identifiers
上傳轉換時,僅使用點擊 ID 時,請勿設定這個欄位。如果這是 欄位設定後,Google Ads 會將上傳作業視為加強型 待開發客戶轉換。
conversion_action
ConversionAction
的資源名稱轉換動作的
type
必須是UPLOAD_CLICKS
,且必須存在 (與 Google Ads 帳戶相連結的 Google Ads 帳戶 點擊。conversion_value
轉換的價值。
currency_code
conversion_value
的貨幣代碼。
設定各項轉換動作的選填欄位
請查看下方的選填欄位清單,並在 ClickConversion
上設定這些欄位
將物件的使用中版本還原為舊版
或依需要永久刪除封存版本
order_id
- 轉換的交易 ID。這是選填欄位,但非常強烈 建議如果您是在上傳期間設定該檔案,您「必須」用於任何 調整項。
external_attribution_data
如果使用第三方工具或自家解決方案追蹤轉換,請 您可以只將轉換功勞的部分歸給 Google Ads,或者 您可能想要將轉換功勞分配給多次點擊。 外部歸因轉換 匯入作業 將功勞分配給每次點擊
如要上傳小額抵免額,請將這個欄位設為
ExternalAttributionData
物件 值為external_attribution_model
和external_attribution_credit
。custom_variables
自訂轉換變數的值。
Google Ads 不支援將自訂轉換變數與
wbraid
或gbraid
。cart_data
您可以將購物車資訊加到「
ClickConversion
」的cart_data
欄位,其中包含 以下屬性:merchant_id
:相關聯的 ID Merchant Center 帳戶。feed_country_code
:商家的 ISO 3166 雙字元區碼 並放在動態饋給中央。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
用於表示記錄這項轉換的環境。例如:App 或網頁。
程式碼範例
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}"' )
小茹
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 Ads 轉換客戶
追蹤轉換動作請造訪我們的
授權指南,詳情請參閱
參閱常見錯誤指南,瞭解一般錯誤做法
以便針對這些不同錯誤進行偵錯
常見錯誤偵錯
錯誤 | |
---|---|
ConversionUploadError.INVALID_CONVERSION_ACTION_TYPE
|
指定的轉換動作類型無效,因此無法上傳
點擊轉換。請確定所指定的 ConversionAction
您的上傳要求類型為 UPLOAD_CLICKS 。
|
ConversionUploadError.NO_CONVERSION_ACTION_FOUND
|
指定的轉換動作未啟用或找不到
上傳 customer_id 中的檔案。確認轉換動作
已啟用,且屬於customer_id
上傳要求。
|
ConversionUploadError.TOO_RECENT_CONVERSION_ACTION
|
轉換動作為新建立的,在 系統會先建立動作,再重試失敗的轉換。 |
ConversionUploadError.INVALID_CUSTOMER_FOR_CLICK
|
要求的 customer_id 與客戶 ID 不同
也就是 Google Ads 轉換
客戶。更新以下項目的 customer_id :
將要求提供給正確的客戶。
|
ConversionUploadError.EVENT_NOT_FOUND
|
Google Ads 找不到點擊 ID 和
customer_id 。詳閱 customer_id 的規定和
確認你使用正確的 Google Ads 帳戶進行上傳。
|
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
|
Google Ads 找不到點擊 ID 和
customer_id 。詳閱 customer_id 的規定和
確認你使用正確的 Google Ads 帳戶進行上傳。
|
ConversionUploadError.EXPIRED_EVENT
|
匯入的點擊發生在
「click_through_lookback_window_days 」欄位。A 罩杯
變更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 。將轉換更新為「僅限使用」
一個點擊 ID,並確認您並未將多次點擊合併為同一個點擊 ID
轉換率每次點擊都只有一個點擊 ID。
|
FieldError.VALUE_MUST_BE_UNSET
|
請檢查 location
GoogleAdsError ,判斷以下哪些問題導致
錯誤。
|
報表中的轉換
報表中會列出曝光日期
原始點擊,而不是上傳要求的日期或日期
第 conversion_date_time
個
ClickConversion
。
這項作業最多需要 3 小時 匯入的轉換統計資料會顯示在 Google Ads 帳戶中,以便獲得最終點擊 出處。如果是其他搜尋歸因模式,的處理時間會超過 3 所以客戶只會在 TAM 當地的服務時間獲得回應諮詢資料更新間隔 指南。