Subir conversiones de clics

Puedes usar la API de Google Ads para subir conversiones de clics sin conexión en Google Ads, mapeando la fuente de conversiones Cargas en la IU de Google Ads, seguida de las Conversiones generadas a partir de clics. Te brinda más flexibilidad para asociar los clics con las conversiones. Puedes hacer un seguimiento de los anuncios que generaron ventas sin conexión, por ejemplo, por teléfono o a través de un representante de ventas.

Parámetros de ID

Debes habilitar tu sitio web y sistema de seguimiento de clientes potenciales para captar y almacenar el GCLID, el ID único que proporciona Google Ads para cada impresión de un anuncio de Google. Si las conversiones por clic se suben a la IU de Google Ads, el etiquetado automático se habilita automáticamente para que tu sitio web comience a recibir el GCLID como un parámetro de URL. Sin embargo, esto no ocurre cuando se utiliza la API de Google Ads, por lo que debes habilitar el etiquetado automático mediante la actualización del atributo auto_tagging_enabled de Customer.

A partir de iOS 14, los clics pueden contener un parámetro wbraid (para los clics asociados con conversiones web) o un parámetro gbraid (para los clics asociados con conversiones de aplicación), en lugar del parámetro gclid.

Ten en cuenta las siguientes restricciones cuando especifiques combinaciones de wbraid, gbraid, gclid y user_identifiers para un objeto ClickConversion determinado:

  • Si proporcionas wbraid y gbraid, se generará el error GBRAID_WBRAID_BOTH_SET.

  • Proporcionar wbraid o gbraid y, al mismo tiempo, incluir gclid o user_identifiers genera el error VALUE_MUST_BE_UNSET.

  • Si no proporcionas wbraid ni gbraid, pero proporcionas gclid y user_identifiers, gclid tiene prioridad.

Además, las variables de conversión personalizadas no se admiten en combinación con wbraid ni gbraid. Por lo tanto, si proporcionas wbraid o gbraid y también incluyes custom_variables, se generará el error VALUE_MUST_BE_UNSET.

Ejemplo de código

Debes pasar el identificador gclid, gbraid o wbraid para asociar tus conversiones de clics sin conexión con una acción de conversión. Además, proporciona la fecha y la hora de la conversión, el nombre del recurso de la acción de conversión y, de manera opcional, el valor de conversión y la moneda a ConversionUploadService:

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) {
  // 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. An order ID is required in order to
    // upload enhancements as shown in the UploadConversionEnhancement example.
    clickConversionBuilder.setOrderId(orderId);
  }

  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.
    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());
      googleAdsFailure
          .getErrorsList()
          .forEach(e -> System.out.println("Partial failure occurred: " + e.getMessage()));
    }

    // Prints the result.
    ClickConversionResult result = response.getResults(0);
    // Only prints valid results.
    if (result.hasGclid()) {
      System.out.printf(
          "Uploaded conversion that occurred at '%s' from Google Click ID '%s' to '%s'.%n",
          result.getConversionDateTime(), result.getGclid(), result.getConversionAction());
    }
  }
}
      

C#

public void Run(GoogleAdsClient client, long customerId, long conversionActionId,
    string gclid, string gbraid, string wbraid, string conversionTime,
    double conversionValue)
{
    // Get the ConversionActionService.
    ConversionUploadServiceClient conversionUploadService =
        client.GetService(Services.V14.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"
    };

    // 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 $conversionDateTime,
    float $conversionValue,
    ?string $conversionCustomVariableId,
    ?string $conversionCustomVariableValue
) {
    // 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
        ])]);
    }

    // Issues a request to upload the click conversion.
    $conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
    /** @var UploadClickConversionsResponse $response */
    $response = $conversionUploadServiceClient->uploadClickConversions(
        UploadClickConversionsRequest::build($customerId, [$clickConversion], true)
    );

    // Prints the status message if any partial failure error is returned.
    // Note: The details of each partial failure error are not printed here, you can refer to
    // the example HandlePartialFailure.php to learn more.
    if ($response->hasPartialFailureError()) {
        printf(
            "Partial failures occurred: '%s'.%s",
            $response->getPartialFailureError()->getMessage(),
            PHP_EOL
        );
    } else {
        // Prints the result if exists.
        /** @var ClickConversionResult $uploadedClickConversion */
        $uploadedClickConversion = $response->getResults()[0];
        printf(
            "Uploaded click conversion that occurred at '%s' from Google Click ID '%s' " .
            "to '%s'.%s",
            $uploadedClickConversion->getConversionDateTime(),
            $uploadedClickConversion->getGclid(),
            $uploadedClickConversion->getConversionAction(),
            PHP_EOL
        );
    }
}
      

Python

def main(
    client,
    customer_id,
    conversion_action_id,
    gclid,
    conversion_date_time,
    conversion_value,
    conversion_custom_variable_id,
    conversion_custom_variable_value,
    gbraid,
    wbraid,
):
    """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.
    """
    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)

    request = client.get_type("UploadClickConversionsRequest")
    request.customer_id = customer_id
    request.conversions.append(click_conversion)
    request.partial_failure = True
    conversion_upload_response = conversion_upload_service.upload_click_conversions(
        request=request,
    )
    uploaded_click_conversion = conversion_upload_response.results[0]
    print(
        f"Uploaded conversion that occurred at "
        f'"{uploaded_click_conversion.conversion_date_time}" from '
        f'Google Click ID "{uploaded_click_conversion.gclid}" '
        f'to "{uploaded_click_conversion.conversion_action}"'
    )
      

Ruby

def upload_offline_conversion(
  customer_id,
  conversion_action_id,
  gclid,
  gbraid,
  wbraid,
  conversion_date_time,
  conversion_value,
  conversion_custom_variable_id,
  conversion_custom_variable_value)
  # 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
  end

  response = client.service.conversion_upload.upload_click_conversions(
    customer_id: customer_id,
    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
  ) = @_;

  # 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::V14::Services::ConversionUploadService::ClickConversion
    ->new({
      conversionAction =>
        Google::Ads::GoogleAds::V14::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::V14::Services::ConversionUploadService::CustomVariable
        ->new({
          conversionCustomVariable =>
            Google::Ads::GoogleAds::V14::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. An order ID is
    # required in order to upload enhancements as shown in the
    # upload_conversion_enhancement.pl example.
    $click_conversion->{orderId} = $order_id;
  }

  # Issue a request to upload the click conversion.
  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;
}
      

Importe conversiones atribuidas externamente

Si utilizas herramientas de terceros o soluciones propias para hacer un seguimiento de las conversiones, te recomendamos que otorgues a Google Ads solo una parte del crédito de la conversión. A veces, es posible que también desees distribuir el crédito de una conversión entre varios clics. Las importaciones de conversiones atribuidas externamente te permiten subir conversiones con fracciones de crédito asignadas a cada clic.

Para subir fracciones de créditos, debes seguir el ejemplo de código upload_offline_conversion y, luego, especificar los atributos external_attribution_model y external_attribution_credit para ExternalAttributionData cuando crees el ClickConversion.

Cómo incluir datos del carrito en las conversiones

Puedes incluir información del carrito de compras de un ClickConversion en el campo cart_data, que consta de los siguientes atributos:

  • merchant_id: Es el ID de la cuenta de Merchant Center asociada.
  • feed_country_code: Es el código de región ISO 3166 de dos caracteres del feed de Merchant Center.
  • feed_language_code: Es el código de idioma ISO 639-1 del feed de Merchant Center.
  • local_transaction_cost: Es la suma de todos los descuentos a nivel de la transacción, en el currency_code de ClickConversion.
  • items: Son los artículos en el carrito de compras.

Cada elemento de items consta de los siguientes atributos:

  • product_id: Es el ID del producto, a veces denominado ID de oferta o ID de artículo.
  • quantity: Es la cantidad del elemento.
  • unit_price: Es el precio unitario del artículo.

Sube la conversión de clics

Hay varios requisitos que se deben cumplir cuando se sube un ClickConversion.

Para evitar un error ConversionUploadError.INVALID_CONVERSION_ACTION, el atributo conversion_action debe hacer referencia a un ConversionAction en el que:

Además, se deben cumplir las siguientes condiciones:

  • El customer_id de UploadClickConversionsRequest debe ser el ID de cliente de la cuenta de seguimiento de conversiones efectiva de la cuenta de Google Ads del clic. De lo contrario, la carga de conversiones generará un error ConversionUploadError.INVALID_CUSTOMER_FOR_CLICK.

  • El conversion_date_time debe ser posterior a la impresión para evitar un error ConversionUploadError.CONVERSION_PRECEDES_GCLID.

  • El conversion_date_time debe ser anterior al click_through_lookback_window_days que especificaste para ConversionAction a fin de evitar un error ConversionUploadError.EXPIRED_GCLID.

  • El valor de conversion_value debe ser mayor o igual que cero.

  • conversion_date_time debe tener especificada una zona horaria, y el formato es yyyy-mm-dd HH:mm:ss+|-HH:mm, por ejemplo: 2022-01-01 19:32:45-05:00 (se ignora el horario de verano).

    La zona horaria puede ser para cualquier valor válido: no tiene que coincidir con la zona horaria de la cuenta. Sin embargo, si planeas comparar los datos de conversiones subidos con los de la IU de Google Ads, te recomendamos que utilices la misma zona horaria que tu cuenta de Google Ads para que los registros de conversiones coincidan.

Crea ClickConversion

Algunos aspectos que debes tener en cuenta cuando creas un ClickConversion:

  • El atributo partial_failure de UploadClickConversionsRequest siempre debe establecerse en true. Sigue los lineamientos de fallas parciales cuando manejes operaciones válidas y con errores de forma simultánea.

  • Si subes una conversión duplicada (es decir, una ClickConversion con gclid, conversion_date_time y conversion_action que se subió antes), se muestra un error CLICK_CONVERSION_ALREADY_EXISTS.

  • Si una sola solicitud contiene varias operaciones para la misma conversión, se muestra un error DUPLICATE_CLICK_CONVERSION_IN_REQUEST.

  • Las conversiones subidas se reflejan en los informes para la fecha de la impresión del clic original, no en la fecha de la solicitud de carga ni en la fecha del conversion_date_time de la ClickConversion.

  • Es posible que encuentres TOO_RECENT_CONVERSION_ACTION cuando intentes subir conversiones a una acción de conversión recién creada. Se recomienda esperar al menos 6 horas después de crear la acción antes de volver a intentar las filas con errores.

  • Las estadísticas de conversiones importadas pueden demorar hasta 3 horas en aparecer en tu cuenta de Google Ads para la atribución de último clic. En el caso de otros modelos de atribución de búsqueda, puede tardar más de 3 horas.

  • Cuando subes conversiones por clic para varias cuentas, puedes especificar los customer_id de una cuenta de administrador en común y, luego, incluir las conversiones con GCLID de varias cuentas. Una conversión se atribuye a la cuenta correspondiente según el origen de su GCLID.

    Este enfoque tiene éxito solo si se cumplen las siguientes condiciones:

    1. La cuenta de conversión efectiva de la cuenta de cliente del GCLID se establece en el administrador especificado en el customer_id de la solicitud.
    2. El conversion_action de ClickConversion pertenece al administrador especificado en el customer_id de la solicitud.
  • Cuando se suben conversiones de clics con el seguimiento de conversiones de múltiples cuentas habilitado, la acción de conversión debe estar en la cuenta de administrador y no en la cuenta asociada con el GCLID.

  • Si planeas subir ajustes de datos de origen para las conversiones avanzadas, debes proporcionar un order_id para cada ClickConversion.