Conversion-Anpassungen importieren

Nachdem eine Conversion bereits an Google Ads gemeldet wurde, können Sie die Conversion später in der Google Ads API anpassen.

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

Warnung : Conversion-Anpassungen funktionieren nicht mit Conversion-Aktionen vom Typ UNKNOWN. Conversion-Anpassungen funktionieren mit GCLIDs und GBRAIDs, aber nicht mit WBRAIDs.

Codebeispiel

Die Google Ads API unterstützt die Verwendung von order_id, auch als Transaktions-ID bezeichnet, um die Conversion zu identifizieren, die mit ConversionAdjustmentUploadService angepasst werden soll.

Hinweis: Sie können die Conversion auch mit einer gclid_date_time_pair identifizieren. Dieser Ansatz ist jedoch weniger zuverlässig als die Verwendung von order_id und wird daher nicht empfohlen.

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

• Rufen Sie den Wert aus dem Parameter ctId ab, der in der URL verfügbar ist, wenn Sie in der Google Ads-Benutzeroberfläche auf Conversion-Details klicken.

• Fragen Sie die Google Ads API nach conversion_action.id im Bericht conversion_action 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 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;
    }
}
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
      

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}'."
            )
upload_conversion_adjustment.py
      

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
upload_conversion_adjustment.rb
      

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;
}
upload_conversion_adjustment.pl
      

curl

Hinweis: Für diesen Schritt wird hier kein direktes REST-Codebeispiel bereitgestellt. Sie können dies jedoch mit einer manuellen REST-Anfrage erreichen.

Weitere Informationen finden Sie in der Dokumentation zur REST-Schnittstelle der Google Ads API und auf den methodenspezifischen Referenzseiten. Sie müssen die JSON-Nutzlast anhand der Proto-Definitionen erstellen.

Wichtige Ressourcen:

• REST verwenden
• Struktur der REST-Schnittstelle
• JSON-Feldzuordnungen
• Informationen zum jeweiligen Dienst und zur Methode finden Sie in der REST API-Referenz.

Voraussetzungen

Hier sind einige Anforderungen und Einschränkungen, die Sie beim Anpassen von Conversions in der API beachten sollten:

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

  Wenn Sie versuchen, eine Anpassung über ein anderes Konto zu importieren, wird der Fehler NO_CONVERSION_ACTION_FOUND ausgegeben. Dieser Fehler tritt auch auf, wenn die Conversion-Aktion der Anpassung nicht aktiviert ist.

• In Google Ads können nur Conversions für die Conversion-Aktionstypen SALESFORCE, UPLOAD_CLICKS oder WEBPAGE angepasst werden. Wenn Sie versuchen, eine Anpassung für eine Conversion zu importieren, bei der die Conversion-Aktion nicht einem dieser Typen entspricht, wird der Fehler INVALID_CONVERSION_ACTION_TYPE ausgegeben.

• Für die Felder, in denen Datum und Uhrzeit angegeben werden, ist eine ausgewählte Zeitzone erforderlich, die sich von der Zeitzone des Kontos unterscheiden kann. Die Felder müssen im Format yyyy-mm-dd HH:mm:ss+|-HH:mm formatiert sein, z. B. 2022-01-01 19:32:45-05:00 (Sommerzeit wird ignoriert).

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

• Die Anpassung schlägt mit dem Fehler CONVERSION_NOT_FOUND fehl, wenn die Conversion nie importiert wurde oder importiert, aber verworfen wurde, weil sie als ungültig oder Spam eingestuft wurde.

• Sie müssen die order_id in der ConversionAdjustment unter einer der folgenden Bedingungen angeben:

  • Der type der Conversion-Aktion ist gleich WEBPAGE.

  • Der ursprünglichen Conversion, die Sie anpassen, wurde ein 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 eines ConversionAdjustment sollte das Attribut partial_failure des UploadConversionAdjustmentsRequest immer auf true festgelegt sein. Folgen Sie den Richtlinien für Teilausfälle, wenn Sie gültige und fehlgeschlagene Vorgänge gleichzeitig verarbeiten.

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