تحميل تسويات الإحالات الناجحة

بعد الإبلاغ عن إحالة ناجحة في "إعلانات Google"، يمكنك تعديل الإحالة الناجحة في وقت لاحق في Google Ads API.

لتعديل إحالة ناجحة، عليك أولاً إعداد إجراء إحالة ناجحة، ويجب أيضًا أن تكون قد سجّلت الإحالات الناجحة التي توشك على تعديلها.

مثال الرمز البرمجي

تتيح Google Ads API استخدام السمة order_id، المعروفة أيضًا باسم معرّف المعاملة، لتحديد الإحالة الناجحة التي يجب تعديلها مع ConversionAdjustmentUploadService.

للحصول على conversion_action_id المطلوبة لإجراء تعديل إحالة ناجحة، يمكنك تنفيذ أحد الإجراءات التالية:

  • يمكنك الحصول على القيمة من المَعلمة ctId المتاحة في عنوان URL عند النقر على تفاصيل الإحالة الناجحة في واجهة مستخدم "إعلانات Google".

  • يمكنك إجراء طلب بحث في Google Ads API لـ conversion_action.id في تقرير 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());
      }
    }
  }
}
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

المتطلّبات

في ما يلي بعض المتطلبات والقيود التي يجب أخذها في الاعتبار أثناء تعديل الإحالات الناجحة في واجهة برمجة التطبيقات:

  • يمكن فقط للحساب الذي يدير إجراءات الإحالات الناجحة تحميل التعديلات. استخدِم تعليمات إعداد تتبُّع الإحالات الناجحة لتحديد الحساب الذي يدير الإحالات الناجحة لحسابك على "إعلانات 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 المعدّل. ولا يلزم تعديل الطابع الزمني. اطّلِع على لمحة عن تعديلات الإحالات الناجحة.

السابق
تحديد المشاكل وحلّها
التالي
قواعد قيمة الإحالة الناجحة