Вы можете использовать API Google Ads для загрузки данных о конверсиях по кликам в офлайн-режиме в Google Ads, чтобы отслеживать объявления, которые привели к продажам в офлайн-среде, например, по телефону или через торгового представителя.
Настраивать
Для корректной работы функции конвертации в офлайн-режиме необходимо выполнить несколько предварительных условий. Убедитесь, что все предварительные условия выполнены, прежде чем приступать к внедрению:
Включите отслеживание конверсий в вашем приложении Google Ads для отслеживания конверсий.
Настройте теги и сохраните идентификаторы кликов.
1. Включите отслеживание конверсий в вашем приложении Google Ads для отслеживания конверсий.
Если вы прошли руководство по началу работы с отслеживанием конверсий и включили его, можете перейти ко второму шагу: настройка тегов .
Получите информацию о настройках отслеживания конверсий.
Вы можете проверить настройки отслеживания конверсий в своем аккаунте и убедиться, что отслеживание конверсий включено, запросив ресурс 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 Ads, который создает и управляет конверсиями для этого клиента. Для клиентов, использующих отслеживание конверсий между аккаунтами , это идентификатор аккаунта менеджера. Идентификатор клиента конверсии Google Ads следует указывать в качестве customer_id в запросах Google Ads API для создания и управления конверсиями. Обратите внимание, что это поле заполняется, даже если отслеживание конверсий не включено.
Поле conversion_tracking_status указывает, включено ли отслеживание конверсий и используется ли в учетной записи отслеживание конверсий между учетными записями.
Создайте действие конверсии для клиента конверсии Google Ads.
Если значение conversion_tracking_status равно NOT_CONVERSION_TRACKED , отслеживание конверсий для аккаунта не включено. Чтобы включить отслеживание конверсий, создайте хотя бы одно ConversionAction в аккаунте Google Ads, отвечающем за конверсии, как показано в следующем примере. В качестве альтернативы, вы можете создать действие конверсии в пользовательском интерфейсе, следуя инструкциям в Справочном центре для типа конверсии, который вы хотите включить.
Обратите внимание, что улучшенные показатели конверсии включаются автоматически при отправке через API Google Ads, но их можно отключить через пользовательский интерфейс 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.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}".' )
Руби
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::V23::Resources::ConversionAction->new({ name => $conversion_action_name, category => DEFAULT, type => WEBPAGE, status => ENABLED, viewThroughLookbackWindowDays => 15, valueSettings => Google::Ads::GoogleAds::V23::Resources::ValueSettings->new({ defaultValue => 23.41, alwaysUseDefaultValue => "true" })}); # Create a conversion action operation. my $conversion_action_operation = Google::Ads::GoogleAds::V23::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 см. в разделе «Создание действий конверсии» .
Получить существующее действие конверсии
Вы можете получить подробную информацию о существующем действии конверсии, выполнив следующий запрос. Убедитесь, что идентификатор клиента в запросе соответствует клиенту 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. Настройте теги и сохраните идентификаторы кликов.
Следуйте инструкциям , чтобы подтвердить включение автоматической разметки. Настройте свой аккаунт Google Ads, веб-сайт и систему отслеживания лидов для сбора и хранения GCLID для каждого показа, а также параметров URL GBRAID или WBRAID для ваших объявлений. Автоматическая разметка включена по умолчанию для новых аккаунтов.
Составьте запрос
Следуйте этим инструкциям, чтобы создать запрос UploadClickConversionsRequest и присвоить его полям соответствующие значения.
-
customer_id Указывает на аккаунт Google Ads, в который вы загружаете контент. Установите это значение на клиента Google Ads, осуществляющего конверсию в аккаунте, который является источником кликов.
-
job_id Предоставляет механизм для сопоставления ваших запросов на загрузку с информацией по каждому заданию в диагностике данных в автономном режиме .
Если вы не зададите это поле, API Google Ads присвоит каждому запросу уникальное значение в диапазоне
[2^31, 2^63). Если вы предпочитаете объединять несколько запросов в одно логическое задание, установите для этого поля одинаковое значение в диапазоне[0, 2^31)для каждого запроса в вашем задании.В ответе поле
job_idсодержит идентификатор задания для запроса, независимо от того, указали ли вы значение или позволили API Google Ads присвоить его автоматически.-
partial_failure_enabled Определяет, как API Google Ads обрабатывает ошибки, возникающие в ходе операций.
Это поле должно быть установлено в
true. При обработке ответа следуйте рекомендациям по обработке частичных сбоев .-
debug_enabled Определяет поведение системы обработки ошибок для повышения конверсии при загрузке лидов . API Google Ads игнорирует это поле при обработке загрузок для конверсий по кликам с использованием параметров URL
gclid,gbraidилиwbraid.
Создание операций по конверсии кликов
Коллекция объектов ClickConversion в вашем UploadClickConversionRequest определяет набор конверсий, которые вы хотите загрузить. Следуйте этим инструкциям, чтобы создать каждый объект ClickConversion и установить для его полей соответствующие значения.
Укажите обязательные поля для каждой операции преобразования.
Следуйте этим инструкциям, чтобы задать необходимые значения для полей ClickConversion .
-
gclid,gbraid,wbraid Параметры GCLID или URL, которые вы получаете, когда пользователь попадает на ваш веб-сайт или в приложение после клика по рекламе. Требуется один из следующих параметров:
-
gclid -
gbraid -
wbraid
-
-
conversion_date_time Дата и время конвертации.
Значение должно содержать указание часового пояса, а формат должен быть следующим:
yyyy-mm-dd HH:mm:ss+|-HH:mm, например:2022-01-01 19:32:45-05:00(без учета летнего времени).В качестве часового пояса можно использовать любое допустимое значение: оно не обязательно должно совпадать с часовым поясом аккаунта. Однако, если вы планируете сравнивать загруженные данные о конверсиях с данными в пользовательском интерфейсе Google Ads, мы рекомендуем использовать тот же часовой пояс, что и ваш аккаунт Google Ads, чтобы количество конверсий совпадало. Более подробную информацию и примеры можно найти в Справочном центре , а список допустимых идентификаторов часовых поясов см. в разделе «Коды и форматы» .
-
user_identifiers Не задавайте этот параметр при загрузке данных о конверсиях, используя только идентификаторы кликов. Если этот параметр задан, Google Ads будет рассматривать операцию загрузки как загрузку данных для повышения конверсии лидов .
-
conversion_action Имя ресурса
ConversionActionдля конверсии по клику.Действие конверсии должно иметь
typeUPLOAD_CLICKSи должно существовать в клиенте конверсии Google Ads в аккаунте Google Ads, связанном с кликом.-
conversion_value Значение конверсии.
-
currency_code Код валюты для
conversion_value.
Задайте необязательные поля для каждой операции преобразования.
Ознакомьтесь со следующим списком необязательных полей и установите их в ClickConversion по мере необходимости.
-
order_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: Идентификатор соответствующей учетной записи Merchant Center . -
feed_country_code: Двухсимвольный региональный код ISO 3166 для фида Merchant Center. -
feed_language_code: Код языка ISO 639-1 для фида Merchant Center. -
local_transaction_cost: Сумма всех скидок на уровне транзакций вcurrency_codeClickConversion. items: Товары в корзине покупок.Каждый элемент в
itemsсостоит из следующих атрибутов:product_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}"' )
Руби
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::V23::Services::ConversionUploadService::ClickConversion ->new({ conversionAction => Google::Ads::GoogleAds::V23::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::V23::Services::ConversionUploadService::CustomVariable ->new({ conversionCustomVariable => Google::Ads::GoogleAds::V23::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::V23::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; }
локон
# 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 . Убедитесь, что в вашем запросе указан идентификатор клиента, которому принадлежит действие по конверсии в Google Ads. Более подробную информацию можно найти в нашем руководстве по авторизации , а советы по устранению этих ошибок — в руководстве по распространенным ошибкам.
Отладка распространенных ошибок
| Ошибка | |
|---|---|
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 для конверсий на момент клика. Обновите customer_id в запросе, указав правильный идентификатор клиента. |
EVENT_NOT_FOUND | Google Ads не может найти комбинацию идентификатора клика (click ID) и customer_id . Проверьте требования к customer_id и убедитесь, что вы загружаете данные, используя правильный аккаунт Google Ads. |
DUPLICATE_CLICK_CONVERSION_IN_REQUEST | В запросе содержится несколько конверсий с одинаковой комбинацией идентификатора клика, conversion_date_time , а также conversion_action . Удалите повторяющиеся конверсии из запроса. |
CLICK_CONVERSION_ALREADY_EXISTS | Ранее уже была загружена конверсия с той же комбинацией идентификатора клика, conversion_date_time и conversion_action . Игнорируйте эту ошибку, если вы пытались загрузить конверсию повторно, и она ранее была успешно загружена. Если вы хотите добавить еще одну конверсию в дополнение к ранее загруженной, измените conversion_date_time для ClickConversion , чтобы избежать дублирования ранее загруженной конверсии. |
EVENT_NOT_FOUND | Google Ads не может найти комбинацию идентификатора клика (click ID) и customer_id . Проверьте требования к customer_id и убедитесь, что вы загружаете данные, используя правильный аккаунт Google Ads. |
EXPIRED_EVENT | Импортированный клик произошел до истечения временного интервала, указанного в поле click_through_lookback_window_days . Изменение значения click_through_lookback_window_days влияет только на клики, зарегистрированные после изменения , поэтому изменение временного интервала не устранит ошибку для данного конкретного клика. При необходимости измените conversion_action на другое действие с более длительным временным интервалом. |
CONVERSION_PRECEDES_EVENT | Параметр conversion_date_time указывает дату и время, предшествующие дате и времени клика. Обновите значение conversion_date_time на более позднее. |
GBRAID_WBRAID_BOTH_SET | Параметр ClickConversion имеет значение, заданное как для gbraid , так и wbraid . Обновите параметр конверсии, чтобы использовать только один идентификатор клика или параметр URL, и убедитесь, что вы не объединяете несколько кликов в одну конверсию. Каждый клик имеет только один идентификатор клика или параметр URL. |
VALUE_MUST_BE_UNSET | Проверьте location ошибки GoogleAdsError , чтобы определить, какая из следующих проблем привела к ошибке.
|
Конверсии в отчетах
В отчетах отражены данные о конверсиях, полученные после загрузки, за дату показа исходного клика , а не за дату запроса на загрузку или дату/время конверсии ( conversion_date_time ) клика ClickConversion ).
Для отображения импортированных статистических данных о конверсиях в вашем аккаунте Google Ads по методу «последний клик» может потребоваться до 3 часов. Для других моделей атрибуции поисковых запросов это может занять больше 3 часов. Для получения дополнительной информации обратитесь к руководству по актуальности данных .