Gestione delle conversioni

In Google Ads, una conversione è un'azione utente di valore, ad esempio l'acquisto di un prodotto, l'invio di un modulo per i lead, una chiamata alla tua attività o una visita a un negozio fisico, che segue un'interazione con l'annuncio. Il monitoraggio delle conversioni misura queste interazioni con i clienti in modo da consentirti di valutare il rendimento della campagna e ottimizzare le offerte automatiche.

L'API Google Ads ti consente di configurare in modo programmatico le azioni di conversione, importare gli eventi di conversione offline, migliorare o modificare le conversioni registrate, raggruppare le azioni in obiettivi di offerta e basati sul ciclo di vita e monitorare la diagnostica dei caricamenti.

Scegli il workflow di conversione

Utilizza la seguente tabella per identificare ConversionActionType, il servizio API e la guida all'implementazione per il tuo caso d'uso:

Attività Tipo di azione di conversione Servizio o risorsa API Guida all'implementazione
Verifica la configurazione dell'account e crea un'azione di conversione UPLOAD_CLICKS, WEBPAGE, UPLOAD_CALLS, AD_CALL, WEBSITE_CALL, GOOGLE_PLAY_DOWNLOAD, GOOGLE_PLAY_IN_APP_PURCHASE Customer (ConversionTrackingSetting), ConversionActionService Inizia e Categorie di azioni di conversione
Importa le conversioni da clic offline o le conversioni avanzate per i lead UPLOAD_CLICKS ConversionUploadService.UploadClickConversions (o API Data Manager per le nuove integrazioni) Importa le conversioni da clic offline
Migliora le conversioni online (conversioni avanzate per il web) WEBPAGE ConversionAdjustmentUploadService.UploadConversionAdjustments (ENHANCEMENT) Importa le conversioni da clic online
Importare le conversioni di chiamata UPLOAD_CALLS ConversionUploadService.UploadCallConversions Importa le conversioni di chiamata
Importa le transazioni di vendita in negozio STORE_SALES, STORE_SALES_DIRECT_UPLOAD OfflineUserDataJobService (o API Data Manager) Importa le conversioni per le vendite in negozio
Ritira o ricalcola le conversioni registrate UPLOAD_CLICKS, WEBPAGE, SALESFORCE (deprecato) ConversionAdjustmentUploadService.UploadConversionAdjustments (RETRACTION, RESTATEMENT) Regola le conversioni dopo l'importazione
Associa i metadati dei tag personalizzati alle conversioni UPLOAD_CLICKS, UPLOAD_CALLS, WEBPAGE ConversionCustomVariableService Variabili di conversione personalizzate
Configura gli obiettivi di offerta, gli obiettivi basati sul ciclo di vita e le regole per i valori Obiettivi basati sul ciclo di vita, della campagna e dell'account CustomerConversionGoalService, CampaignConversionGoalService, CustomConversionGoalService, ConversionGoalCampaignConfigService, GoalService, CampaignGoalConfigService, ConversionValueRuleService Obiettivi di conversione, obiettivi basati sul ciclo di vita e regole per i valori di conversione
Monitora l'integrità dell'importazione e la diagnostica degli errori UPLOAD_CLICKS, WEBPAGE, UPLOAD_CALLS offline_conversion_upload_client_summary, offline_conversion_upload_conversion_action_summary Monitora la diagnostica dei dati offline
Esegui query sulle metriche di conversione e risolvi gli errori Tutti i tipi di conversione GoogleAdsService.SearchStream (customer, campaign, conversion_action) Recupera le statistiche sulle conversioni e Risolvi i problemi relativi alle importazioni delle conversioni

Ciclo di vita delle conversioni end-to-end

Un'integrazione completa della gestione delle conversioni nell'API Google Ads prevede quattro fasi:

  1. Verifica la configurazione dell'account e crea azioni di conversione: esegui una query su Customer.conversion_tracking_setting per confermare l'account di conversione effettivo (google_ads_conversion_customer), verifica che il monitoraggio delle conversioni sia attivo, configura il consenso dell'utente e crea un ConversionAction con il target ConversionActionType e ConversionActionCategory.
  2. Importa gli eventi di conversione: trasmetti in streaming le conversioni di chiamata o di clic offline utilizzando ConversionUploadService con partial_failure impostato su true, integra le conversioni sul sito web con gli aggiustamenti ENHANCEMENT utilizzando ConversionAdjustmentUploadService o carica collettivamente le vendite in negozio utilizzando OfflineUserDataJobService.
  3. Modifica e ottimizza le conversioni: ritira o modifica le conversioni registrate utilizzando ConversionAdjustmentUploadService, allega i metadati ConversionCustomVariable, applica le regole per i valori di conversione e organizza le azioni in obiettivi di conversione e obiettivi basati sul ciclo di vita per controllare l'ottimizzazione delle offerte.
  4. Monitora la diagnostica e il rendimento dei report: esegui query su offline_conversion_upload_client_summary e offline_conversion_upload_conversion_action_summary per controllare lo stato di elaborazione dei caricamenti e gli avvisi di errore parziale. Esegui una query sulle risorse customer o campaign (facoltativamente segmentate per segments.conversion_action) per confrontare le metriche metrics.conversions e metrics.all_conversions oppure esegui una query sulla risorsa conversion_action per esaminare metrics.all_conversions e i timestamp dell'ultima conversione.

Guida rapida: verifica la configurazione, crea azioni e controlla l'integrità

I seguenti esempi mostrano le tre query e mutazioni più comuni necessarie per inizializzare e monitorare il monitoraggio delle conversioni.

1. Verifica le impostazioni del monitoraggio delle conversioni con GAQL

Prima di creare un ConversionAction o caricare eventi, esegui una query sulla risorsa customer utilizzando GoogleAdsService.SearchStream per determinare quale account gestisce le conversioni (google_ads_conversion_customer), se i termini relativi ai dati dei clienti sono stati accettati e se le conversioni avanzate a livello di account sono attive (EnhancedConversionsConfig):

SELECT
  customer.conversion_tracking_setting.conversion_tracking_id,
  customer.conversion_tracking_setting.conversion_tracking_status,
  customer.conversion_tracking_setting.cross_account_conversion_tracking_id,
  customer.conversion_tracking_setting.google_ads_conversion_customer,
  customer.conversion_tracking_setting.accepted_customer_data_terms,
  customer.conversion_tracking_setting.enablement_setting,
  customer.conversion_tracking_setting.effective_enablement_setting
FROM customer

Estrai {customer_id} dal nome della risorsa customers/{customer_id} restituito in google_ads_conversion_customer ed esegui tutte le richieste ConversionActionService e ConversionUploadService successive per questo ID cliente. Per i dettagli completi sulla configurazione e sulla gerarchia tra account, consulta Inizia.

2. Crea un'azione di conversione

Utilizza ConversionActionService.MutateConversionActions per creare un ConversionAction. L'esempio seguente crea un'azione di conversione UPLOAD_CLICKS con impostazioni personalizzate per il valore e la finestra temporale:

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.V26.ConversionActionService);

    // Note that conversion action names must be unique.
    // If a conversion action already exists with the specified name the create operation
    // will fail with a ConversionAction.DUPLICATE_NAME error.
    string ConversionActionName = "Earth to Mars Cruises Conversion #"
        + ExampleUtilities.GetRandomString();

    // Add a conversion action.
    ConversionAction conversionAction = new ConversionAction()
    {
        Name = ConversionActionName,
        Category = ConversionActionCategory.Default,
        Type = ConversionActionType.Webpage,
        Status = ConversionActionStatus.Enabled,
        ViewThroughLookbackWindowDays = 15,
        ValueSettings = new ConversionAction.Types.ValueSettings()
        {
            DefaultValue = 23.41,
            AlwaysUseDefaultValue = true
        }
    };

    // Create the operation.
    ConversionActionOperation operation = new ConversionActionOperation()
    {
        Create = conversionAction
    };

    try
    {
        // Create the conversion action.
        MutateConversionActionsResponse response =
            conversionActionService.MutateConversionActions(customerId.ToString(),
                    new ConversionActionOperation[] { operation });

        // Display the results.
        foreach (MutateConversionActionResult newConversionAction in response.Results)
        {
            Console.WriteLine($"New conversion action with resource name = " +
                $"'{newConversionAction.ResourceName}' was added.");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

PHP

    public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
    {
        // Creates a conversion action.
        $conversionAction = new ConversionAction(
            [
            // Note that conversion action names must be unique.
            // If a conversion action already exists with the specified conversion_action_name
            // the create operation will fail with a ConversionActionError.DUPLICATE_NAME error.
            'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(),
            'category' => ConversionActionCategory::PBDEFAULT,
            'type' => ConversionActionType::WEBPAGE,
            'status' => ConversionActionStatus::ENABLED,
            'view_through_lookback_window_days' => 15,
            'value_settings' => new ValueSettings(
                [
                'default_value' => 23.41,
                'always_use_default_value' => true
                ]
            )
            ]
        );

        // Creates a conversion action operation.
        $conversionActionOperation = new ConversionActionOperation();
        $conversionActionOperation->setCreate($conversionAction);

        // Issues a mutate request to add the conversion action.
        $conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient();
        $response = $conversionActionServiceClient->mutateConversionActions(
            MutateConversionActionsRequest::build($customerId, [$conversionActionOperation])
        );

        printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL);

        foreach ($response->getResults() as $addedConversionAction) {
            /**
 * @var ConversionAction $addedConversionAction
*/
            printf(
                "New conversion action added with resource name: '%s'%s",
                $addedConversionAction->getResourceName(),
                PHP_EOL
            );
        }
    }

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    conversion_action_service: ConversionActionServiceClient = (
        client.get_service("ConversionActionService")
    )

    # Create the operation.
    conversion_action_operation: ConversionActionOperation = client.get_type(
        "ConversionActionOperation"
    )

    # Create conversion action.
    conversion_action: ConversionAction = conversion_action_operation.create

    # Note that conversion action names must be unique. If a conversion action
    # already exists with the specified conversion_action_name, the create
    # operation will fail with a ConversionActionError.DUPLICATE_NAME error.
    conversion_action.name = f"Earth to Mars Cruises Conversion {uuid.uuid4()}"
    conversion_action.type_ = (
        client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS
    )
    conversion_action.category = (
        client.enums.ConversionActionCategoryEnum.DEFAULT
    )
    conversion_action.status = client.enums.ConversionActionStatusEnum.ENABLED
    conversion_action.view_through_lookback_window_days = 15

    # Create a value settings object.
    value_settings: ConversionAction.ValueSettings = (
        conversion_action.value_settings
    )
    value_settings.default_value = 15.0
    value_settings.always_use_default_value = True

    # Add the conversion action.
    conversion_action_response: MutateConversionActionsResponse = (
        conversion_action_service.mutate_conversion_actions(
            customer_id=customer_id,
            operations=[conversion_action_operation],
        )
    )

    print(
        "Created conversion action "
        f'"{conversion_action_response.results[0].resource_name}".'
    )

Ruby

def add_conversion_action(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new


  # Add a conversion action.
  conversion_action = client.resource.conversion_action do |ca|
    ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}"
    ca.type = :UPLOAD_CLICKS
    ca.category = :DEFAULT
    ca.status = :ENABLED
    ca.view_through_lookback_window_days = 15

    # Create a value settings object.
    ca.value_settings = client.resource.value_settings do |vs|
      vs.default_value = 15
      vs.always_use_default_value = true
    end
  end

  # Create the operation.
  conversion_action_operation = client.operation.create_resource.conversion_action(conversion_action)

  # Add the ad group ad.
  response = client.service.conversion_action.mutate_conversion_actions(
    customer_id: customer_id,
    operations: [conversion_action_operation],
  )

  puts "New conversion action with resource name = #{response.results.first.resource_name}."
end

Perl

sub add_conversion_action {
  my ($api_client, $customer_id) = @_;

  # Note that conversion action names must be unique.
  # If a conversion action already exists with the specified conversion_action_name,
  # the create operation fails with error ConversionActionError.DUPLICATE_NAME.
  my $conversion_action_name = "Earth to Mars Cruises Conversion #" . uniqid();

  # Create a conversion action.
  my $conversion_action =
    Google::Ads::GoogleAds::V26::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V26::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V26::Services::ConversionActionService::ConversionActionOperation
    ->new({create => $conversion_action});

  # Add the conversion action.
  my $conversion_actions_response =
    $api_client->ConversionActionService()->mutate({
      customerId => $customer_id,
      operations => [$conversion_action_operation]});

  printf "New conversion action added with resource name: '%s'.\n",
    $conversion_actions_response->{results}[0]{resourceName};

  return 1;
}

curl

Richiesta REST

Per creare lo stesso ConversionAction su REST, invia una richiesta POST a ConversionActionService.MutateConversionActions:

POST https://googleads.googleapis.com/v26/customers/{customer_id}/conversionActions:mutate

{
  "operations": [
    {
      "create": {
        "name": "Earth to Mars Cruise Conversion",
        "type": "UPLOAD_CLICKS",
        "category": "DEFAULT",
        "status": "ENABLED",
        "primaryForGoal": true,
        "countingType": "ONE_PER_CLICK",
        "clickThroughLookbackWindowDays": "60",
        "valueSettings": {
          "defaultValue": 23.41,
          "defaultCurrencyCode": "USD",
          "alwaysUseDefaultValue": true
        }
      }
    }
  ]
}

Una volta che l'azione di conversione è ENABLED, importa gli eventi di conversione o i miglioramenti utilizzando il workflow per l'origine conversione (consulta Importa eventi di conversione).

3. Monitora lo stato del caricamento delle conversioni offline

Dopo aver caricato le conversioni di clic, le conversioni di chiamata o gli aggiustamenti delle conversioni, esegui una query su offline_conversion_upload_client_summary per controllare lo stato complessivo del job, i tassi di successo e di attesa e le suddivisioni degli errori nei caricamenti recenti:

SELECT
  offline_conversion_upload_client_summary.client,
  offline_conversion_upload_client_summary.status,
  offline_conversion_upload_client_summary.total_event_count,
  offline_conversion_upload_client_summary.successful_event_count,
  offline_conversion_upload_client_summary.success_rate,
  offline_conversion_upload_client_summary.pending_event_count,
  offline_conversion_upload_client_summary.pending_rate,
  offline_conversion_upload_client_summary.last_upload_date_time,
  offline_conversion_upload_client_summary.alerts
FROM offline_conversion_upload_client_summary

Esegui una query su offline_conversion_upload_conversion_action_summary per la diagnostica a livello di azione di conversione (consulta Monitora la diagnostica dei dati offline) e consulta Risolvi i problemi relativi alle importazioni delle conversioni per risolvere codici di errore specifici.

Directory delle guide per fase del ciclo di vita

Esplora l'insieme completo di guide alla gestione delle conversioni organizzate per fase del ciclo di vita:

1. Configurazione dell'account e azioni di conversione

  • Categorie di azioni di conversione: seleziona l'origine conversione corretta, ovvero sito web (WEBPAGE), telefonata (UPLOAD_CALLS, AD_CALL, WEBSITE_CALL), app mobile (GOOGLE_PLAY_DOWNLOAD, GOOGLE_PLAY_IN_APP_PURCHASE, Firebase, SKAdNetwork), Google Analytics 4 (GOOGLE_ANALYTICS_4_CUSTOM, GOOGLE_ANALYTICS_4_PURCHASE), offline (UPLOAD_CLICKS) o negozio fisico (STORE_SALES), e mappala al ConversionActionType e al flusso di lavoro dell'API corrispondenti.
  • Per iniziare: configura il consenso dell'utente, verifica ConversionTrackingSetting, configura il monitoraggio delle conversioni su più account e crea azioni di conversione utilizzando le librerie client o REST.

2. Importa gli eventi di conversione

3. Modifica e ottimizza le conversioni

4. Monitora, genera report e risolvi i problemi

Avanti
Categorie di azioni di conversione