Importowanie dostosowań konwersji

Po zgłoszeniu konwersji w Google Ads możesz ją później dostosować w interfejsie Google Ads API.

Aby dostosować konwersję, musisz najpierw skonfigurować działanie powodujące konwersję i zarejestrować konwersje, które chcesz dostosować.

Przykładowy kod

Interfejs Google Ads API obsługuje używanie parametru order_id, znanego też jako identyfikator transakcji, do identyfikowania konwersji, którą należy dostosować za pomocą ConversionAdjustmentUploadService.

Aby uzyskać parametr conversion_action_id wymagany do dostosowania konwersji, możesz wykonać jedną z tych czynności:

  • Uzyskaj wartość z parametru ctId dostępnego w adresie URL, gdy klikniesz szczegóły konwersji w interfejsie Google Ads.

  • Wyślij do interfejsu Google Ads API zapytanie o conversion_action.id w raporcie conversion_action.

Java

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

C#

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.V26.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;
    }
}

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
            );
        }
    }

Python

def main(
    client: GoogleAdsClient,
    customer_id: str,
    conversion_action_id: str,
    adjustment_type: str,
    order_id: str,
    adjustment_date_time: str,
    restatement_value: Optional[str] = None,
) -> 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: ConversionAdjustmentTypeEnum = (
        client.enums.ConversionAdjustmentTypeEnum
    )
    # Determine the adjustment type.
    conversion_adjustment_type: int = conversion_adjustment_type_enum[
        adjustment_type
    ].value

    # Applies the conversion adjustment to the existing conversion.
    conversion_adjustment: ConversionAdjustment = client.get_type(
        "ConversionAdjustment"
    )
    conversion_action_service: ConversionActionServiceClient = (
        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: ConversionAdjustmentUploadServiceClient = client.get_service(
        "ConversionAdjustmentUploadService"
    )
    request: UploadConversionAdjustmentsRequest = 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: UploadConversionAdjustmentsResponse = (
        service.upload_conversion_adjustments(request=request)
    )

    # Extracts the partial failure error if present on the response.
    error_details = None
    if response.partial_failure_error:
        error_details: Iterable[Any] = response.partial_failure_error.details

    i: int
    conversion_adjustment_result: ConversionAdjustmentResult
    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: Any = error_details[i]
            failure_message: GoogleAdsFailure = client.get_type(
                "GoogleAdsFailure"
            )
            # Parse the string into a GoogleAdsFailure message instance.
            # To access class-only methods on the message we retrieve its type.
            google_ads_failure_class: GoogleAdsFailure = type(failure_message)
            failure_object: GoogleAdsFailure = (
                google_ads_failure_class.deserialize(error_detail.value)
            )

            error: GoogleAdsError
            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}'."
            )

Ruby

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

Perl

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::V26::Services::ConversionAdjustmentUploadService::ConversionAdjustment
    ->new({
      conversionAction =>
        Google::Ads::GoogleAds::V26::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::V26::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::V26::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;
}

curl

Wymagania

Oto kilka wymagań i ograniczeń, o których należy pamiętać podczas dostosowywania konwersji w interfejsie API:

  • Dostosowania może importować tylko konto, które zarządza działaniami powodującymi konwersję. Aby dowiedzieć się, które konto zarządza konwersjami na Twoim koncie Google Ads, skorzystaj z instrukcji konfigurowania śledzenia konwersji.

    Próba zaimportowania dostosowania za pomocą innego konta spowoduje błąd NO_CONVERSION_ACTION_FOUND. Ten błąd występuje też wtedy, gdy działanie powodujące konwersję, którego dotyczy dostosowanie, nie jest włączone.

  • Google Ads obsługuje dostosowywanie konwersji tylko w przypadku działań powodujących konwersję typu SALESFORCE, UPLOAD_CLICKS lub WEBPAGE. Próba zaimportowania dostosowania konwersji, w której działanie powodujące konwersję nie jest jednym z tych typów, spowoduje błąd INVALID_CONVERSION_ACTION_TYPE.

  • Pola określające datę i godzinę wymagają wybranej strefy czasowej, która może się różnić od strefy czasowej konta. Pola muszą być sformatowane jako yyyy-mm-dd HH:mm:ss+|-HH:mm, na przykład: 2022-01-01 19:32:45-05:00 (bez uwzględniania czasu letniego).

  • Aby uniknąć błędu TOO_RECENT_CONVERSION_ACTION, po utworzeniu działania powodującego konwersję odczekaj 4–6 godzin, zanim dostosujesz jego konwersje.

  • Jeśli konwersja nigdy nie została zaimportowana lub została zaimportowana, ale odrzucona, ponieważ uznano ją za nieprawidłową lub spam, dostosowanie nie powiedzie się i zostanie wyświetlony błąd CONVERSION_NOT_FOUND.

  • Musisz podać order_id w ConversionAdjustment w tych przypadkach:

    • type działania powodującego konwersję jest równa WEBPAGE.

    • Pierwotna konwersja, którą dostosowujesz, została przypisana do: order_id.

    Jeśli zamiast tego podasz gclid_date_time_pair, operacja zakończy się niepowodzeniem i odpowiednio błędem ConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE lub ConversionAdjustmentUploadError.CONVERSION_NOT_FOUND.

  • Podczas tworzenia ConversionAdjustment atrybut partial_failure elementu UploadConversionAdjustmentsRequest powinien być zawsze ustawiony na true. Podczas jednoczesnego obsługiwania prawidłowych i nieudanych operacji postępuj zgodnie ze wskazówkami dotyczącymi częściowych niepowodzeń.

  • Nie możesz zmienić ConversionAction przypisanego do konwersji za pomocą dostosowania. Zamiast tego użyj RETRACTION, aby usunąć poprzednią konwersję i zaimportować nową konwersję ze zaktualizowaną wartością ConversionAction. Nie trzeba zmieniać sygnatury czasowej. Więcej informacji znajdziesz w artykule Korekty konwersji.

Wstecz
Zarządzanie konwersjami polegającymi na sprzedaży w sklepie
Dalej
Reguły wartości konwersji