Загрузить корректировки конверсий

Как только о конверсии уже будет сообщено в Google Рекламу, вы сможете позже скорректировать конверсию в API Google Рекламы.

Ключевой момент: подождите 24 часа после сообщения о преобразовании, прежде чем его корректировать, чтобы избежать ошибок CONVERSION_NOT_FOUND или TOO_RECENT_CONVERSION .

Чтобы скорректировать конверсию, сначала необходимо настроить действие-конверсию, а также записать конверсии, которые вы собираетесь корректировать.

Внимание! Корректировки конверсий не работают с действиями-конверсиями типа UNKNOWN .

Пример кода

API Google Рекламы поддерживает использование order_id , также известного как идентификатор транзакции , для идентификации конверсии, которую нужно корректировать с помощью ConversionAdjustmentUploadService .

Примечание. Хотя вы также можете идентифицировать преобразование с помощью gclid_date_time_pair , этот подход менее надежен, чем использование order_id , и поэтому не рекомендуется.

Чтобы получить conversion_action_id , необходимую для корректировки конверсии, вы можете выполнить одно из следующих действий:

• Получите значение из параметра ctId , доступного в URL-адресе, когда вы нажимаете «Сведения о конверсии» в пользовательском интерфейсе Google Рекламы.

• Запросите API Google Рекламы для conversion_action.id в отчете conversion_action .

Джава

private void runExample(
    GoogleAdsClient googleAdsClient,
    long customerId,
    long conversionActionId,
    String orderId,
    String adjustmentType,
    String adjustmentDateTime,
    @Nullable Float restatementValue)
    throws InvalidProtocolBufferException {
  // Gets the conversion adjustment enum value from the adjustmentType String.
  ConversionAdjustmentType conversionAdjustmentType =
      ConversionAdjustmentType.valueOf(adjustmentType);

  // Applies the conversion adjustment to the existing conversion.
  ConversionAdjustment conversionAdjustment =
      ConversionAdjustment.newBuilder()
          .setConversionAction(ResourceNames.conversionAction(customerId, conversionActionId))
          .setAdjustmentType(conversionAdjustmentType)
          // Sets the orderId to identify the conversion to adjust.
          .setOrderId(orderId)
          // As an alternative to setting orderId, you can provide a GclidDateTimePair, but
          // setting orderId instead is strongly recommended.
          // .setGclidDateTimePair(
          //     GclidDateTimePair.newBuilder()
          //         .setGclid(gclid)
          //         .setConversionDateTime(conversionDateTime)
          //         .build())
          .setAdjustmentDateTime(adjustmentDateTime)
          .build();

  // Sets adjusted value for adjustment type RESTATEMENT.
  if (restatementValue != null
      && conversionAdjustmentType == ConversionAdjustmentType.RESTATEMENT) {
    conversionAdjustment =
        conversionAdjustment.toBuilder()
            .setRestatementValue(
                RestatementValue.newBuilder().setAdjustedValue(restatementValue).build())
            .build();
  }

  // Creates the conversion upload service client.
  try (ConversionAdjustmentUploadServiceClient conversionUploadServiceClient =
      googleAdsClient.getLatestVersion().createConversionAdjustmentUploadServiceClient()) {
    // Uploads the click conversion. Partial failure should always be set to true.
    UploadConversionAdjustmentsRequest request =
        UploadConversionAdjustmentsRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            // Enables partial failure (must be true).
            .setPartialFailure(true)
            .addConversionAdjustments(conversionAdjustment)
            .build();
    UploadConversionAdjustmentsResponse response =
        conversionUploadServiceClient.uploadConversionAdjustments(request);

    // Extracts the partial failure error if present on the response.
    ErrorUtils errorUtils = ErrorUtils.getInstance();
    GoogleAdsFailure googleAdsFailure =
        response.hasPartialFailureError()
            ? errorUtils.getGoogleAdsFailure(response.getPartialFailureError())
            : null;

    // Constructs a protocol buffer printer that will print error details in a concise format.
    final Printer errorPrinter = JsonFormat.printer().omittingInsignificantWhitespace();
    // Prints the results for each adjustment, including any partial errors returned.
    for (int opIndex = 0; opIndex < request.getConversionAdjustmentsCount(); opIndex++) {
      ConversionAdjustmentResult result = response.getResults(opIndex);
      if (errorUtils.isPartialFailureResult(result)) {
        // The operation failed. Prints the error details.
        for (GoogleAdsError googleAdsError :
            errorUtils.getGoogleAdsErrors(opIndex, googleAdsFailure)) {
          System.out.printf(
              "%4d: Partial failure occurred: %s%n", opIndex, errorPrinter.print(googleAdsError));
        }
      } else {
        System.out.printf(
            "%4d: Uploaded conversion adjustment for conversion action '%s' and order ID '%s'.%n",
            opIndex, result.getConversionAction(), result.getOrderId());
      }
    }
  }
}
UploadConversionAdjustment.java
      

С#

public void Run(GoogleAdsClient client, long customerId, long conversionActionId,
    string orderId, string adjustmentDateTime,
    ConversionAdjustmentType adjustmentType,
    double? restatementValue)
{
    // Get the ConversionAdjustmentUploadService.
    ConversionAdjustmentUploadServiceClient conversionAdjustmentUploadService =
        client.GetService(Services.V16.ConversionAdjustmentUploadService);

    // Associate conversion adjustments with the existing conversion action.
    ConversionAdjustment conversionAdjustment = new ConversionAdjustment()
    {
        ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
        AdjustmentType = adjustmentType,
        // Sets the orderId to identify the conversion to adjust.
        OrderId = orderId,
        // As an alternative to setting orderId, you can provide a GclidDateTimePair,
        // but setting orderId instead is strongly recommended.
        //GclidDateTimePair = new GclidDateTimePair()
        //{
        //    Gclid = gclid,
        //    ConversionDateTime = conversionDateTime,
        //},
        AdjustmentDateTime = adjustmentDateTime,
    };

    // Set adjusted value for adjustment type RESTATEMENT.
    if (adjustmentType == ConversionAdjustmentType.Restatement)
    {
        conversionAdjustment.RestatementValue = new RestatementValue()
        {
            AdjustedValue = restatementValue.Value
        };
    }

    try
    {
        // Issue a request to upload the conversion adjustment.
        UploadConversionAdjustmentsResponse response =
            conversionAdjustmentUploadService.UploadConversionAdjustments(
                new UploadConversionAdjustmentsRequest()
                {
                    CustomerId = customerId.ToString(),
                    ConversionAdjustments = { conversionAdjustment },
                    // Enables partial failure (must be true).
                    PartialFailure = true,
                    ValidateOnly = false
                });

        // Prints any partial errors returned.
        // To review the overall health of your recent uploads, see:
        // https://developers.google.com/google-ads/api/docs/conversions/upload-summaries
        if (response.PartialFailureError != null)
        {
            // Extracts the partial failure from the response status.
            GoogleAdsFailure partialFailure = response.PartialFailure;
            Console.WriteLine($"{partialFailure.Errors.Count} partial failure error(s) " +
                $"occurred");
        }
        else
        {
            ConversionAdjustmentResult result = response.Results[0];
            // Print the result.
            Console.WriteLine($"Uploaded conversion adjustment value of" +
                $" '{result.ConversionAction}' for Google Click ID " +
                $"'{result.GclidDateTimePair.Gclid}'");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
UploadConversionAdjustment.cs
      

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $conversionActionId,
    string $orderId,
    string $adjustmentType,
    string $adjustmentDateTime,
    ?float $restatementValue
) {
    $conversionAdjustmentType = ConversionAdjustmentType::value($adjustmentType);

    // Applies the conversion adjustment to the existing conversion.
    $conversionAdjustment = new ConversionAdjustment([
        'conversion_action' =>
            ResourceNames::forConversionAction($customerId, $conversionActionId),
        'adjustment_type' => $conversionAdjustmentType,
        // Sets the orderId to identify the conversion to adjust.
        'order_id' => $orderId,
        // As an alternative to setting orderId, you can provide a 'gclid_date_time_pair', but
        // setting 'order_id' instead is strongly recommended.
        // 'conversion_date_time' must be in "yyyy-mm-dd hh:mm:ss+|-hh:mm" format.
        /*
        'gclid_date_time_pair' => new GclidDateTimePair([
            'gclid' => 'INSERT_YOUR_GCLID_HERE',
            'conversion_date_time' => 'INSERT_YOUR_CONVERSION_DATE_TIME_HERE'
        ]),
        */
        'adjustment_date_time' => $adjustmentDateTime
    ]);

    // Sets adjusted value for adjustment type RESTATEMENT.
    if (
        $restatementValue !== null
        && $conversionAdjustmentType === ConversionAdjustmentType::RESTATEMENT
    ) {
        $conversionAdjustment->setRestatementValue(new RestatementValue([
            'adjusted_value' => $restatementValue
        ]));
    }

    // Issues a request to upload the conversion adjustment.
    $conversionAdjustmentUploadServiceClient =
        $googleAdsClient->getConversionAdjustmentUploadServiceClient();
    $response = $conversionAdjustmentUploadServiceClient->uploadConversionAdjustments(
        // Enables partial failure (must be true).
        UploadConversionAdjustmentsRequest::build($customerId, [$conversionAdjustment], 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 ConversionAdjustmentResult $uploadedConversionAdjustment */
        $uploadedConversionAdjustment = $response->getResults()[0];
        printf(
            "Uploaded conversion adjustment of '%s' for order ID '%s'.%s",
            $uploadedConversionAdjustment->getConversionAction(),
            $uploadedConversionAdjustment->getOrderId(),
            PHP_EOL
        );
    }
}
UploadConversionAdjustment.php
      

Питон

def main(
    client,
    customer_id,
    conversion_action_id,
    adjustment_type,
    order_id,
    adjustment_date_time,
    restatement_value=None,
):
    """The main method that creates all necessary entities for the example.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        conversion_action_id: the ID of the conversion action to upload the
            adjustment to.
        adjustment_type: the adjustment type, e.g. " "RETRACTION, RESTATEMENT.
        order_id: the transaction ID of the conversion to adjust. Strongly
            recommended instead of using gclid and conversion_date_time.
        adjustment_date_time: the date and time of the adjustment.
        restatement_value: the adjusted value for adjustment type RESTATEMENT.
    """
    conversion_adjustment_type_enum = client.enums.ConversionAdjustmentTypeEnum
    # Determine the adjustment type.
    conversion_adjustment_type = conversion_adjustment_type_enum[
        adjustment_type
    ].value

    # Applies the conversion adjustment to the existing conversion.
    conversion_adjustment = client.get_type("ConversionAdjustment")
    conversion_action_service = client.get_service("ConversionActionService")
    conversion_adjustment.conversion_action = (
        conversion_action_service.conversion_action_path(
            customer_id, conversion_action_id
        )
    )
    conversion_adjustment.adjustment_type = conversion_adjustment_type
    conversion_adjustment.adjustment_date_time = adjustment_date_time

    # Sets the order_id to identify the conversion to adjust.
    conversion_adjustment.order_id = order_id

    # As an alternative to setting order_id, you can provide a
    # gclid_date_time_pair, but setting order_id instead is strongly recommended.
    # conversion_adjustment.gclid_date_time_pair.gclid = gclid
    # conversion_adjustment.gclid_date_time_pair.conversion_date_time = (
    #     conversion_date_time
    # )

    # Sets adjusted value for adjustment type RESTATEMENT.
    if (
        restatement_value
        and conversion_adjustment_type
        == conversion_adjustment_type_enum.RESTATEMENT.value
    ):
        conversion_adjustment.restatement_value.adjusted_value = float(
            restatement_value
        )

    # Uploads the click conversion. Partial failure should always be set to
    # true.
    service = client.get_service("ConversionAdjustmentUploadService")
    request = client.get_type("UploadConversionAdjustmentsRequest")
    request.customer_id = customer_id
    request.conversion_adjustments.append(conversion_adjustment)
    # Enables partial failure (must be true)
    request.partial_failure = True

    response = service.upload_conversion_adjustments(request=request)

    # Extracts the partial failure error if present on the response.
    if response.partial_failure_error:
        error_details = response.partial_failure_error.details

    for i, conversion_adjustment_result in enumerate(response.results):
        # If there's a GoogleAdsFailure in error_details at this position then
        # the uploaded operation failed and we print the error message.
        if error_details and error_details[i]:
            error_detail = error_details[i]
            failure_message = client.get_type("GoogleAdsFailure")
            # Parse the string into a GoogleAdsFailure message instance.
            # To access class-only methods on the message we retrieve its type.
            GoogleAdsFailure = type(failure_message)
            failure_object = GoogleAdsFailure.deserialize(error_detail.value)

            for error in failure_object.errors:
                # Construct and print a string that details which element in
                # the operation list failed (by index number) as well as the
                # error message and error code.
                print(
                    "A partial failure at index "
                    f"{error.location.field_path_elements[0].index} occurred "
                    f"\nError message: {error.message}\nError code: "
                    f"{error.error_code}"
                )
        else:
            print(
                "Uploaded conversion adjustment for conversion action "
                f"'{conversion_adjustment_result.conversion_action}' and order "
                f"ID '{conversion_adjustment_result.order_id}'."
            )
upload_conversion_adjustment.py
      

Рубин

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

  # Applies the conversion adjustment to the existing conversion.
  conversion_adjustment = client.resource.conversion_adjustment do |ca|
    ca.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
    ca.adjustment_type = adjustment_type
    ca.order_id = order_id
    ca.adjustment_date_time = adjustment_date_time

    # Set adjusted value for adjustment type RESTATEMENT.
    if adjustment_type == :RESTATEMENT
      ca.restatement_value = client.resource.restatement_value do |ra|
        ra.adjusted_value = restatement_value.to_f
      end
    end
  end

  # Issue a request to upload the conversion adjustment(s).
  response = client.service.conversion_adjustment_upload.upload_conversion_adjustments(
    customer_id: customer_id,
    # This example shows just one adjustment but you may upload multiple ones.
    conversion_adjustments: [conversion_adjustment],
    partial_failure: true
  )

  if response.partial_failure_error.nil?
    # Process and print all results for multiple adjustments
    response.results.each do |result|
      puts "Uploaded conversion adjustment for conversion action #{result.conversion_action} "\
        "and order ID #{result.order_id}."
    end
  else
    # Print any partial errors returned.
    failures = client.decode_partial_failure_error(response.partial_failure_error)
    puts 'Request failed. Failure details:'
    failures.each do |failure|
      failure.errors.each do |error|
        index = error.location.field_path_elements.first.index
        puts "\toperation[#{index}] #{error.error_code.error_code}: #{error.message}"
      end
    end
  end
end
upload_conversion_adjustment.rb
      

Перл

sub upload_conversion_adjustment {
  my ($api_client, $customer_id, $conversion_action_id, $order_id,
    $adjustment_type, $adjustment_date_time, $restatement_value)
    = @_;

  # Applies the conversion adjustment to the existing conversion.
  my $conversion_adjustment =
    Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::ConversionAdjustment
    ->new({
      conversionAction =>
        Google::Ads::GoogleAds::V16::Utils::ResourceNames::conversion_action(
        $customer_id, $conversion_action_id
        ),
      adjustmentType => $adjustment_type,
      # Sets the orderId to identify the conversion to adjust.
      orderId => $order_id,
      # As an alternative to setting orderId, you can provide a 'gclid_date_time_pair',
      # but setting 'order_id' instead is strongly recommended.
      # gclidDateTimePair =>
      #  Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::GclidDateTimePair
      #  ->new({
      #    gclid              => $gclid,
      #    conversionDateTime => $conversion_date_time
      #  }
      #  ),
      adjustmentDateTime => $adjustment_date_time,
    });

  # Set adjusted value for adjustment type RESTATEMENT.
  $conversion_adjustment->{restatementValue} =
    Google::Ads::GoogleAds::V16::Services::ConversionAdjustmentUploadService::RestatementValue
    ->new({
      adjustedValue => $restatement_value
    }) if defined $restatement_value && $adjustment_type eq RESTATEMENT;

  # Issue a request to upload the conversion adjustment.
  my $upload_conversion_adjustments_response =
    $api_client->ConversionAdjustmentUploadService()
    ->upload_conversion_adjustments({
      customerId            => $customer_id,
      conversionAdjustments => [$conversion_adjustment],
      partialFailure        => "true"
    });

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

  # Print the result if valid.
  my $uploaded_conversion_adjustment =
    $upload_conversion_adjustments_response->{results}[0];
  if (%$uploaded_conversion_adjustment) {
    printf "Uploaded conversion adjustment of the conversion action " .
      "with resource name '%s' for order ID '%s'.\n",
      $uploaded_conversion_adjustment->{conversionAction},
      $uploaded_conversion_adjustment->{orderId};
  }

  return 1;
}
upload_conversion_adjustment.pl
      

Требования

Вот некоторые требования и ограничения, которые следует учитывать при настройке конверсий в API:

• Загружать корректировки может только тот аккаунт, который управляет действиями-конверсиями. Используйте инструкции по настройке отслеживания конверсий, чтобы определить, какой аккаунт управляет конверсиями в вашем аккаунте Google Рекламы.

  Попытка загрузить корректировку с использованием другого аккаунта приводит к ошибке NO_CONVERSION_ACTION_FOUND . Эта ошибка также возникает, если действие преобразования корректировки не включено.

• Google Реклама поддерживает настройку конверсий только для типов действий-конверсий SALESFORCE , UPLOAD_CLICKS или WEBPAGE . Попытка загрузить корректировку для конверсии, действие которой не относится к одному из этих типов, приводит к ошибке INVALID_CONVERSION_ACTION_TYPE .

• Для полей, определяющих дату и время, требуется часовой пояс, который не обязательно должен совпадать с часовым поясом учетной записи. Формат этих полей следующий: yyyy-mm-dd HH:mm:ss+|-HH:mm , например: 2022-01-01 19:32:45-05:00 (без учета летнего времени).

• Подождите 4–6 часов после создания действия-конверсии, прежде чем корректировать его конверсии, чтобы избежать ошибки TOO_RECENT_CONVERSION_ACTION .

• Корректировка завершается с ошибкой CONVERSION_NOT_FOUND , если выполняется любое из этих условий:

  • О конверсии никогда не сообщалось.

  • О конверсии было сообщено менее чем за 24 часа до попытки корректировки. В некоторых ситуациях это может привести к ошибке TOO_RECENT_CONVERSION .

• Вы должны указать order_id в ConversionAdjustment при любом из этих условий:

  • type действия-конверсии равен WEBPAGE .

  • Исходной конверсии, которую вы настраиваете, был присвоен order_id .

  Если вместо этого вы укажете gclid_date_time_pair , операция завершится с ошибкой ConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE или ConversionAdjustmentUploadError.CONVERSION_NOT_FOUND соответственно.

• При создании ConversionAdjustment атрибут partial_failure UploadConversionAdjustmentsRequest всегда должен иметь значение true . Следуйте рекомендациям по частичным сбоям при одновременной обработке допустимых и неудачных операций.

• Вы не можете изменить ConversionAction с помощью корректировки. Вместо этого используйте RETRACTION , чтобы удалить предыдущее преобразование и загрузить новое преобразование с обновленным ConversionAction . Временную метку изменять не нужно. См. раздел О корректировках конверсий .