بارگذاری کلیک کنید تبدیل

می‌توانید از Google Ads API برای آپلود تبدیل‌های کلیک آفلاین در Google Ads استفاده کنید تا تبلیغاتی را که منجر به فروش در دنیای آفلاین شده‌اند، مانند تلفن یا از طریق یک نماینده فروش، ردیابی کنید.

برپایی

چند پیش نیاز برای تنظیم تبدیل آفلاین وجود دارد. قبل از اقدام به اجرا مطمئن شوید که همه پیش نیازها برآورده شده اند:

  1. ردیابی تبدیل را در مشتری تبدیل Google Ads خود فعال کنید.

  2. برچسب‌گذاری را پیکربندی کنید و شناسه‌های کلیک را ذخیره کنید.

1. ردیابی تبدیل را در مشتری تبدیل Google Ads خود فعال کنید

اگر راهنمای شروع تبدیل را تکمیل کرده اید و ردیابی تبدیل را فعال کرده اید، می توانید به مرحله دو بروید: پیکربندی برچسب گذاری .

اطلاعات مربوط به تنظیمات ردیابی تبدیل خود را بازیابی کنید

می‌توانید تنظیمات ردیابی تبدیل حساب خود را بررسی کنید و با جستجو در منبع Customer برای ConversionTrackingSetting ، تأیید کنید که ردیابی تبدیل فعال است. درخواست زیر را با GoogleAdsService.SearchStream صادر کنید:

SELECT
  customer.conversion_tracking_setting.google_ads_conversion_customer,
  customer.conversion_tracking_setting.conversion_tracking_status,
  customer.conversion_tracking_setting.conversion_tracking_id,
  customer.conversion_tracking_setting.cross_account_conversion_tracking_id
FROM customer

فیلد google_ads_conversion_customer حساب Google Ads را نشان می‌دهد که تبدیل‌ها را برای این مشتری ایجاد و مدیریت می‌کند. برای مشتریانی که از ردیابی تبدیل بین حساب‌ها استفاده می‌کنند، این شناسه یک حساب مدیر است. شناسه مشتری تبدیل Google Ads باید به عنوان customer_id در درخواست‌های Google Ads API برای ایجاد و مدیریت تبدیل‌ها ارائه شود. توجه داشته باشید که حتی اگر ردیابی تبدیل فعال نباشد، این قسمت پر است.

فیلد conversion_tracking_status نشان می‌دهد که آیا ردیابی تبدیل فعال است و آیا حساب از ردیابی تبدیل بین حساب‌ها استفاده می‌کند یا خیر.

یک اقدام تبدیل تحت مشتری تبدیل Google Ads ایجاد کنید

اگر مقدار conversion_tracking_status NOT_CONVERSION_TRACKED باشد، ردیابی تبدیل برای حساب فعال نیست. با ایجاد حداقل یک ConversionAction در حساب تبدیل Google Ads، مانند مثال زیر، ردیابی تبدیل را فعال کنید. همچنین، می‌توانید با دنبال کردن دستورالعمل‌های موجود در مرکز راهنمایی برای نوع تبدیلی که می‌خواهید فعال کنید، یک اقدام تبدیل در رابط کاربری ایجاد کنید.

توجه داشته باشید که وقتی از طریق Google Ads API ارسال می‌شود، تبدیل‌های پیشرفته به‌طور خودکار فعال می‌شوند، اما می‌توان آن‌ها را از طریق رابط کاربری Google Ads غیرفعال کرد.

نمونه کد

جاوا

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {

  // Creates a ConversionAction.
  ConversionAction conversionAction =
      ConversionAction.newBuilder()
          // Note that conversion action names must be unique. If a conversion action already
          // exists with the specified conversion_action_name the create operation will fail with
          // a ConversionActionError.DUPLICATE_NAME error.
          .setName("Earth to Mars Cruises Conversion #" + getPrintableDateTime())
          .setCategory(ConversionActionCategory.DEFAULT)
          .setType(ConversionActionType.WEBPAGE)
          .setStatus(ConversionActionStatus.ENABLED)
          .setViewThroughLookbackWindowDays(15L)
          .setValueSettings(
              ValueSettings.newBuilder()
                  .setDefaultValue(23.41)
                  .setAlwaysUseDefaultValue(true)
                  .build())
          .build();

  // Creates the operation.
  ConversionActionOperation operation =
      ConversionActionOperation.newBuilder().setCreate(conversionAction).build();

  try (ConversionActionServiceClient conversionActionServiceClient =
      googleAdsClient.getLatestVersion().createConversionActionServiceClient()) {
    MutateConversionActionsResponse response =
        conversionActionServiceClient.mutateConversionActions(
            Long.toString(customerId), Collections.singletonList(operation));
    System.out.printf("Added %d conversion actions:%n", response.getResultsCount());
    for (MutateConversionActionResult result : response.getResultsList()) {
      System.out.printf(
          "New conversion action added with resource name: '%s'%n", result.getResourceName());
    }
  }
}
AddConversionAction.java

سی شارپ

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V16.ConversionActionService);

    // Note that conversion action names must be unique.
    // If a conversion action already exists with the specified name the create operation
    // will fail with a ConversionAction.DUPLICATE_NAME error.
    string ConversionActionName = "Earth to Mars Cruises Conversion #"
        + ExampleUtilities.GetRandomString();

    // Add a conversion action.
    ConversionAction conversionAction = new ConversionAction()
    {
        Name = ConversionActionName,
        Category = ConversionActionCategory.Default,
        Type = ConversionActionType.Webpage,
        Status = ConversionActionStatus.Enabled,
        ViewThroughLookbackWindowDays = 15,
        ValueSettings = new ConversionAction.Types.ValueSettings()
        {
            DefaultValue = 23.41,
            AlwaysUseDefaultValue = true
        }
    };

    // Create the operation.
    ConversionActionOperation operation = new ConversionActionOperation()
    {
        Create = conversionAction
    };

    try
    {
        // Create the conversion action.
        MutateConversionActionsResponse response =
            conversionActionService.MutateConversionActions(customerId.ToString(),
                    new ConversionActionOperation[] { operation });

        // Display the results.
        foreach (MutateConversionActionResult newConversionAction in response.Results)
        {
            Console.WriteLine($"New conversion action with resource name = " +
                $"'{newConversionAction.ResourceName}' was added.");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
AddConversionAction.cs

PHP

public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    // Creates a conversion action.
    $conversionAction = new ConversionAction([
        // Note that conversion action names must be unique.
        // If a conversion action already exists with the specified conversion_action_name
        // the create operation will fail with a ConversionActionError.DUPLICATE_NAME error.
        'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(),
        'category' => ConversionActionCategory::PBDEFAULT,
        'type' => ConversionActionType::WEBPAGE,
        'status' => ConversionActionStatus::ENABLED,
        'view_through_lookback_window_days' => 15,
        'value_settings' => new ValueSettings([
            'default_value' => 23.41,
            'always_use_default_value' => true
        ])
    ]);

    // Creates a conversion action operation.
    $conversionActionOperation = new ConversionActionOperation();
    $conversionActionOperation->setCreate($conversionAction);

    // Issues a mutate request to add the conversion action.
    $conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient();
    $response = $conversionActionServiceClient->mutateConversionActions(
        MutateConversionActionsRequest::build($customerId, [$conversionActionOperation])
    );

    printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL);

    foreach ($response->getResults() as $addedConversionAction) {
        /** @var ConversionAction $addedConversionAction */
        printf(
            "New conversion action added with resource name: '%s'%s",
            $addedConversionAction->getResourceName(),
            PHP_EOL
        );
    }
}
AddConversionAction.php

پایتون

def main(client, customer_id):
    conversion_action_service = client.get_service("ConversionActionService")

    # Create the operation.
    conversion_action_operation = client.get_type("ConversionActionOperation")

    # Create conversion action.
    conversion_action = conversion_action_operation.create

    # Note that conversion action names must be unique. If a conversion action
    # already exists with the specified conversion_action_name, the create
    # operation will fail with a ConversionActionError.DUPLICATE_NAME error.
    conversion_action.name = f"Earth to Mars Cruises Conversion {uuid.uuid4()}"
    conversion_action.type_ = (
        client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS
    )
    conversion_action.category = (
        client.enums.ConversionActionCategoryEnum.DEFAULT
    )
    conversion_action.status = client.enums.ConversionActionStatusEnum.ENABLED
    conversion_action.view_through_lookback_window_days = 15

    # Create a value settings object.
    value_settings = conversion_action.value_settings
    value_settings.default_value = 15.0
    value_settings.always_use_default_value = True

    # Add the conversion action.
    conversion_action_response = (
        conversion_action_service.mutate_conversion_actions(
            customer_id=customer_id,
            operations=[conversion_action_operation],
        )
    )

    print(
        "Created conversion action "
        f'"{conversion_action_response.results[0].resource_name}".'
    )
add_conversion_action.py

روبی

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


  # Add a conversion action.
  conversion_action = client.resource.conversion_action do |ca|
    ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}"
    ca.type = :UPLOAD_CLICKS
    ca.category = :DEFAULT
    ca.status = :ENABLED
    ca.view_through_lookback_window_days = 15

    # Create a value settings object.
    ca.value_settings = client.resource.value_settings do |vs|
      vs.default_value = 15
      vs.always_use_default_value = true
    end
  end

  # Create the operation.
  conversion_action_operation = client.operation.create_resource.conversion_action(conversion_action)

  # Add the ad group ad.
  response = client.service.conversion_action.mutate_conversion_actions(
    customer_id: customer_id,
    operations: [conversion_action_operation],
  )

  puts "New conversion action with resource name = #{response.results.first.resource_name}."
end
add_conversion_action.rb

پرل

sub add_conversion_action {
  my ($api_client, $customer_id) = @_;

  # Note that conversion action names must be unique.
  # If a conversion action already exists with the specified conversion_action_name,
  # the create operation fails with error ConversionActionError.DUPLICATE_NAME.
  my $conversion_action_name = "Earth to Mars Cruises Conversion #" . uniqid();

  # Create a conversion action.
  my $conversion_action =
    Google::Ads::GoogleAds::V16::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V16::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V16::Services::ConversionActionService::ConversionActionOperation
    ->new({create => $conversion_action});

  # Add the conversion action.
  my $conversion_actions_response =
    $api_client->ConversionActionService()->mutate({
      customerId => $customer_id,
      operations => [$conversion_action_operation]});

  printf "New conversion action added with resource name: '%s'.\n",
    $conversion_actions_response->{results}[0]{resourceName};

  return 1;
}
add_conversion_action.pl

مطمئن شوید که conversion_action_type روی مقدار ConversionActionType صحیح تنظیم شده است. برای راهنمایی بیشتر در مورد ایجاد کنش‌های تبدیل در Google Ads API، به ایجاد کنش‌های تبدیل مراجعه کنید.

یک اقدام تبدیل موجود را بازیابی کنید

می‌توانید جزئیات یک اقدام تبدیل موجود را با ارسال عبارت زیر بازیابی کنید. مطمئن شوید که شناسه مشتری در درخواست روی مشتری تبدیل Google Ads که در بالا شناسایی کرده‌اید و نوع اقدام تبدیل روی مقدار ConversionActionType صحیح تنظیم شده است.

SELECT
  conversion_action.resource_name,
  conversion_action.name,
  conversion_action.status
FROM conversion_action
WHERE conversion_action.type = 'INSERT_CONVERSION_ACTION_TYPE'

2. برچسب گذاری را پیکربندی کنید و شناسه های کلیک را ذخیره کنید

دستورالعمل‌ها را برای تأیید فعال بودن برچسب‌گذاری خودکار دنبال کنید و حساب Google Ads، وب‌سایت و سیستم ردیابی سرنخ خود را راه‌اندازی کنید تا GCLID، GBRAID، یا WBRAID هر نمایش را ضبط و ذخیره کنید و برای تبلیغات خود کلیک کنید. برچسب‌گذاری خودکار به‌طور پیش‌فرض برای حساب‌های جدید فعال است.

درخواست را بسازید

دستورالعمل زیر را دنبال کنید تا UploadClickConversionsRequest خود را بسازید و فیلدهای آن را روی مقادیر مناسب تنظیم کنید.

customer_id

حساب Google Ads آپلود شما را مشخص می کند. این را روی مشتری تبدیل Google Ads حسابی که منبع کلیک‌ها است، تنظیم کنید.

job_id

مکانیزمی برای مرتبط کردن درخواست‌های آپلود شما با اطلاعات هر شغل در تشخیص داده‌های آفلاین ارائه می‌کند.

اگر این فیلد را تنظیم نکنید، API Google Ads به هر درخواست یک مقدار منحصر به فرد در محدوده [2^31, 2^63) اختصاص می دهد. اگر ترجیح می دهید چندین درخواست را در یک کار منطقی واحد گروه بندی کنید، این فیلد را روی همان مقدار در محدوده [0, 2^31) برای هر درخواست در شغل خود تنظیم کنید.

job_id در پاسخ حاوی شناسه شغلی درخواست است، صرف نظر از اینکه مقداری را مشخص کرده‌اید یا به API Google Ads اجازه داده‌اید مقداری را اختصاص دهد.

partial_failure_enabled

نحوه برخورد API Google Ads با خطاهای عملیات را تعیین می کند.

این فیلد باید روی true تنظیم شود. هنگام پردازش پاسخ ، دستورالعمل‌های شکست جزئی را دنبال کنید.

debug_enabled

رفتار گزارش خطا را برای تبدیل‌های پیشرفته برای بارگذاری‌های سرنخ تعیین می‌کند. Google Ads API این فیلد را هنگام مدیریت آپلودها برای تبدیل کلیک با استفاده از gclid , gbraid , یا wbraid نادیده می گیرد.

عملیات تبدیل کلیک ایجاد کنید

مجموعه اشیاء ClickConversion در UploadClickConversionRequest شما، مجموعه تبدیل‌هایی را که می‌خواهید آپلود کنید، تعریف می‌کند. برای ساختن هر ClickConversion و تنظیم فیلدهای آن روی مقادیر مناسب، راهنمایی زیر را دنبال کنید.

فیلدهای مورد نیاز هر عملیات تبدیل را تنظیم کنید

دستورالعمل های زیر را دنبال کنید تا فیلدهای مورد نیاز ClickConversion را روی مقادیر مناسب تنظیم کنید.

gclid ، gbraid ، wbraid
شناسه‌ای که در زمان کلیک برای کلیک یا نمایش تبدیل گرفته‌اید. فقط یکی از این فیلدها را تنظیم کنید.
conversion_date_time

تاریخ و زمان تبدیل.

مقدار باید دارای منطقه زمانی مشخص شده باشد، و قالب باید yyyy-mm-dd HH:mm:ss+|-HH:mm باشد، برای مثال: 2022-01-01 19:32:45-05:00 (با نادیده گرفتن صرفه جویی در روز زمان) .

منطقه زمانی می تواند برای هر مقدار معتبری باشد: لازم نیست با منطقه زمانی حساب مطابقت داشته باشد. با این حال، اگر قصد دارید داده‌های تبدیل آپلود شده خود را با داده‌های موجود در رابط کاربری Google Ads مقایسه کنید، توصیه می‌کنیم از همان منطقه زمانی حساب Google Ads خود استفاده کنید تا تعداد تبدیل‌ها مطابقت داشته باشند. می‌توانید جزئیات و نمونه‌های بیشتری را در مرکز راهنمایی بیابید و کدها و قالب‌ها را برای فهرستی از شناسه‌های منطقه زمانی معتبر بررسی کنید.

user_identifiers

این فیلد را هنگام آپلود تبدیل فقط با استفاده از شناسه های کلیک تنظیم نکنید. اگر این فیلد تنظیم شده باشد، Google Ads عملیات آپلود را به عنوان آپلود برای تبدیل‌های پیشرفته برای سرنخ‌ها در نظر می‌گیرد.

conversion_action

نام منبع ConversionAction برای تبدیل کلیک.

اقدام تبدیل باید دارای یک type UPLOAD_CLICKS باشد و باید در مشتری تبدیل Google Ads حساب Google Ads مرتبط با کلیک وجود داشته باشد.

conversion_value

ارزش تبدیل.

currency_code

کد ارز conversion_value .

فیلدهای اختیاری هر عملیات تبدیل را تنظیم کنید

لیست فیلدهای اختیاری زیر را مرور کنید و در صورت نیاز آنها را روی ClickConversion خود تنظیم کنید.

order_id
شناسه تراکنش برای تبدیل. این قسمت اختیاری است اما به شدت توصیه می شود. اگر آن را در حین آپلود تنظیم کردید، باید برای هر گونه تنظیماتی که در تبدیل انجام شده است از آن استفاده کنید.
external_attribution_data

اگر از ابزارهای شخص ثالث یا راه‌حل‌های داخلی برای ردیابی تبدیل‌ها استفاده می‌کنید، ممکن است بخواهید فقط بخشی از اعتبار تبدیل را به Google Ads بدهید، یا ممکن است بخواهید اعتبار یک تبدیل را بین چند کلیک تقسیم کنید. واردات تبدیل منتسب به خارج به شما امکان می‌دهد تبدیل‌ها را با اعتبار کسری که به هر کلیک اختصاص داده شده است، آپلود کنید.

برای آپلود اعتبار کسری، این فیلد را روی یک شی ExternalAttributionData با مقادیر external_attribution_model و external_attribution_credit تنظیم کنید.

custom_variables

مقادیر متغیرهای تبدیل سفارشی .

Google Ads از متغیرهای تبدیل سفارشی در ترکیب با wbraid یا gbraid پشتیبانی نمی کند.

cart_data

می توانید اطلاعات سبد خرید را برای یک ClickConversion در قسمت cart_data قرار دهید که شامل ویژگی های زیر است:

  • merchant_id : شناسه حساب Merchant Center مرتبط.
  • feed_country_code : کد منطقه دو نویسه ISO 3166 فید Merchant Center.
  • feed_language_code : کد زبان ISO 639-1 فید Merchant Center.
  • local_transaction_cost : مجموع همه تخفیف‌های سطح تراکنش، در currency_code ClickConversion .
  • items : اقلام موجود در سبد خرید.

هر مورد در items از ویژگی های زیر تشکیل شده است:

  • product_id : شناسه محصول، که گاهی اوقات به عنوان شناسه پیشنهاد یا شناسه کالا از آن یاد می شود.
  • quantity : مقدار مورد.
  • unit_price : قیمت واحد کالا.
conversion_environment

محیطی که این تبدیل در آن ثبت شده را نشان می دهد. به عنوان مثال، برنامه یا وب.

نمونه کد

جاوا

private void runExample(
    GoogleAdsClient googleAdsClient,
    long customerId,
    long conversionActionId,
    String gclid,
    String gbraid,
    String wbraid,
    String conversionDateTime,
    Double conversionValue,
    Long conversionCustomVariableId,
    String conversionCustomVariableValue,
    String orderId,
    ConsentStatus adUserDataConsent)
    throws InvalidProtocolBufferException {
  // Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
  // See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
  long numberOfIdsSpecified =
      Arrays.asList(gclid, gbraid, wbraid).stream().filter(idField -> idField != null).count();
  if (numberOfIdsSpecified != 1) {
    throw new IllegalArgumentException(
        "Exactly 1 of gclid, gbraid, or wbraid is required, but "
            + numberOfIdsSpecified
            + " ID values were provided");
  }

  // Constructs the conversion action resource name from the customer and conversion action IDs.
  String conversionActionResourceName =
      ResourceNames.conversionAction(customerId, conversionActionId);

  // Creates the click conversion.
  ClickConversion.Builder clickConversionBuilder =
      ClickConversion.newBuilder()
          .setConversionAction(conversionActionResourceName)
          .setConversionDateTime(conversionDateTime)
          .setConversionValue(conversionValue)
          .setCurrencyCode("USD");

  // Sets the single specified ID field.
  if (gclid != null) {
    clickConversionBuilder.setGclid(gclid);
  } else if (gbraid != null) {
    clickConversionBuilder.setGbraid(gbraid);
  } else {
    clickConversionBuilder.setWbraid(wbraid);
  }

  if (conversionCustomVariableId != null && conversionCustomVariableValue != null) {
    // Sets the custom variable and value, if provided.
    clickConversionBuilder.addCustomVariables(
        CustomVariable.newBuilder()
            .setConversionCustomVariable(
                ResourceNames.conversionCustomVariable(customerId, conversionCustomVariableId))
            .setValue(conversionCustomVariableValue));
  }

  if (orderId != null) {
    // Sets the order ID (unique transaction ID), if provided.
    clickConversionBuilder.setOrderId(orderId);
  }

  // Sets the consent information, if provided.
  if (adUserDataConsent != null) {
    // Specifies whether user consent was obtained for the data you are uploading. See
    // https://www.google.com/about/company/user-consent-policy for details.
    clickConversionBuilder.setConsent(Consent.newBuilder().setAdUserData(adUserDataConsent));
  }
  ClickConversion clickConversion = clickConversionBuilder.build();

  // Creates the conversion upload service client.
  try (ConversionUploadServiceClient conversionUploadServiceClient =
      googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) {
    // Uploads the click conversion. Partial failure should always be set to true.

    // NOTE: This request contains a single conversion as a demonstration.  However, if you have
    // multiple conversions to upload, it's best to upload multiple conversions per request
    // instead of sending a separate request per conversion. See the following for per-request
    // limits:
    // https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
    UploadClickConversionsResponse response =
        conversionUploadServiceClient.uploadClickConversions(
            UploadClickConversionsRequest.newBuilder()
                .setCustomerId(Long.toString(customerId))
                .addConversions(clickConversion)
                // Enables partial failure (must be true).
                .setPartialFailure(true)
                .build());

    // Prints any partial errors returned.
    if (response.hasPartialFailureError()) {
      GoogleAdsFailure googleAdsFailure =
          ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
      // Constructs a protocol buffer printer that will print error details in a concise format.
      Printer errorPrinter = JsonFormat.printer().omittingInsignificantWhitespace();
      for (int operationIndex = 0;
          operationIndex < response.getResultsCount();
          operationIndex++) {
        ClickConversionResult conversionResult = response.getResults(operationIndex);
        if (ErrorUtils.getInstance().isPartialFailureResult(conversionResult)) {
          // Prints the errors for the failed operation.
          System.out.printf("Operation %d failed with the following errors:%n", operationIndex);
          for (GoogleAdsError resultError :
              ErrorUtils.getInstance().getGoogleAdsErrors(operationIndex, googleAdsFailure)) {
            // Prints the error with newlines and extra spaces removed.
            System.out.printf("  %s%n", errorPrinter.print(resultError));
          }
        } else {
          // Prints the information about the successful operation.
          StringBuilder clickInfoBuilder =
              new StringBuilder("conversion that occurred at ")
                  .append(String.format("'%s' ", conversionResult.getConversionDateTime()))
                  .append("with ");
          if (conversionResult.hasGclid()) {
            clickInfoBuilder.append(String.format("gclid '%s'", conversionResult.getGclid()));
          } else if (!conversionResult.getGbraid().isEmpty()) {
            clickInfoBuilder.append(String.format("gbraid '%s'", conversionResult.getGbraid()));
          } else if (!conversionResult.getWbraid().isEmpty()) {
            clickInfoBuilder.append(String.format("wbraid '%s'", conversionResult.getWbraid()));
          } else {
            clickInfoBuilder.append("no click ID");
          }
          System.out.printf("Operation %d for %s succeeded.%n", operationIndex, clickInfoBuilder);
        }
      }
    }
  }
}
UploadOfflineConversion.java

سی شارپ

public void Run(GoogleAdsClient client, long customerId, long conversionActionId,
    string gclid, string gbraid, string wbraid, string conversionTime,
    double conversionValue, ConsentStatus? adUserDataConsent)
{
    // Get the ConversionActionService.
    ConversionUploadServiceClient conversionUploadService =
        client.GetService(Services.V16.ConversionUploadService);

    // Creates a click conversion by specifying currency as USD.
    ClickConversion clickConversion = new ClickConversion()
    {
        ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
        ConversionValue = conversionValue,
        ConversionDateTime = conversionTime,
        CurrencyCode = "USD",
    };

    // Sets the consent information, if provided.
    if (adUserDataConsent != null)
    {
        // Specifies whether user consent was obtained for the data you are uploading. See
        // https://www.google.com/about/company/user-consent-policy
        // for details.
        clickConversion.Consent = new Consent()
        {
            AdUserData = (ConsentStatus)adUserDataConsent
        };
    }

    // Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
    // See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks
    // for details.
    string[] ids = { gclid, gbraid, wbraid };
    int idCount = ids.Where(id => !string.IsNullOrEmpty(id)).Count();

    if (idCount != 1)
    {
        throw new ArgumentException($"Exactly 1 of gclid, gbraid, or wbraid is " +
            $"required, but {idCount} ID values were provided");
    }

    // Sets the single specified ID field.
    if (!string.IsNullOrEmpty(gclid))
    {
        clickConversion.Gclid = gclid;
    }
    else if (!string.IsNullOrEmpty(wbraid))
    {
        clickConversion.Wbraid = wbraid;
    }
    else if (!string.IsNullOrEmpty(gbraid))
    {
        clickConversion.Gbraid = gbraid;
    }

    try
    {
        // Issues a request to upload the click conversion.
        UploadClickConversionsResponse response =
            conversionUploadService.UploadClickConversions(
                new UploadClickConversionsRequest()
                {
                    CustomerId = customerId.ToString(),
                    Conversions = { clickConversion },
                    PartialFailure = true,
                    ValidateOnly = false
                });

        // Prints the result.
        ClickConversionResult uploadedClickConversion = response.Results[0];
        Console.WriteLine($"Uploaded conversion that occurred at " +
            $"'{uploadedClickConversion.ConversionDateTime}' from Google " +
            $"Click ID '{uploadedClickConversion.Gclid}' to " +
            $"'{uploadedClickConversion.ConversionAction}'.");
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
UploadOfflineConversion.cs

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $conversionActionId,
    ?string $gclid,
    ?string $gbraid,
    ?string $wbraid,
    ?string $orderId,
    string $conversionDateTime,
    float $conversionValue,
    ?string $conversionCustomVariableId,
    ?string $conversionCustomVariableValue,
    ?int $adUserDataConsent
) {
    // Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
    // See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
    $nonNullFields = array_filter(
        [$gclid, $gbraid, $wbraid],
        function ($field) {
            return !is_null($field);
        }
    );
    if (count($nonNullFields) !== 1) {
        throw new \UnexpectedValueException(
            sprintf(
                "Exactly 1 of gclid, gbraid or wbraid is required, but %d ID values were "
                . "provided",
                count($nonNullFields)
            )
        );
    }

    // Creates a click conversion by specifying currency as USD.
    $clickConversion = new ClickConversion([
        'conversion_action' =>
            ResourceNames::forConversionAction($customerId, $conversionActionId),
        'conversion_value' => $conversionValue,
        'conversion_date_time' => $conversionDateTime,
        'currency_code' => 'USD'
    ]);
    // Sets the single specified ID field.
    if (!is_null($gclid)) {
        $clickConversion->setGclid($gclid);
    } elseif (!is_null($gbraid)) {
        $clickConversion->setGbraid($gbraid);
    } else {
        $clickConversion->setWbraid($wbraid);
    }

    if (!is_null($conversionCustomVariableId) && !is_null($conversionCustomVariableValue)) {
        $clickConversion->setCustomVariables([new CustomVariable([
            'conversion_custom_variable' => ResourceNames::forConversionCustomVariable(
                $customerId,
                $conversionCustomVariableId
            ),
            'value' => $conversionCustomVariableValue
        ])]);
    }
    // Sets the consent information, if provided.
    if (!empty($adUserDataConsent)) {
        // Specifies whether user consent was obtained for the data you are uploading. See
        // https://www.google.com/about/company/user-consent-policy for details.
        $clickConversion->setConsent(new Consent(['ad_user_data' => $adUserDataConsent]));
    }

    if (!empty($orderId)) {
        // Sets the order ID (unique transaction ID), if provided.
        $clickConversion->setOrderId($orderId);
    }

    // Issues a request to upload the click conversion.
    $conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
    /** @var UploadClickConversionsResponse $response */
    // NOTE: This request contains a single conversion as a demonstration.  However, if you have
    // multiple conversions to upload, it's best to upload multiple conversions per request
    // instead of sending a separate request per conversion. See the following for per-request
    // limits:
    // https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
    $response = $conversionUploadServiceClient->uploadClickConversions(
        // Uploads the click conversion. Partial failure should always be set to true.
        UploadClickConversionsRequest::build($customerId, [$clickConversion], 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 ClickConversionResult $uploadedClickConversion */
        $uploadedClickConversion = $response->getResults()[0];
        printf(
            "Uploaded click conversion that occurred at '%s' from Google Click ID '%s' " .
            "to '%s'.%s",
            $uploadedClickConversion->getConversionDateTime(),
            $uploadedClickConversion->getGclid(),
            $uploadedClickConversion->getConversionAction(),
            PHP_EOL
        );
    }
}
UploadOfflineConversion.php

پایتون

def main(
    client,
    customer_id,
    conversion_action_id,
    gclid,
    conversion_date_time,
    conversion_value,
    conversion_custom_variable_id,
    conversion_custom_variable_value,
    gbraid,
    wbraid,
    order_id,
    ad_user_data_consent,
):
    """Creates a click conversion with a default currency of USD.

    Args:
        client: An initialized GoogleAdsClient instance.
        customer_id: The client customer ID string.
        conversion_action_id: The ID of the conversion action to upload to.
        gclid: The Google Click Identifier ID. If set, the wbraid and gbraid
            parameters must be None.
        conversion_date_time: The the date and time of the conversion (should be
            after the click time). The format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm',
            e.g. '2021-01-01 12:32:45-08:00'.
        conversion_value: The conversion value in the desired currency.
        conversion_custom_variable_id: The ID of the conversion custom
            variable to associate with the upload.
        conversion_custom_variable_value: The str value of the conversion custom
            variable to associate with the upload.
        gbraid: The GBRAID for the iOS app conversion. If set, the gclid and
            wbraid parameters must be None.
        wbraid: The WBRAID for the iOS app conversion. If set, the gclid and
            gbraid parameters must be None.
        order_id: The order ID for the click conversion.
        ad_user_data_consent: The ad user data consent for the click.
    """
    click_conversion = client.get_type("ClickConversion")
    conversion_upload_service = client.get_service("ConversionUploadService")
    conversion_action_service = client.get_service("ConversionActionService")
    click_conversion.conversion_action = (
        conversion_action_service.conversion_action_path(
            customer_id, conversion_action_id
        )
    )

    # Sets the single specified ID field.
    if gclid:
        click_conversion.gclid = gclid
    elif gbraid:
        click_conversion.gbraid = gbraid
    else:
        click_conversion.wbraid = wbraid

    click_conversion.conversion_value = float(conversion_value)
    click_conversion.conversion_date_time = conversion_date_time
    click_conversion.currency_code = "USD"

    if conversion_custom_variable_id and conversion_custom_variable_value:
        conversion_custom_variable = client.get_type("CustomVariable")
        conversion_custom_variable.conversion_custom_variable = (
            conversion_upload_service.conversion_custom_variable_path(
                customer_id, conversion_custom_variable_id
            )
        )
        conversion_custom_variable.value = conversion_custom_variable_value
        click_conversion.custom_variables.append(conversion_custom_variable)

    if order_id:
        click_conversion.order_id = order_id

    # Sets the consent information, if provided.
    if ad_user_data_consent:
        # Specifies whether user consent was obtained for the data you are
        # uploading. For more details, see:
        # https://www.google.com/about/company/user-consent-policy
        click_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[
            ad_user_data_consent
        ]

    # Uploads the click conversion. Partial failure must be set to True here.
    #
    # NOTE: This request only uploads a single conversion, but if you have
    # multiple conversions to upload, it's most efficient to upload them in a
    # single request. See the following for per-request limits for reference:
    # https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
    request = client.get_type("UploadClickConversionsRequest")
    request.customer_id = customer_id
    request.conversions.append(click_conversion)
    request.partial_failure = True
    conversion_upload_response = (
        conversion_upload_service.upload_click_conversions(
            request=request,
        )
    )
    uploaded_click_conversion = conversion_upload_response.results[0]
    print(
        f"Uploaded conversion that occurred at "
        f'"{uploaded_click_conversion.conversion_date_time}" from '
        f'Google Click ID "{uploaded_click_conversion.gclid}" '
        f'to "{uploaded_click_conversion.conversion_action}"'
    )
upload_offline_conversion.py

روبی

def upload_offline_conversion(
  customer_id,
  conversion_action_id,
  gclid,
  gbraid,
  wbraid,
  conversion_date_time,
  conversion_value,
  conversion_custom_variable_id,
  conversion_custom_variable_value,
  ad_user_data_consent)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  # Verifies that exactly one of gclid, gbraid, and wbraid is specified, as required.
  # See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
  identifiers_specified = [gclid, gbraid, wbraid].reject {|v| v.nil?}.count
  if identifiers_specified != 1
    raise "Must specify exactly one of GCLID, GBRAID, and WBRAID. " \
      "#{identifiers_specified} values were provided."
  end

  click_conversion = client.resource.click_conversion do |cc|
    cc.conversion_action = client.path.conversion_action(customer_id, conversion_action_id)
    # Sets the single specified ID field.
    if !gclid.nil?
      cc.gclid = gclid
    elsif !gbraid.nil?
      cc.gbraid = gbraid
    else
      cc.wbraid = wbraid
    end
    cc.conversion_value = conversion_value.to_f
    cc.conversion_date_time = conversion_date_time
    cc.currency_code = 'USD'
    if conversion_custom_variable_id && conversion_custom_variable_value
      cc.custom_variables << client.resource.custom_variable do |cv|
        cv.conversion_custom_variable = client.path.conversion_custom_variable(
          customer_id, conversion_custom_variable_id)
        cv.value = conversion_custom_variable_value
      end
    end
    # Sets the consent information, if provided.
    unless ad_user_data_consent.nil?
      c.consent = client.resource.consent do |c|
        # Specifies whether user consent was obtained for the data you are
        # uploading. For more details, see:
        # https://www.google.com/about/company/user-consent-policy
        c.ad_user_data = ad_user_data_consent
      end
    end
  end

  response = client.service.conversion_upload.upload_click_conversions(
    customer_id: customer_id,
    # NOTE: This request contains a single conversion as a demonstration.
    # However, if you have multiple conversions to upload, it's best to upload
    # multiple conversions per request instead of sending a separate request per
    # conversion. See the following for per-request limits:
    # https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
    conversions: [click_conversion],
    partial_failure: true,
  )
  if response.partial_failure_error.nil?
    result = response.results.first
    puts "Uploaded conversion that occurred at #{result.conversion_date_time} " \
      "from Google Click ID #{result.gclid} to #{result.conversion_action}."
  else
    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_offline_conversion.rb

پرل

sub upload_offline_conversion {
  my (
    $api_client,                    $customer_id,
    $conversion_action_id,          $gclid,
    $gbraid,                        $wbraid,
    $conversion_date_time,          $conversion_value,
    $conversion_custom_variable_id, $conversion_custom_variable_value,
    $order_id,                      $ad_user_data_consent
  ) = @_;

  # Verify that exactly one of gclid, gbraid, and wbraid is specified, as required.
  # See https://developers.google.com/google-ads/api/docs/conversions/upload-clicks for details.
  my $number_of_ids_specified = grep { defined $_ } ($gclid, $gbraid, $wbraid);
  if ($number_of_ids_specified != 1) {
    die sprintf "Exactly 1 of gclid, gbraid, or wbraid is required, " .
      "but %d ID values were provided.\n",
      $number_of_ids_specified;
  }

  # Create a click conversion by specifying currency as USD.
  my $click_conversion =
    Google::Ads::GoogleAds::V16::Services::ConversionUploadService::ClickConversion
    ->new({
      conversionAction =>
        Google::Ads::GoogleAds::V16::Utils::ResourceNames::conversion_action(
        $customer_id, $conversion_action_id
        ),
      conversionDateTime => $conversion_date_time,
      conversionValue    => $conversion_value,
      currencyCode       => "USD"
    });

  # Set the single specified ID field.
  if (defined $gclid) {
    $click_conversion->{gclid} = $gclid;
  } elsif (defined $gbraid) {
    $click_conversion->{gbraid} = $gbraid;
  } else {
    $click_conversion->{wbraid} = $wbraid;
  }

  if ($conversion_custom_variable_id && $conversion_custom_variable_value) {
    $click_conversion->{customVariables} = [
      Google::Ads::GoogleAds::V16::Services::ConversionUploadService::CustomVariable
        ->new({
          conversionCustomVariable =>
            Google::Ads::GoogleAds::V16::Utils::ResourceNames::conversion_custom_variable(
            $customer_id, $conversion_custom_variable_id
            ),
          value => $conversion_custom_variable_value
        })];
  }

  if (defined $order_id) {
    # Set the order ID (unique transaction ID), if provided.
    $click_conversion->{orderId} = $order_id;
  }

  # Set the consent information, if provided.
  if ($ad_user_data_consent) {
    # Specify whether user consent was obtained for the data you are uploading.
    # See https://www.google.com/about/company/user-consent-policy for details.
    $click_conversion->{consent} =
      Google::Ads::GoogleAds::V16::Common::Consent->new({
        adUserData => $ad_user_data_consent
      });
  }

  # Issue a request to upload the click conversion. Partial failure should
  # always be set to true.
  #
  # NOTE: This request contains a single conversion as a demonstration.
  # However, if you have multiple conversions to upload, it's best to
  # upload multiple conversions per request instead of sending a separate
  # request per conversion. See the following for per-request limits:
  # https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
  my $upload_click_conversions_response =
    $api_client->ConversionUploadService()->upload_click_conversions({
      customerId     => $customer_id,
      conversions    => [$click_conversion],
      partialFailure => "true"
    });

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

  # Print the result if valid.
  my $uploaded_click_conversion =
    $upload_click_conversions_response->{results}[0];
  if (%$uploaded_click_conversion) {
    printf
      "Uploaded conversion that occurred at '%s' from Google Click ID '%s' " .
      "to the conversion action with resource name '%s'.\n",
      $uploaded_click_conversion->{conversionDateTime},
      $uploaded_click_conversion->{gclid},
      $uploaded_click_conversion->{conversionAction};
  }

  return 1;
}
upload_offline_conversion.pl

عیب یابی

تشخیص داده های آفلاین یک منبع واحد برای بررسی سلامت کلی آپلودهای شما به صورت مداوم فراهم می کند. با این حال، در حین پیاده سازی می توانید از اطلاعات این بخش برای بررسی هر گونه خطای گزارش شده در قسمت partial_failure_error پاسخ استفاده کنید.

برخی از رایج‌ترین خطاها هنگام آپلود کنش‌های تبدیل، خطاهای مجوز است، مانند USER_PERMISSION_DENIED . مجدداً بررسی کنید که شناسه مشتری در درخواستتان روی مشتری تبدیل Google Ads که مالک عمل تبدیل است تنظیم شده باشد. برای جزئیات بیشتر از راهنمای مجوز ما دیدن کنید و راهنمای خطاهای رایج ما را برای نکاتی در مورد نحوه اشکال زدایی این خطاهای مختلف ببینید.

اشکال زدایی خطاهای رایج

خطا
ConversionUploadError.INVALID_CONVERSION_ACTION_TYPE اقدام تبدیل مشخص شده دارای نوعی است که برای آپلود تبدیل کلیک معتبر نیست. مطمئن شوید که ConversionAction مشخص شده در درخواست آپلود شما دارای نوع UPLOAD_CLICKS است.
ConversionUploadError.NO_CONVERSION_ACTION_FOUND اقدام تبدیل مشخص شده یا فعال نیست یا در شناسه بارگذاری customer_id یافت نمی شود. مطمئن شوید که عمل تبدیل در آپلود شما فعال است و متعلق به customer_id درخواست آپلود است.
ConversionUploadError.TOO_RECENT_CONVERSION_ACTION عمل تبدیل به تازگی ایجاد شده است. قبل از اینکه تبدیل‌های ناموفق را دوباره امتحان کنید، حداقل 6 ساعت پس از ایجاد کنش صبر کنید.
ConversionUploadError.INVALID_CUSTOMER_FOR_CLICK customer_id درخواست همان شناسه مشتری نیست که مشتری تبدیل Google Ads در زمان کلیک بود. customer_id درخواست را به مشتری صحیح به روز کنید.
ConversionUploadError.EVENT_NOT_FOUND Google Ads نمی تواند ترکیبی از شناسه کلیک و customer_id را پیدا کند. الزامات customer_id را بررسی کنید و تأیید کنید که با استفاده از حساب Google Ads درست آپلود می‌کنید.
ConversionUploadError.DUPLICATE_CLICK_CONVERSION_IN_REQUEST تبدیل‌های چندگانه در درخواست ترکیبی یکسان از شناسه کلیک، conversion_date_time و conversion_action دارند. تبدیل های تکراری را از درخواست خود حذف کنید.
ConversionUploadError.CLICK_CONVERSION_ALREADY_EXISTS تبدیلی با همان ترکیب شناسه کلیک، conversion_date_time و conversion_action قبلا آپلود شده بود. اگر بارگذاری مجدد را امتحان می‌کردید و این تبدیل قبلاً با موفقیت انجام شده بود، این خطا را نادیده بگیرید. اگر می‌خواهید تبدیل دیگری را علاوه بر تبدیل آپلود شده قبلی اضافه کنید، conversion_date_time مربوط به ClickConversion را تنظیم کنید تا از تکرار تبدیل آپلود شده قبلی جلوگیری کنید.
ConversionUploadError.EVENT_NOT_FOUND Google Ads نمی تواند ترکیبی از شناسه کلیک و customer_id را پیدا کند. الزامات customer_id را بررسی کنید و تأیید کنید که با استفاده از حساب Google Ads درست آپلود می‌کنید.
ConversionUploadError.EXPIRED_EVENT کلیک وارد شده قبل از بازه زمانی مشخص شده در قسمت click_through_lookback_window_days رخ داده است. تغییر در click_through_lookback_window_days فقط بر کلیک‌های ثبت‌شده پس از تغییر تأثیر می‌گذارد ، بنابراین تغییر پنجره بازبینی این خطا را برای کلیک خاص برطرف نمی‌کند. در صورت لزوم، conversion_action به اکشن دیگری با یک پنجره نگاه طولانی‌تر تغییر دهید.
ConversionUploadError.CONVERSION_PRECEDES_GCLID conversion_date_time قبل از تاریخ و زمان کلیک است. conversion_date_time به مقدار بعدی به روز کنید.
ConversionUploadError.GBRAID_WBRAID_BOTH_SET ClickConversion دارای مقداری برای gbraid و wbraid است. تبدیل را به‌روزرسانی کنید تا فقط از شناسه یک کلیک استفاده کنید، و مطمئن شوید که چندین کلیک را در یک تبدیل ترکیب نمی‌کنید. هر کلیک فقط یک شناسه کلیک دارد.
FieldError.VALUE_MUST_BE_UNSET location GoogleAdsError را بررسی کنید تا مشخص شود کدام یک از مشکلات زیر منجر به این خطا شده است.
  • ClickConversion دارای مقداری برای gclid و همچنین حداقل یکی از gbraid یا wbraid است. تبدیل را به‌روزرسانی کنید تا فقط از شناسه یک کلیک استفاده کنید، و مطمئن شوید که چندین کلیک را در یک تبدیل ترکیب نمی‌کنید. هر کلیک فقط یک شناسه کلیک دارد.
  • ClickConversion دارای مقداری برای gbraid یا wbraid است و مقداری برای custom_variables دارد. Google Ads از متغیرهای سفارشی برای تبدیل با شناسه کلیک gbraid یا wbraid پشتیبانی نمی کند. فیلد custom_variables تبدیل را تنظیم نکنید.

تبدیل در گزارش ها

تبدیل‌های آپلود شده در گزارش‌های مربوط به تاریخ نمایش کلیک اصلی منعکس می‌شوند، نه تاریخ درخواست آپلود یا تاریخ conversion_date_time ClickConversion .

حداکثر 3 ساعت طول می کشد تا آمار تبدیل وارد شده در حساب Google Ads شما برای انتساب آخرین کلیک ظاهر شود. برای سایر مدل‌های ارجاع جستجو، ممکن است بیش از 3 ساعت طول بکشد. برای اطلاعات بیشتر به راهنمای تازه سازی داده ها مراجعه کنید.

قبلی
ایجاد اقدامات تبدیل
بعدی
تبدیل تماس ها را بارگذاری کنید