انضمّوا إلينا في بث مباشر على Discord على خادم Google Advertising and Measurement Community وعلى YouTube في 15 أكتوبر الساعة 10:00 صباحًا بالتوقيت الشرقي. سنتناول الميزات الجديدة التي تمت إضافتها في الإصدار 26 من Google Ads API.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

البدء

يجب تفعيل ميزة تتبُّع الإحالات الناجحة في حساب تتبّع الإحالات الناجحة على "إعلانات Google" من أجل تسجيل الإحالات الناجحة. يقدّم هذا الدليل تفاصيل حول كيفية التأكّد من تفعيل ميزة تتبُّع الإحالات الناجحة، وتفعيلها إذا لم تكن مفعّلة، واسترداد معلومات حول إجراءات الإحالات الناجحة الحالية.

تتطلّب معظم إجراءات الإحالات الناجحة أيضًا اتّخاذ خطوات إضافية من جانبك لتتبُّعها. لمزيد من المعلومات عن الأنواع المختلفة لإجراءات الإحالات الناجحة ومتطلباتها، يُرجى الاطّلاع على فئات إجراءات الإحالات الناجحة وإنشاء إجراءات الإحالات الناجحة.

الاستعداد لتقديم الموافقة

عند استيراد الإحالات الناجحة أو بيانات المستخدمين، عليك تأكيد حصولك على إذن بمشاركة بيانات الإحالات الناجحة مع Google. يمكنك إجراء ذلك بإحدى الطريقتَين التاليتَين:

اضبط إعدادات الموافقة التلقائية على مستوى الحساب. في واجهة مستخدم "إعلانات Google"، انقر على الأدوات > إدارة بيانات إعلانات Google > إعدادات الموافقة > إعدادات الموافقة التلقائية.
اضبط حقل الموافقة في كل حمولة بيانات مستورَدة للمستخدم أو الإحالة الناجحة (على سبيل المثال، ClickConversion.consent أو CallConversion.consent أو UserData.consent).

إعداد موقعك الإلكتروني لتتبُّع الإحالات الناجحة

إذا كنت تتتبّع الإحالات الناجحة على الموقع الإلكتروني أو تنفّذ ميزة الإحالات الناجحة المحسّنة للعملاء المحتملين، عليك ضبط وضع العلامات على موقعك الإلكتروني أولاً. اتّبِع الخطوات الواردة في مقالة ضبط علامة التتبُّع من Google لميزة "الإحالات الناجحة المحسّنة للعملاء المهتمين"، أو استخدِم Google Tag Manager باتّباع الخطوات الواردة في مقالة ضبط Google Tag Manager لميزة "الإحالات الناجحة المحسّنة للعملاء المهتمين".

تفعيل ميزة "تتبُّع الإحالات الناجحة" في حساب الإحالات الناجحة على "إعلانات Google"

اتّبِع الخطوات التالية للتحقّق من إعداد ميزة تتبُّع الإحالات الناجحة في حسابك وإنشاء إجراءات إحالات ناجحة أو استردادها.

خطوات تفعيل ميزة "تتبُّع الإحالات الناجحة"

استرداد معلومات عن إعداد تتبُّع الإحالات الناجحة

يمكنك الاطّلاع على إعدادات تتبُّع الإحالات الناجحة في حسابك والتأكّد من تفعيل ميزة تتبُّع الإحالات الناجحة من خلال إرسال طلب بحث عن المورد 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" الذي ينشئ الإحالات الناجحة ويديرها لهذا العميل. بالنسبة إلى العملاء الذين يستخدمون ميزة تتبُّع الإحالات الناجحة في جميع الحسابات، هذا هو رقم تعريف الحساب الإداري. يجب تقديم الرقم التعريفي لعميل الإحالة الناجحة في "إعلانات Google" على أنّه customer_id في طلبات Google Ads API لإنشاء الإحالات الناجحة وإدارتها. يُرجى العِلم أنّه تتم تعبئة هذا الحقل حتى في حال عدم تفعيل ميزة تتبُّع الإحالات الناجحة.

يشير الحقل conversion_tracking_status إلى ما إذا كانت ميزة تتبُّع الإحالات الناجحة مفعَّلة وما إذا كان الحساب يستخدِم ميزة تتبُّع الإحالات الناجحة في جميع الحسابات.

إنشاء إجراء إحالة ناجحة ضمن عميل الإحالة الناجحة في "إعلانات Google"

إذا كانت قيمة conversion_tracking_status هي NOT_CONVERSION_TRACKED، يعني ذلك أنّ ميزة تتبُّع الإحالات الناجحة غير مفعَّلة للحساب. فعِّل ميزة تتبُّع الإحالات الناجحة من خلال إنشاء ConversionAction واحد على الأقل في حساب تتبُّع الإحالات الناجحة على "إعلانات Google"، كما هو موضّح في المثال التالي. بدلاً من ذلك، يمكنك إنشاء إجراء إحالة ناجحة في واجهة المستخدِم باتّباع التعليمات الواردة في مقالة مركز مساعدة "إعلانات Google" حول إعداد ميزة تتبُّع الإحالات الناجحة لنوع الإحالة الناجحة الذي تريد تفعيله.

يُرجى العِلم أنّه يتم تفعيل ميزة "الإحالات الناجحة المحسّنة" تلقائيًا عند إرسالها من خلال Google Ads API، ولكن يمكن إيقافها من خلال واجهة مستخدم "إعلانات Google".

مثال على الرمز

جافا

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

#C

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V25.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

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    conversion_action_service: ConversionActionServiceClient = (
        client.get_service("ConversionActionService")
    )

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

    # Create conversion action.
    conversion_action: ConversionAction = 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: ConversionAction.ValueSettings = (
        conversion_action.value_settings
    )
    value_settings.default_value = 15.0
    value_settings.always_use_default_value = True

    # Add the conversion action.
    conversion_action_response: MutateConversionActionsResponse = (
        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

Ruby

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}."
endadd_conversion_action.rb

Perl

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::V25::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V25::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V25::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

curl

تأكَّد من ضبط السمة type على قيمة ConversionActionType الصحيحة. للحصول على مزيد من الإرشادات حول إنشاء إجراءات إحالات ناجحة في Google Ads API، يُرجى الاطّلاع على مقالة إنشاء إجراءات إحالات ناجحة.

استرداد إجراء إحالة ناجحة حالي

يمكنك استرداد تفاصيل إجراء إحالة ناجحة حالي من خلال إرسال الطلب التالي. تأكَّد من أنّ رقم تعريف العميل في الطلب مضبوط على عميل الإحالة الناجحة الذي حدّدته سابقًا في "إعلانات Google"، وأنّ نوع إجراء الإحالة الناجحة مضبوط على القيمة الصحيحة ConversionActionType.

SELECT
  conversion_action.id,
  conversion_action.resource_name,
  conversion_action.name,
  conversion_action.type,
  conversion_action.category,
  conversion_action.status
FROM conversion_action

WHERE conversion_action.type = 'INSERT_CONVERSION_ACTION_TYPE'

تتبّع الإحالات الناجحة في جميع الحسابات

تتيح ميزة تتبُّع الإحالات الناجحة في جميع الحسابات لحسابات "إعلانات Google" استيراد الإحالات الناجحة نيابةً عن حسابات أخرى ربما عرضت الإعلانات التي أدّت إلى إنشاء الإحالات الناجحة. يمكن أن يساعد ذلك في تبسيط عملية الدمج من خلال السماح لك بدمج الحسابات التي تُرسل طلبات الاستيراد.

تفعيل ميزة "تتبُّع الإحالات الناجحة في جميع الحسابات" في Google Ads API

يمكنك استخدام Google Ads API لتفعيل ميزة تتبُّع الإحالات الناجحة في جميع الحسابات عند إنشاء حسابات العملاء أو تعديلها.

في مورد Customer، اضبط الحقل conversion_tracking_setting.google_ads_conversion_customer على اسم مورد الحساب الإداري الذي يجب أن يدير إجراءات الإحالات الناجحة نيابةً عن حساب العميل.

يجب إرسال الطلبات التي تعدّل عميل الإحالة الناجحة لحساب عميل من خلال الحساب الإداري الذي سيصبح عميل الإحالة الناجحة الجديد للعميل. يمكنك إجراء ذلك من خلال ضبط login-customer-id على رقم تعريف الحساب الإداري.

عند تفعيل ميزة تتبُّع الإحالات الناجحة في جميع الحسابات، أو تبديل الحساب الإداري لتتبُّع الإحالات الناجحة لحساب عميل حالي، تنطبق التحذيرات نفسها كما لو كنت تُجري هذا التغيير في واجهة المستخدم. على وجه التحديد:

سيستخدم حساب العميل قواعد قيمة الإحالة الناجحة التلقائية وأهداف مراحل النشاط التلقائية لمدير تتبُّع الإحالات الناجحة الجديد.
ستنتقل الحملات التي تستهدف إجراء إحالة ناجحة معيّنًا إلى استخدام أهداف الإحالات الناجحة التلقائية في الحساب الإداري للإحالات الناجحة. إذا واصلت استهداف إجراء إحالة ناجحة معيّن، قد يؤدي ذلك إلى سلوك غير متّسق، لأنّ الحساب الإداري قد لا يتضمّن الأهداف نفسها التي يتضمّنها حساب العميل. تأكَّد من تحسين حملاتك لتحقيق الأهداف المناسبة.
إذا كان أحد الحسابات ينتمي إلى أكثر من حساب إداري، يمكنه فقط استخدام إجراءات الإحالات الناجحة من حساب إداري واحد. إذا لم يتم تحديد حساب لتتبُّع الإحالات الناجحة، سيستخدم الحساب نفسه كحساب لتتبُّع الإحالات الناجحة بشكل تلقائي.

استيراد الإحالات الناجحة على مستوى الحسابات

عند تفعيل ميزة التتبُّع في جميع الحسابات، يمكن لحسابات العملاء والحسابات الإدارية استيراد الإحالات الناجحة نيابةً عن حساب عرض الإعلانات. ويتيح ذلك تبسيط منطق الاستيراد، وبالتالي لن تحتاج إلى تحديد حساب العرض لكل إحالة ناجحة عند الاستيراد، بل يمكنك اختيار حساب واحد فقط من شجرة حسابك لاستيراد جميع الإحالات الناجحة.

لتحميل إحالة ناجحة بنجاح، يجب أن يكون لدى الحساب الذي يتم التحميل منه إذن الوصول إلى إجراء الإحالة الناجحة. في التدرّج الهرمي للتتبُّع في جميع الحسابات، يكون للحساب الذي يحمّل الإحالات الناجحة إذن وصول إلى الإجراء إذا كان حسابًا رئيسيًا (إداريًا) أو حسابًا فرعيًا لمالك إجراء الإحالة الناجحة في شجرة الحسابات.

يوضّح المخطّط البياني التالي بنية التفويض لاستيراد الإحالات الناجحة. في هذا المثال، C1 هو حساب العميل الذي عرض الإعلان الذي أدّى إلى الإحالة الناجحة، وM2 هو مالك إجراء الإحالة الناجحة والحساب الرئيسي لتتبُّع الإحالات الناجحة في C1. يُسمح للحسابات المميّزة باللون الأخضر باستيراد الإحالات الناجحة نيابةً عن "C1"، في حين لا يُسمح للحسابات المميّزة باللون الأحمر بذلك.

بنية التفويض

يجب إنشاء إجراءات إحالات ناجحة

لقياس الإحالات الناجحة، عليك إعداد ConversionAction type لإجراء الإحالة الناجحة الذي تريد تتبُّعه. على سبيل المثال، يتطلّب الشراء على الإنترنت والمكالمة الهاتفية إجراءات إحالة ناجحة مختلفة.

أفضل طريقة لإعداد إجراءات إحالات ناجحة جديدة في واجهة برمجة التطبيقات هي استخدام مثال رمز إضافة إجراء إحالة ناجحة. يتولّى النموذج جميع مهام المصادقة في الخلفية نيابةً عنك، ويرشدك خلال إنشاء ConversionAction.

تتطلّب معظم إجراءات الإحالات الناجحة أيضًا خطوات إضافية من جانبك لتتبُّعها. على سبيل المثال، لتتبُّع الإحالات الناجحة على موقعك الإلكتروني، عليك إضافة مقتطف رمز يُعرف باسم العلامة إلى صفحة الإحالة الناجحة على موقعك الإلكتروني. للاطّلاع على المتطلبات التفصيلية لأنواع إجراءات الإحالات الناجحة الأخرى، راجِع مقالة مركز مساعدة "إعلانات Google" حول أنواع الإحالات الناجحة.

في حال استخدام تتبُّع الإحالات الناجحة في جميع الحسابات، تعرض السمة ConversionActionService إجراءات الإحالات الناجحة التالية:

جميع إجراءات الإحالات الناجحة التي يحدّدها الحساب الإداري الذي يستخدمه الحساب لتتبُّع الإحالات الناجحة في جميع الحسابات
جميع إجراءات الإحالات الناجحة التي جمع العميل إحصاءات بشأنها، بما في ذلك الإجراءات المحدّدة من النظام والإجراءات التي يملكها المدير حتى إذا ألغى المدير الربط لاحقًا
جميع الإجراءات التي حدّدها العميل في حسابه
الإحالات الناجحة في "إحصاءات Google" التي تم إنشاؤها في مواقع "إحصاءات Google" المرتبطة ويشمل ذلك الإجراءات الخاصة بالإحالات الناجحة في "إحصاءات Google" التي لم يتم استيرادها إلى "إعلانات Google"، والتي تكون حالتها HIDDEN.

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

يوضّح مثال الرمز البرمجي التالي عملية إنشاء إجراء إحالة ناجحة جديد. على وجه التحديد، ينشئ إجراء إحالة ناجحة مع ضبط type على UPLOAD_CLICKS. ويضبط أيضًا category على DEFAULT.

تنطبق الإعدادات التلقائية التالية:

يضبط Google Ads API الحقل primary_for_goal تلقائيًا، ولكن يمكنك ضبط هذا الحقل بشكل صريح للتحكّم في تأثير إجراء الإحالة الناجحة في إعداد التقارير وتقديم عروض الأسعار في حسابك عند دمجه مع أهداف الإحالات الناجحة.
تضبط Google Ads API السمة counting_type تلقائيًا على MANY_PER_CLICK. اطّلِع على مقالة لمحة عن خيارات احتساب الإحالات الناجحة لمزيد من التفاصيل.
تضبط Google Ads API نموذج تحديد المصدر على بالاستناد إلى البيانات من خلال ضبط الحقل attribution_model_settings على القيمة GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN لـ AttributionModel. اطّلِع على مقالة لمحة عن نماذج تحديد المصدر لمعرفة المزيد عن نماذج تحديد المصدر.

جافا

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

#C

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V25.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

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    conversion_action_service: ConversionActionServiceClient = (
        client.get_service("ConversionActionService")
    )

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

    # Create conversion action.
    conversion_action: ConversionAction = 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: ConversionAction.ValueSettings = (
        conversion_action.value_settings
    )
    value_settings.default_value = 15.0
    value_settings.always_use_default_value = True

    # Add the conversion action.
    conversion_action_response: MutateConversionActionsResponse = (
        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

Ruby

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}."
endadd_conversion_action.rb

Perl

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::V25::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V25::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V25::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

curl

يمكنك الاطّلاع على هذا المثال في مجلد "تجديد النشاط التسويقي" ضمن مكتبة العميل وفي مجموعة أمثلة الرموز البرمجية: مثال على إضافة رمز إجراء الإحالة الناجحة.

شروط التحقق من صحة القيمة

تتيح "إعلانات Google" وGoogle Ads API مجموعة كبيرة من إجراءات الإحالات الناجحة، لذا تختلف بعض قواعد التحقّق من الصحة استنادًا إلى type الإجراء.

الخطأ الأكثر شيوعًا عند إنشاء إجراء إحالة ناجحة هو DUPLICATE_NAME. تأكَّد من استخدام اسم فريد لكل إجراء إحالة ناجحة.

في ما يلي بعض النصائح حول ضبط حقول ConversionAction:

جميع حقول التعداد

ستؤدي محاولة ضبط أي حقل تعداد على UNKNOWN إلى ظهور RequestError.INVALID_ENUM_VALUE خطأ.

app_id

سمة app_id غير قابلة للتغيير ولا يمكن ضبطها إلا عند إنشاء إحالة ناجحة جديدة للتطبيق.

attribution_model_settings

يؤدي ضبط هذه السياسة على خيار متوقّف نهائيًا إلى ظهور الخطأ CANNOT_SET_RULE_BASED_ATTRIBUTION_MODELS. تتيح "إعلانات Google" استخدام GOOGLE_ADS_LAST_CLICK وGOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN فقط.

click_through_lookback_window_days

يؤدي ضبط هذه السمة على قيمة خارج النطاق المسموح به إلى ظهور الخطأ RangeError.TOO_LOW أو RangeError.TOO_HIGH.

يجب أن تتراوح قيمة هذه السمة بين يوم واحد و60 يومًا لإجراء إحالة ناجحة من النوع AD_CALL أو WEBSITE_CALL. بالنسبة إلى معظم إجراءات الإحالات الناجحة الأخرى، يتراوح النطاق المسموح به بين يوم واحد و90 يومًا.

include_in_conversions_metric

يؤدي ضبط هذه القيمة في عملية create أو update إلى حدوث خطأ FieldError.IMMUTABLE_FIELD. بدلاً من ذلك، اضبط primary_for_goal كما هو موضّح في دليل أهداف الإحالات الناجحة.

phone_call_duration_seconds

ستؤدي محاولة ضبط هذه السمة على إجراء إحالة ناجحة ليس للمكالمات إلى ظهور الخطأ FieldError.VALUE_MUST_BE_UNSET.

type

السمة type غير قابلة للتغيير ولا يمكن ضبطها إلا عند إنشاء إحالة ناجحة جديدة.

يؤدي تعديل إجراء إحالة ناجحة باستخدام type يساوي UNKNOWN إلى حدوث الخطأ MutateError.MUTATE_NOT_ALLOWED.

value_settings

يجب أن تكون قيمة السمة always_use_default_value لإجراء الإحالة الناجحة value_settings لـ WEBSITE_CALL أو AD_CALL مضبوطة على true. يؤدي تحديد قيمة false عند إنشاء هذه القيمة أو تعديلها إلى حدوث خطأ INVALID_VALUE.

view_through_lookback_window_days

يؤدي ضبط هذه السمة على قيمة خارج النطاق المسموح به إلى ظهور الخطأ RangeError.TOO_LOW أو RangeError.TOO_HIGH. بالنسبة إلى معظم إجراءات الإحالات الناجحة، يتراوح النطاق المسموح به بين يوم واحد و30 يومًا.

لا يمكن ضبط هذه السمة على إجراءات الإحالات الناجحة AD_CALL أو WEBSITE_CALL. يؤدي تحديد قيمة إلى حدوث خطأ VALUE_MUST_BE_UNSET.

فئات إجراءات الإحالات الناجحة

إدارة الإحالات الناجحة بلا إنترنت

البدء تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الاستعداد لتقديم الموافقة

إعداد موقعك الإلكتروني لتتبُّع الإحالات الناجحة

تفعيل ميزة "تتبُّع الإحالات الناجحة" في حساب الإحالات الناجحة على "إعلانات Google"

خطوات تفعيل ميزة "تتبُّع الإحالات الناجحة"

استرداد معلومات عن إعداد تتبُّع الإحالات الناجحة

إنشاء إجراء إحالة ناجحة ضمن عميل الإحالة الناجحة في "إعلانات Google"

مثال على الرمز

جافا

#C

PHP

Python

Ruby

Perl

curl

استرداد إجراء إحالة ناجحة حالي

تتبّع الإحالات الناجحة في جميع الحسابات

تفعيل ميزة "تتبُّع الإحالات الناجحة في جميع الحسابات" في Google Ads API

استيراد الإحالات الناجحة على مستوى الحسابات

يجب إنشاء إجراءات إحالات ناجحة

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

جافا

#C

PHP

Python

Ruby

Perl

curl

شروط التحقق من صحة القيمة

البدء