Importer des conversions par appel

Vous pouvez utiliser l'API Google Ads pour importer les appels hors connexion de conversions dans Google Ads afin de déterminer quand les annonces génèrent des appels téléphoniques et quand ceux-ci génèrent des prospects. à des actions intéressantes de la part des clients.

Vous ne pouvez pas importer un clic "Appels directs depuis des mobiles" en tant que conversion s'il n'y a pas Numéro de transfert Google associé à l'appel. Sans redirection Google Google ne peut pas s'assurer que le clic a généré un appel, puis avant une conversion. Si un clic est importé de cette manière, il sera ignoré par la variable action de conversion.

Mapper avec l'interface utilisateur Google Ads revient à utiliser la conversion Importations. source, puis sélectionnez Conversions à partir d'appels.

Créer une conversion par appel

Voici quelques points à retenir lorsque vous créez un CallConversion:

  • À partir de la version v15 de l'API Google Ads, vous devez renseigner le champ Champ consent de CallConversion.

  • L'attribut partial_failure de UploadCallConversionsRequest doit toujours être défini sur true. Suivez les instructions relatives aux échecs partiels de sécurité pour la gestion les opérations ayant échoué simultanément.

  • Si vous rencontrez un TOO_RECENT_CONVERSION_ACTION ou TOO_RECENT_CALL à une demande d'importation de conversion, patientez 6 heures ou 12 heures, avant de relancer les lignes ayant échoué.

  • Un délai de trois heures peut être nécessaire pour que les statistiques sur les conversions importées s'affichent dans vos compte Google Ads.

  • Si vous importez des conversions en double (c'est-à-dire un CallConversion avec une valeur caller_id, conversion_date_time et conversion_action qui étaient précédemment importé), une erreur CALL_CONVERSION_ALREADY_EXISTS est renvoyée.

    • Si une même demande contient plusieurs opérations pour la même conversion, une erreur DUPLICATE_CALL_CONVERSION_IN_REQUEST est renvoyée.

Importer une conversion par appel

Pour associer vos conversions par appel hors connexion à une action de conversion, ont besoin des informations suivantes: le numéro de l'appelant (numéro de téléphone), date et heure de la conversion, nom de la ressource de l'action de conversion et, éventuellement, la valeur de conversion et la devise ConversionUploadService Pour en savoir plus sur les différentes entrées, consultez notre Aide Center. Le code exemple décrit également les formats des différentes entrées.

Conditions requises

Lorsque vous importez un fichier CallConversion

Pour éviter une erreur ConversionUploadError.INVALID_CONVERSION_ACTION, le Attribut conversion_action doit faire référence à un ConversionAction où:

  • ConversionActionType est UPLOAD_CALLS

  • La status sur ConversionAction est ENABLED. Sinon, l'opération échoue avec une NO_CONVERSION_ACTION_FOUND .

  • Le ConversionAction existe dans le client de conversion Google Ads du le compte Google Ads de ce clic.

Nous vous recommandons également de définir ConversionAction.category vers catégorie qui décrit le mieux vos conversions.

De plus, les conditions suivantes doivent être remplies:

  • Au moment de l'appel, le suivi des conversions était activé dans la Client ayant réalisé une conversion Google Ads du compte Google Ads associé à l'appel.

  • Le customer_id de UploadCallConversionsRequest doit être le numéro client de la conversion Google Ads. client de au compte Google Ads de l'appel. Sinon, l'importation des conversions générera ConversionUploadError.INVALID_CUSTOMER_FOR_CALL erreur.

  • La valeur de conversion_value doit être supérieure ou égale à zéro.

  • Vous devez spécifier un fuseau horaire pour conversion_date_time, et le format est en tant que yyyy-mm-dd HH:mm:ss+|-HH:mm, par exemple: 2022-01-01 19:32:45-05:00 (sans tenir compte de l'heure d'été) pour en savoir plus. Le fuseau horaire peut correspondre à n'importe quelle valeur valide : pas devant correspondre au fuseau horaire du compte.

Exemple de code

Java

private void runExample(
    GoogleAdsClient googleAdsClient,
    long customerId,
    String conversionActionId,
    String callerId,
    String callStartDateTime,
    double conversionValue,
    Long conversionCustomVariableId,
    String conversionCustomVariableValue,
    ConsentStatus adUserDataConsent) {
  // Create a call conversion by specifying currency as USD.
  CallConversion.Builder conversionBuilder =
      CallConversion.newBuilder()
          .setConversionAction(conversionActionId)
          .setCallerId(callerId)
          .setCallStartDateTime(callStartDateTime)
          .setConversionValue(conversionValue)
          .setCurrencyCode("USD");

  if (conversionCustomVariableId != null && conversionCustomVariableValue != null) {
    conversionBuilder.addCustomVariables(
        CustomVariable.newBuilder()
            .setConversionCustomVariable(
                ResourceNames.conversionCustomVariable(customerId, conversionCustomVariableId))
            .setValue(conversionCustomVariableValue));
  }

  // 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.
    conversionBuilder.setConsent(Consent.newBuilder().setAdUserData(adUserDataConsent));
  }

  CallConversion conversion = conversionBuilder.build();

  // Uploads the call conversion to the API.
  try (ConversionUploadServiceClient conversionUploadServiceClient =
      googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) {
    // Partial failure MUST be enabled for this request.

    // 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
    UploadCallConversionsResponse response =
        conversionUploadServiceClient.uploadCallConversions(
            UploadCallConversionsRequest.newBuilder()
                .setCustomerId(String.valueOf(customerId))
                .setCustomerId(Long.toString(customerId))
                .addConversions(conversion)
                .setPartialFailure(true)
                .build());

    // Prints any partial failure errors returned.
    if (response.hasPartialFailureError()) {
      GoogleAdsFailure googleAdsFailure =
          ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
      googleAdsFailure
          .getErrorsList()
          .forEach(e -> System.out.println("Partial failure occurred: " + e.getMessage()));
      throw new RuntimeException(
          "Partial failure occurred " + response.getPartialFailureError().getMessage());
    }

    // Prints the result if valid.
    CallConversionResult result = response.getResults(0);
    System.out.printf(
        "Uploaded call conversion that occurred at '%' for caller ID '%' to the conversion"
            + " action with resource name '%'.%n",
        result.getCallStartDateTime(), result.getCallerId(), result.getConversionAction());
  }
}
UploadCallConversion.java

C#

public void Run(GoogleAdsClient client, long customerId,
    long conversionActionId, string callerId, string callStartTime,
    string conversionTime, double conversionValue,
    long? conversionCustomVariableId, string conversionCustomVariableValue,
    ConsentStatus? adUserDataConsent)
{
    // Get the ConversionUploadService.
    ConversionUploadServiceClient conversionUploadService =
        client.GetService(Services.V17.ConversionUploadService);

    // Create a call conversion by specifying currency as USD.
    CallConversion callConversion = new CallConversion()
    {
        ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
        CallerId = callerId,
        CallStartDateTime = callStartTime,
        ConversionDateTime = conversionTime,
        ConversionValue = conversionValue,
        CurrencyCode = "USD",
    };

    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.
        callConversion.Consent = new Consent()
        {
            AdUserData = (ConsentStatus)adUserDataConsent
        };
    }

    if (conversionCustomVariableId != null &&
        !string.IsNullOrEmpty(conversionCustomVariableValue))
    {
        callConversion.CustomVariables.Add(new CustomVariable()
        {
            ConversionCustomVariable = ResourceNames.ConversionCustomVariable(
                customerId, conversionCustomVariableId.Value),
            Value = conversionCustomVariableValue
        });
    }

    UploadCallConversionsRequest request = new UploadCallConversionsRequest()
    {
        CustomerId = customerId.ToString(),
        Conversions = { callConversion },
        PartialFailure = true
    };

    try
    {
        // Issues a request to upload the call conversion. The partialFailure parameter
        // is set to true, and validateOnly parameter to false as required by this method
        // call.
        // 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
        UploadCallConversionsResponse response =
            conversionUploadService.UploadCallConversions(request);

        // Since we set partialFailure = true, we can retrieve error messages (if any) from
        // the operation response.
        if (response.PartialFailureError != null)
        {
            Console.WriteLine("Call conversion upload failed.");

            // Retrieves the errors from the partial failure and prints them.
            List<GoogleAdsError> errors =
                response.PartialFailure.GetErrorsByOperationIndex(0);
            foreach (GoogleAdsError error in errors)
            {
                Console.WriteLine($"Operation failed with error: {error}.");
            }
        }
        else
        {
            // Prints the result.
            CallConversionResult uploadedCallConversion = response.Results[0];
            Console.WriteLine($"Uploaded call conversion that occurred at " +
                $"'{uploadedCallConversion.CallStartDateTime}' for caller ID " +
                $"'{uploadedCallConversion.CallerId}' to the conversion action with " +
                $"resource name '{uploadedCallConversion.ConversionAction}'.");
        }

    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
UploadCallConversion.cs

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $conversionActionId,
    string $callerId,
    string $callStartDateTime,
    string $conversionDateTime,
    float $conversionValue,
    ?string $conversionCustomVariableId,
    ?string $conversionCustomVariableValue,
    ?int $adUserDataConsent
) {
    // Creates a call conversion by specifying currency as USD.
    $callConversion = new CallConversion([
        'conversion_action' =>
            ResourceNames::forConversionAction($customerId, $conversionActionId),
        'caller_id' => $callerId,
        'call_start_date_time' => $callStartDateTime,
        'conversion_date_time' => $conversionDateTime,
        'conversion_value' => $conversionValue,
        'currency_code' => 'USD'
    ]);
    if (!is_null($conversionCustomVariableId) && !is_null($conversionCustomVariableValue)) {
        $callConversion->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.
        $callConversion->setConsent(new Consent(['ad_user_data' => $adUserDataConsent]));
    }

    // Issues a request to upload the call conversion.
    $conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
    // 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->uploadCallConversions(
        // Partial failure MUST be enabled for this request.
        UploadCallConversionsRequest::build($customerId, [$callConversion], 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 CallConversionResult $uploadedCallConversion */
        $uploadedCallConversion = $response->getResults()[0];
        printf(
            "Uploaded call conversion that occurred at '%s' for caller ID '%s' to the "
            . "conversion action with resource name '%s'.%s",
            $uploadedCallConversion->getCallStartDateTime(),
            $uploadedCallConversion->getCallerId(),
            $uploadedCallConversion->getConversionAction(),
            PHP_EOL
        );
    }
}
UploadCallConversion.php

Python

def main(
    client,
    customer_id,
    conversion_action_id,
    caller_id,
    call_start_date_time,
    conversion_date_time,
    conversion_value,
    conversion_custom_variable_id,
    conversion_custom_variable_value,
    ad_user_data_consent,
):
    """Imports offline call conversion values for calls related to your ads.

    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.
        caller_id: The caller ID from which this call was placed. Caller ID is
            expected to be in E.164 format with preceding '+' sign,
            e.g. '+18005550100'.
        call_start_date_time: The date and time at which the call occurred. The
            format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm',
            e.g. '2021-01-01 12:32:45-08:00'.
        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.
        ad_user_data_consent: The consent status for ad user data for all
            members in the job.
    """
    # Get the ConversionUploadService client.
    conversion_upload_service = client.get_service("ConversionUploadService")

    # Create a call conversion in USD currency.
    call_conversion = client.get_type("CallConversion")
    call_conversion.conversion_action = client.get_service(
        "ConversionActionService"
    ).conversion_action_path(customer_id, conversion_action_id)
    call_conversion.caller_id = caller_id
    call_conversion.call_start_date_time = call_start_date_time
    call_conversion.conversion_date_time = conversion_date_time
    call_conversion.conversion_value = conversion_value
    call_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_custom_variable_id
        )
        conversion_custom_variable.value = conversion_custom_variable_value
        call_conversion.custom_variables.append(conversion_custom_variable)

    # 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
    if ad_user_data_consent:
        call_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[
            ad_user_data_consent
        ]

    # Issue a request to upload the call conversion.
    # Partial failure MUST be enabled for this request.
    request = client.get_type("UploadCallConversionsRequest")
    request.customer_id = customer_id
    request.conversions = [call_conversion]
    request.partial_failure = True
    # 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
    upload_call_conversions_response = (
        conversion_upload_service.upload_call_conversions(request=request)
    )

    # Print any partial errors returned.
    if upload_call_conversions_response.partial_failure_error:
        print(
            "Partial error occurred: "
            f"'{upload_call_conversions_response.partial_failure_error.message}'"
        )

    # Print the result if valid.
    uploaded_call_conversion = upload_call_conversions_response.results[0]
    if uploaded_call_conversion.call_start_date_time:
        print(
            "Uploaded call conversion that occurred at "
            f"'{uploaded_call_conversion.call_start_date_time}' "
            f"for caller ID '{uploaded_call_conversion.caller_id}' "
            "to the conversion action with resource name "
            f"'{uploaded_call_conversion.conversion_action}'."
        )
upload_call_conversion.py

Ruby

def upload_call_conversion(
  customer_id,
  conversion_action_id,
  caller_id,
  call_start_date_time,
  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

  # Create a call conversion by specifying currency as USD.
  call_conversion = client.resource.call_conversion do |c|
    c.conversion_action = client.path.conversion_action(
      customer_id, conversion_action_id)
    c.caller_id = caller_id
    c.call_start_date_time = call_start_date_time
    c.conversion_date_time = conversion_date_time
    c.conversion_value = conversion_value
    c.currency_code = "USD"
    if conversion_custom_variable_id && conversion_custom_variable_value
      c.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

    unless ad_user_data_consent.nil?
      c.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

  # Issues a request to upload the call conversion.
  response = client.service.conversion_upload.upload_call_conversions(
    customer_id: customer_id,
    # 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
    conversions: [call_conversion],
    partial_failure: true
  )

  # Prints errors if any partial failure error is returned.
  if response.partial_failure_error
    failures = client.decode_partial_failure_error(response.partial_failure_error)
    failures.each do |failure|
      failure.errors.each do |error|
        human_readable_error_path = error
          .location
          .field_path_elements
          .map { |location_info|
            if location_info.index
              "#{location_info.field_name}[#{location_info.index}]"
            else
              "#{location_info.field_name}"
            end
          }.join(" > ")

        errmsg =  "error occured while adding operations " \
          "#{human_readable_error_path}" \
          " with value: #{error.trigger.string_value}" \
          " because #{error.message.downcase}"
        puts errmsg
      end
    end
  else
    # Print the result if valid.
    uploaded_call_conversion = response.results.first
    puts "Uploaded call conversion that occurred at " \
      "#{uploaded_call_conversion.call_start_date_time} " \
      "for caller ID " \
      "#{uploaded_call_conversion.caller_id} " \
      "to the conversion action with resource name " \
      "#{uploaded_call_conversion.conversion_action}"
  end
end
upload_call_conversion.rb

Perl

sub upload_call_conversion {
  my (
    $api_client,                       $customer_id,
    $conversion_action_id,             $caller_id,
    $call_start_date_time,             $conversion_date_time,
    $conversion_value,                 $conversion_custom_variable_id,
    $conversion_custom_variable_value, $ad_user_data_consent
  ) = @_;

  # Create a call conversion by specifying currency as USD.
  my $call_conversion =
    Google::Ads::GoogleAds::V17::Services::ConversionUploadService::CallConversion
    ->new({
      conversionAction =>
        Google::Ads::GoogleAds::V17::Utils::ResourceNames::conversion_action(
        $customer_id, $conversion_action_id
        ),
      callerId           => $caller_id,
      callStartDateTime  => $call_start_date_time,
      conversionDateTime => $conversion_date_time,
      conversionValue    => $conversion_value,
      currencyCode       => "USD"
    });

  if ($conversion_custom_variable_id && $conversion_custom_variable_value) {
    $call_conversion->{customVariables} = [
      Google::Ads::GoogleAds::V17::Services::ConversionUploadService::CustomVariable
        ->new({
          conversionCustomVariable =>
            Google::Ads::GoogleAds::V17::Utils::ResourceNames::conversion_custom_variable(
            $customer_id, $conversion_custom_variable_id
            ),
          value => $conversion_custom_variable_value
        })];
  }

  # 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.
    $call_conversion->{consent} =
      Google::Ads::GoogleAds::V17::Common::Consent->new({
        adUserData => $ad_user_data_consent
      });
  }

  # Issue a request to upload the call conversion.
  # 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_call_conversions_response =
    $api_client->ConversionUploadService()->upload_call_conversions({
      customerId     => $customer_id,
      conversions    => [$call_conversion],
      partialFailure => "true"
    });

  # Print any partial errors returned.
  if ($upload_call_conversions_response->{partialFailureError}) {
    printf "Partial error encountered: '%s'.\n",
      $upload_call_conversions_response->{partialFailureError}{message};
  }

  # Print the result if valid.
  my $uploaded_call_conversion =
    $upload_call_conversions_response->{results}[0];
  if (%$uploaded_call_conversion) {
    printf "Uploaded call conversion that occurred at '%s' " .
      "for caller ID '%s' to the conversion action with resource name '%s'.\n",
      $uploaded_call_conversion->{callStartDateTime},
      $uploaded_call_conversion->{callerId},
      $uploaded_call_conversion->{conversionAction};
  }

  return 1;
}
upload_call_conversion.pl

Précédent
Importer des conversions par clic
Suivant
Importer les conversions de type "Ventes en magasin"