Conversion-Anpassungen hochladen

Sobald eine Conversion bereits in Google Ads erfasst wurde, können Sie sie später über die Google Ads API anpassen.

Wichtiger Hinweis :Warten Sie 24 Stunden, nachdem eine Conversion erfasst wurde, bevor Sie sie anpassen, um einen CONVERSION_NOT_FOUND- oder TOO_RECENT_CONVERSION-Fehler zu vermeiden.

Wenn Sie eine Conversion anpassen möchten, müssen Sie zuerst eine Conversion-Aktion einrichten und die Conversions erfassen, die angepasst werden sollen.

Warnung :Conversion-Anpassungen funktionieren nicht mit Conversion-Aktionen vom Typ UNKNOWN.

Codebeispiel

Die Google Ads API unterstützt die Verwendung von order_id (auch als Transaktions-ID bezeichnet) zur Identifizierung der Conversion, die mit ConversionAdjustmentUploadService angepasst werden soll.

Hinweis: Sie können die Conversion auch mit einem gclid_date_time_pair identifizieren. Dieser Ansatz ist jedoch weniger langlebig als die Verwendung von order_id. Daher wird er nicht empfohlen.

Sie haben folgende Möglichkeiten, um das für eine Conversion-Anpassung erforderliche conversion_action_id abzurufen:

• Rufen Sie den Wert vom Parameter ctId in der URL ab, wenn Sie in der Google Ads-Benutzeroberfläche auf Conversion-Details klicken.

• Fragen Sie die Google Ads API im Bericht conversion_action nach conversion_action.id ab.

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

C#

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

    // Associate conversion adjustments with the existing conversion action.
    // The GCLID should have been uploaded before with a conversion.
    ConversionAdjustment conversionAdjustment = new ConversionAdjustment()
    {
        ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
        AdjustmentType = adjustmentType,
        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 },
                    PartialFailure = true,
                    ValidateOnly = false
                });

        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 $gclid,
    string $adjustmentType,
    string $conversionDateTime,
    string $adjustmentDateTime,
    float $restatementValue
) {
    $conversionAdjustmentType = ConversionAdjustmentType::value($adjustmentType);

    // Associates conversion adjustments with the existing conversion action.
    // The GCLID should have been uploaded before with a conversion.
    $conversionAdjustment = new ConversionAdjustment([
        'conversion_action' =>
            ResourceNames::forConversionAction($customerId, $conversionActionId),
        'adjustment_type' => $conversionAdjustmentType,
        'gclid_date_time_pair' => new GclidDateTimePair([
            'gclid' => $gclid,
            'conversion_date_time' => $conversionDateTime
        ]),
        '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(
        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 Google Click ID '%s'.%s",
            $uploadedConversionAdjustment->getConversionAction(),
            $uploadedConversionAdjustment->getGclidDateTimePair()->getGclid(),
            PHP_EOL
        );
    }
}
UploadConversionAdjustment.php
      

Python

def main(
    client,
    customer_id,
    conversion_action_id,
    gclid,
    adjustment_type,
    conversion_date_time,
    adjustment_date_time,
    restatement_value,
):
    conversion_adjustment_type_enum = client.enums.ConversionAdjustmentTypeEnum
    # Determine the adjustment type.
    conversion_adjustment_type = conversion_adjustment_type_enum[
        adjustment_type
    ].value

    # Associates conversion adjustments with the existing conversion action.
    # The GCLID should have been uploaded before with a 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

    # Set the Gclid Date
    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
        )

    conversion_adjustment_upload_service = client.get_service(
        "ConversionAdjustmentUploadService"
    )
    request = client.get_type("UploadConversionAdjustmentsRequest")
    request.customer_id = customer_id
    request.conversion_adjustments = [conversion_adjustment]
    request.partial_failure = True
    response = (
        conversion_adjustment_upload_service.upload_conversion_adjustments(
            request=request,
        )
    )
    conversion_adjustment_result = response.results[0]
    print(
        f"Uploaded conversion that occurred at "
        f'"{conversion_adjustment_result.adjustment_date_time}" '
        f"from Gclid "
        f'"{conversion_adjustment_result.gclid_date_time_pair.gclid}"'
        f' to "{conversion_adjustment_result.conversion_action}"'
    )
upload_conversion_adjustment.py
      

Ruby

def upload_conversion_adjustment(
  customer_id,
  conversion_action_id,
  gclid,
  adjustment_type,
  conversion_date_time,
  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

  # Associate conversion adjustments with the existing conversion action.
  # The GCLID should have been uploaded before with a 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.gclid_date_time_pair = client.resource.gclid_date_time_pair do |gdtp|
      gdtp.gclid = gclid
      gdtp.conversion_date_time = conversion_date_time
    end
    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 at #{result.adjustment_date_time} " \
      "for adjustment #{result.adjustment_type} to #{result.conversion_action}."
    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|
        puts "\t#{error.error_code.error_code}: #{error.message}"
      end
    end
  end
end
upload_conversion_adjustment.rb
      

Perl

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

  # Associate conversion adjustments with the existing conversion action.
  # The GCLID should have been uploaded before with a 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,
      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 Google Click ID '%s'.\n",
      $uploaded_conversion_adjustment->{conversionAction},
      $uploaded_conversion_adjustment->{gclidDateTimePair}{gclid};
  }

  return 1;
}
upload_conversion_adjustment.pl
      

Voraussetzungen

Im Folgenden sind einige Anforderungen und Einschränkungen aufgeführt, die beim Anpassen von Conversions in der API zu beachten sind:

• Anpassungen können nur über das Konto hochgeladen werden, über das Conversion-Aktionen verwaltet werden. Bestimmen Sie anhand der Anleitung zum Einrichten des Conversion-Trackings, über welches Konto Conversions für Ihr Google Ads-Konto verwaltet werden.

  Der Versuch, eine Anpassung mit einem anderen Konto hochzuladen, führt zum Fehler NO_CONVERSION_ACTION_FOUND. Dieser Fehler tritt auch auf, wenn die Conversion-Aktion der Anpassung nicht aktiviert ist.

• In Google Ads wird die Anpassung von Conversions nur für die Conversion-Aktionstypen SALESFORCE, UPLOAD_CLICKS oder WEBPAGE unterstützt. Wenn Sie versuchen, eine Anpassung für eine Conversion hochzuladen, bei der die Conversion-Aktion nicht einem dieser Typen entspricht, wird der Fehler INVALID_CONVERSION_ACTION_TYPE ausgegeben.

• Für die Felder mit Datum und Uhrzeit ist eine Zeitzone erforderlich, die nicht die des Kontos sein muss. Das Format dieser Felder ist yyyy-mm-dd HH:mm:ss+|-HH:mm, z. B. 2022-01-01 19:32:45-05:00 (ohne Sommerzeit).

• Warten Sie nach dem Erstellen der Conversion-Aktion 4 bis 6 Stunden, bevor Sie die Conversions anpassen. So können Sie den Fehler TOO_RECENT_CONVERSION_ACTION vermeiden.

• Die Anpassung schlägt mit dem Fehler CONVERSION_NOT_FOUND fehl, wenn eine der folgenden Bedingungen erfüllt ist:

  • Die Conversion wurde nie erfasst.

  • Die Conversion wurde weniger als 24 Stunden vor dem Anpassungsversuch erfasst. In einigen Situationen kann dies stattdessen zum Fehler TOO_RECENT_CONVERSION führen.

• Unter jeder der folgenden Bedingungen müssen Sie die order_id in der ConversionAdjustment angeben:

  • „type“ der Conversion-Aktion entspricht „WEBPAGE“.

  • Der ursprünglichen Conversion, die Sie anpassen, wurde eine order_id zugewiesen.

  Wenn Sie stattdessen gclid_date_time_pair angeben, schlägt der Vorgang mit dem Fehler ConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE bzw. ConversionAdjustmentUploadError.CONVERSION_NOT_FOUND fehl.

• Beim Erstellen einer ConversionAdjustment sollte das Attribut partial_failure der UploadConversionAdjustmentsRequest immer auf true festgelegt werden. Beachten Sie die Richtlinien für partielle Fehler, wenn Sie gültige und fehlgeschlagene Vorgänge gleichzeitig handhaben.

• Sie können ConversionAction nicht mit einer Anpassung ändern. Verwenden Sie stattdessen RETRACTION, um die vorherige Conversion zu entfernen und eine neue Conversion mit der aktualisierten ConversionAction hochzuladen. Der Zeitstempel muss nicht geändert werden. Weitere Informationen finden Sie unter Conversion-Anpassungen.