Carica conversioni dei clic

Puoi utilizzare l'API Google Ads per caricare le conversioni da clic offline in Google Ads per monitorare gli annunci che hanno generato vendite nel mondo offline, ad esempio per telefono o tramite un rappresentante di vendita.

Configurazione

Esistono alcuni prerequisiti per una configurazione delle conversioni offline funzionante. Prima di procedere all'implementazione, assicurati che tutti i prerequisiti siano soddisfatti:

  1. Attiva il monitoraggio delle conversioni nel cliente di conversione Google Ads.

  2. Configura il tagging e memorizza gli ID clic.

1. Attivare il monitoraggio delle conversioni nel cliente di conversione Google Ads

Se hai completato la guida introduttiva alle conversioni e hai attivato il monitoraggio delle conversioni, puoi andare al passaggio 2: configura il tagging.

Recuperare informazioni sulla configurazione del monitoraggio delle conversioni

Puoi controllare la configurazione del monitoraggio delle conversioni del tuo account e verificare che sia abilitato eseguendo una query sulla risorsa Customer per ConversionTrackingSetting. Esegui la seguente query con 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

Il campo google_ads_conversion_customer indica l'account Google Ads che crea e gestisce le conversioni per questo cliente. Per i clienti che utilizzano il monitoraggio delle conversioni su più account, si tratta dell'ID di un account amministratore. L'ID cliente di conversione di Google Ads deve essere fornito come customer_id nelle richieste dell'API Google Ads per creare e gestire le conversioni. Tieni presente che questo campo viene compilato anche se il monitoraggio delle conversioni non è attivato.

Il campo conversion_tracking_status indica se il monitoraggio delle conversioni è attivato e se l'account utilizza il monitoraggio delle conversioni su più account.

Crea un'azione di conversione nel cliente di conversione Google Ads

Se il valore conversion_tracking_status è NOT_CONVERSION_TRACKED, il monitoraggio delle conversioni non è attivo per l'account. Attiva il monitoraggio delle conversioni creando almeno un ConversionAction nell'account conversione Google Ads, come nell'esempio seguente. In alternativa, puoi creare un'azione di conversione nell'interfaccia utente seguendo le istruzioni riportate nel Centro assistenza per il tipo di conversione che vuoi attivare.

Tieni presente che le conversioni avanzate vengono attivate automaticamente quando vengono inviate tramite l'API Google Ads, ma possono essere disattivate tramite l'interfaccia utente di Google Ads.

Esempio di codice

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());
    }
  }
}
AddConversionAction.java

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V18.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;
    }
}
AddConversionAction.cs

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
        );
    }
}
AddConversionAction.php

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}".'
    )
add_conversion_action.py

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
add_conversion_action.rb

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::V18::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V18::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V18::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;
}
add_conversion_action.pl

Assicurati che conversion_action_type sia impostato sul valore corretto ConversionActionType. Per ulteriori indicazioni sulla creazione di azioni di conversione nell'API Google Ads, consulta Creare azioni di conversione.

Recuperare un'azione di conversione esistente

Puoi recuperare i dettagli di un'azione di conversione esistente emettendo la seguente query. Assicurati che l'ID cliente nella richiesta sia impostato sul cliente di conversione Google Ads che hai identificato sopra e che il tipo di azione di conversione sia impostato sul valore ConversionActionType corretto.

SELECT
  conversion_action.resource_name,
  conversion_action.name,
  conversion_action.status
FROM conversion_action
WHERE conversion_action.type = 'INSERT_CONVERSION_ACTION_TYPE'

2. Configurare la codifica e memorizzare gli ID clic

Segui le istruzioni per verificare che il tagging automatico sia attivo. Configura l'account Google Ads, il sito web e il sistema di monitoraggio dei lead per acquisire e memorizzare il GCLID, il GBRAID o il WBRAID di ogni impressione e clic per i tuoi annunci. Il tagging automatico è attivo per impostazione predefinita per i nuovi account.

Crea la richiesta

Segui le indicazioni riportate di seguito per creare il tuo UploadClickConversionsRequest e impostare i relativi campi su valori appropriati.

customer_id

Identifica l'account Google Ads del caricamento. Imposta questo valore sul cliente di conversione Google Ads dell'account che è l'origine dei clic.

job_id

Fornisce un meccanismo per associare le richieste di caricamento alle informazioni per job nella diagnostica dei dati offline.

Se non imposti questo campo, l'API Google Ads assegna a ogni richiesta un valore unico nell'intervallo [2^31, 2^63). Se preferisci raggruppare più richieste in un unico job logico, imposta questo campo sullo stesso valore nell'intervallo [0, 2^31) in ogni richiesta del job.

Il valore job_id nella risposta contiene l'ID job per la richiesta, indipendentemente dal fatto che tu abbia specificato un valore o lasciato che l'API Google Ads ne assegni uno.

partial_failure_enabled

Determina il modo in cui l'API Google Ads gestisce gli errori delle operazioni.

Questo campo deve essere impostato su true. Segui le linee guida per gli errori parziali durante l'elaborazione della risposta.

debug_enabled

Determina il comportamento di generazione di report sugli errori per i caricamenti delle conversioni avanzate per i lead. L'API Google Ads ignora questo campo durante la gestione dei caricamenti per le conversioni di clic utilizzando gclid, gbraid o wbraid.

Creare operazioni di conversione dei clic

La raccolta di oggetti ClickConversion nel UploadClickConversionRequest definisce l'insieme di conversioni da caricare. Segui le indicazioni riportate di seguito per creare ogni ClickConversion e impostarne i campi su valori appropriati.

Imposta i campi obbligatori di ogni operazione di conversione

Segui le istruzioni riportate di seguito per impostare i campi obbligatori di ClickConversion su valori appropriati.

gclid, gbraid, wbraid
L'identificatore acquisito al momento del clic per il clic o l'impressione della conversione. Imposta solo uno di questi campi.
conversion_date_time

La data e l'ora della conversione.

Il valore deve avere un fuso orario specificato e il formato deve essere yyyy-mm-dd HH:mm:ss+|-HH:mm, ad esempio: 2022-01-01 19:32:45-05:00 (ignorando l'ora legale) .

Il fuso orario può essere qualsiasi valore valido: non deve corrispondere al fuso orario dell'account. Tuttavia, se prevedi di confrontare i dati sulle conversioni caricati con quelli nell'interfaccia utente di Google Ads, ti consigliamo di utilizzare lo stesso fuso orario del tuo account Google Ads in modo che i conteggi delle conversioni corrispondano. Puoi trovare ulteriori dettagli ed esempi nel Centro assistenza e consultare la sezione Codici e formati per un elenco di ID fuso orario validi.

user_identifiers

Non impostare questo campo quando carichi le conversioni utilizzando solo gli ID clic. Se questo campo è impostato, Google Ads tratta l'operazione di caricamento come un caricamento per le conversioni avanzate per i lead.

conversion_action

Il nome della risorsa dell'ConversionAction per la conversione dei clic.

L'azione di conversione deve avere un valore type pari a UPLOAD_CLICKS e deve essere presente nel cliente di conversione Google Ads dell'account Google Ads associato al clic.

conversion_value

Il valore della conversione.

currency_code

Il codice valuta del conversion_value.

Imposta i campi facoltativi di ogni operazione di conversione

Esamina l'elenco dei campi facoltativi di seguito e impostali su ClickConversion in base alle tue esigenze.

order_id
L'ID transazione per la conversione. Questo campo è facoltativo, ma vivamente consigliato. Se lo imposti durante il caricamento, devi utilizzarlo per eventuali aggiustamenti apportati alla conversione. Per scoprire di più su come utilizzare un ID transazione per ridurre al minimo le conversioni duplicate, consulta questo articolo del Centro assistenza.
external_attribution_data

Se utilizzi strumenti di terze parti o soluzioni proprietarie per monitorare le conversioni, potresti assegnare a Google Ads solo una parte del merito della conversione o distribuire il merito di una conversione su più clic. Le importazioni di conversioni attribuite esternamente ti consentono di caricare le conversioni con un merito frazionato assegnato a ogni clic.

Per caricare i crediti frazionati, imposta questo campo su un oggetto ExternalAttributionData con valori per external_attribution_model e external_attribution_credit.

custom_variables

I valori per le variabili di conversione personalizzate.

Google Ads non supporta le variabili di conversione personalizzate in combinazione con wbraid o gbraid.

cart_data

Puoi includere i dati del carrello degli acquisti per un ClickConversion nel campo cart_data, costituito dai seguenti attributi:

  • merchant_id: l'ID dell'account Merchant Center associato.
  • feed_country_code: il codice regione di due caratteri ISO 3166 del feed di Merchant Center.
  • feed_language_code: il codice lingua ISO 639-1 del feed di Merchant Center.
  • local_transaction_cost: la somma di tutti gli sconti a livello di transazione, in currency_code del ClickConversion.
  • items: gli articoli nel carrello degli acquisti.

Ogni elemento di items è costituito dai seguenti attributi:

  • product_id: l'ID del prodotto, a volte indicato come ID offerta o ID articolo.
  • quantity: la quantità dell'articolo.
  • unit_price: il prezzo unitario dell'articolo.

conversion_environment

Indica l'ambiente in cui è stata registrata questa conversione. Ad esempio, App o Web.

Esempio di codice

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);
        }
      }
    }
  }
}
UploadOfflineConversion.java

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.V18.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;
    }
}
UploadOfflineConversion.cs

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
        );
    }
}
UploadOfflineConversion.php

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}"'
    )
upload_offline_conversion.py

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
upload_offline_conversion.rb

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::V18::Services::ConversionUploadService::ClickConversion
    ->new({
      conversionAction =>
        Google::Ads::GoogleAds::V18::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::V18::Services::ConversionUploadService::CustomVariable
        ->new({
          conversionCustomVariable =>
            Google::Ads::GoogleAds::V18::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::V18::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;
}
upload_offline_conversion.pl

Risoluzione dei problemi

La diagnostica dei dati offline offre una singola risorsa per esaminare costantemente lo stato generale dei tuoi caricamenti. Tuttavia, durante l'implementazione puoi utilizzare le informazioni riportate in questa sezione per esaminare eventuali errori segnalati nel campo partial_failure_error della risposta.

Alcuni degli errori più comuni durante il caricamento delle azioni di conversione sono gli errori di autorizzazione, ad esempio USER_PERMISSION_DENIED. Verifica che l'ID cliente nella richiesta sia impostato sul cliente di conversione di Google Ads proprietario dell'azione di conversione. Per ulteriori dettagli, consulta la nostra guida all'autorizzazione e la nostra guida agli errori comuni per suggerimenti su come eseguire il debug di questi diversi errori.

Eseguire il debug degli errori comuni

Errore
ConversionUploadError.INVALID_CONVERSION_ACTION_TYPE L'azione di conversione specificata ha un tipo non valido per il caricamento delle conversioni di clic. Assicurati che il valore ConversionAction specificato nella richiesta di caricamento sia di tipo UPLOAD_CLICKS.
ConversionUploadError.NO_CONVERSION_ACTION_FOUND L'azione di conversione specificata non è attivata o non è possibile trovarla nel file customer_id in fase di caricamento. Recupero delle informazioni sulla configurazione delle conversioni per assicurarti che l'azione di conversione nel caricamento sia attivata e di proprietà del customer_id della richiesta di caricamento.
ConversionUploadError.TOO_RECENT_CONVERSION_ACTION L'azione di conversione è stata appena creata. Prima di riprovare le conversioni non riuscite, attendi almeno 6 ore dalla creazione dell'azione.
ConversionUploadError.INVALID_CUSTOMER_FOR_CLICK customer_id della richiesta non è lo stesso ID cliente che era l'account di conversione dell'API Google Ads al momento del clic. Aggiorna il customer_id della richiesta in base al cliente corretto.
ConversionUploadError.EVENT_NOT_FOUND Google Ads non riesce a trovare la combinazione di ID clic e customer_id. Esamina i requisiti per customer_id e conferma di eseguire il caricamento utilizzando l'account Google Ads corretto.
ConversionUploadError.DUPLICATE_CLICK_CONVERSION_IN_REQUEST Più conversioni nella richiesta hanno la stessa combinazione di ID clic, conversion_date_time e conversion_action. Rimuovi le conversioni duplicate dalla richiesta.
ConversionUploadError.CLICK_CONVERSION_ALREADY_EXISTS È stata caricata in precedenza una conversione con la stessa combinazione di ID clic, conversion_date_time e conversion_action. Ignora questo errore se stavi riprovando il caricamento e questa conversione è riuscita in precedenza. Se vuoi aggiungere un'altra conversione oltre a quella caricata in precedenza, modifica il valore conversion_date_time del ClickConversion per evitare di duplicare la conversione caricata in precedenza.
ConversionUploadError.EVENT_NOT_FOUND Google Ads non riesce a trovare la combinazione di ID clic e customer_id. Esamina i requisiti per customer_id e conferma di eseguire il caricamento utilizzando l'account Google Ads corretto.
ConversionUploadError.EXPIRED_EVENT Il clic importato si è verificato prima dell'intervallo di tempo specificato nel click_through_lookback_window_days campo. Una modifica a click_through_lookback_window_days influisce solo sui clic registrati dopo la modifica, pertanto la modifica della finestra di ricerca non risolverebbe questo errore per il determinato clic. Se opportuno, modifica conversion_action in un'altra azione con una finestra temporale più lunga.
ConversionUploadError.CONVERSION_PRECEDES_EVENT conversion_date_time è precedente alla data e all'ora del clic. Aggiorna conversion_date_time con un valore successivo.
ConversionUploadError.GBRAID_WBRAID_BOTH_SET Per ClickConversion è stato impostato un valore sia per gbraid sia per wbraid. Aggiorna la conversione in modo da utilizzare un solo ID clic e assicurati di non combinare più clic nella stessa conversione. Ogni clic ha un solo ID clic.
FieldError.VALUE_MUST_BE_UNSET Controlla il location del GoogleAdsError per determinare quale dei seguenti problemi ha causato l'errore.
  • ClickConversion ha un valore impostato per gclid, nonché almeno uno di gbraid o wbraid. Aggiorna la conversione in modo da utilizzare un solo ID clic e assicurati di non combinare più clic nella stessa conversione. Ogni clic ha un solo ID.
  • ClickConversion ha un valore impostato per gbraid o wbraid e un valore per custom_variables. Google Ads non supporta le variabili personalizzate per una conversione con un ID clic gbraid o wbraid. Deseleziona il campo custom_variables della conversione.

Conversioni nei report

Le conversioni caricate vengono riportate nei report per la data dell'impressione del clic originale, non per la data della richiesta di caricamento o per la data del conversion_date_time del ClickConversion.

Sono necessarie fino a 3 ore prima che le statistiche sulle conversioni importate vengano visualizzate nell'account Google Ads per l'attribuzione dell'ultimo clic. Per altri modelli di attribuzione della ricerca, potrebbero essere necessarie più di 3 ore. Per ulteriori informazioni, consulta la guida sull'aggiornamento dei dati.

Indietro
Crea azioni di conversione
Avanti
Caricare le conversioni di chiamata