نتيجة التحسين والاقتراحات

يمكن أن تساعدك الاقتراحات في تحسين حملاتك بعدة طرق:

• تقديم ميزات جديدة ومناسبة
• الاستفادة بشكلٍ أفضل من ميزانيتك من خلال تحسين عروض الأسعار والكلمات الرئيسية والإعلانات
• زيادة الأداء العام والكفاءة في حملاتك

لزيادة نتائج التحسين، يمكنك استخدام RecommendationService لاسترداد الاقتراحات، ثم تطبيقها أو رفضها وفقًا لذلك. يمكنك أيضًا الاشتراك في التطبيق التلقائي للاقتراحات باستخدام RecommendationSubscriptionService.

نتيجة التحسين

نتيجة التحسين هي تقدير لمدى جودة أداء حسابك على "إعلانات Google"، وهي متاحة على مستوى Customer وCampaign.

ملاحظة: إذا كانت لديك حسابات عملاء متعددة وأردت احتساب نتيجة التحسين الإجمالية، يمكنك احتساب المتوسط المرجّح في الحسابات التي تم تسجيلها من خلال جمع حاصل ضرب نتيجة التحسين لكل حساب ووزن نتيجة التحسين، ثم القسمة على مجموع الأوزان: SUM(Customer.optimization_score * Customer.optimization_score_weight) / SUM(Customer.optimization_score_weight).

تتوفّر مقاييس مرتبطة بالتحسين لتقارير customer وcampaign:

1. يوفّر metrics.optimization_score_url رابطًا لصفحة معيّنة في الحساب للاطّلاع على معلومات عن الاقتراحات ذات الصلة في واجهة مستخدم "إعلانات Google".
2. يوضّح الرقم metrics.optimization_score_uplift مقدار الزيادة في نتيجة التحسين في حال تطبيق جميع الاقتراحات ذات الصلة. وهو تقدير يستند إلى جميع الاقتراحات المتاحة ككل، وليس فقط إلى مجموع نقاط التحسُّن لكل اقتراح.

لتجميع الاقتراحات المعروضة وترتيبها، يمكنك تقسيم هذين المقياسَين حسب نوع الاقتراح باستخدام segments.recommendation_type في طلب البحث.

أنواع الاقتراحات

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

أنواع الاقتراحات المتاحة بالكامل

RecommendationType	الوصف
CAMPAIGN_BUDGET	إصلاح الحملات المقيَّدة بالميزانية
KEYWORD	إضافة كلمات رئيسية جديدة
TEXT_AD	إضافة اقتراحات الإعلانات
TARGET_CPA_OPT_IN	تقديم عروض أسعار باستخدام "سقف التكلفة المحدد لكل إجراء"
MAXIMIZE_CONVERSIONS_OPT_IN	تقديم عروض أسعار باستخدام استراتيجية "تحقيق الحد الأقصى من الإحالات الناجحة"
MAXIMIZE_CONVERSION_VALUE_OPT_IN	تقديم عروض أسعار باستخدام استراتيجية "تحقيق الحد الأقصى من قيمة الإحالات الناجحة"
ENHANCED_CPC_OPT_IN	تقديم عروض أسعار باستخدام "تكلفة النقرة المحسّنة"
MAXIMIZE_CLICKS_OPT_IN	تقديم عروض أسعار باستخدام استراتيجية "الحصول على الحد الأقصى من النقرات"
OPTIMIZE_AD_ROTATION	استخدام عرض الإعلانات بالتناوب المحسّن
MOVE_UNUSED_BUDGET	نقل الميزانيات غير المستخدَمة إلى الميزانيات المحدودة
TARGET_ROAS_OPT_IN	تقديم عروض أسعار باستخدام استراتيجية "عائد الإنفاق الإعلاني المستهدَف"
FORECASTING_CAMPAIGN_BUDGET	إصلاح الحملات التي من المتوقّع أن تصبح ميزانيتها أدنى من حدود الميزانية المطلوبة في المستقبل
RESPONSIVE_SEARCH_AD	إضافة إعلان متجاوب جديد على شبكة البحث
MARGINAL_ROI_CAMPAIGN_BUDGET	تعديل ميزانية الحملة لزيادة عائد الاستثمار
USE_BROAD_MATCH_KEYWORD	استخدام المطابقة التقريبية للحملات المستندة إلى الإحالات الناجحة والتي تستخدم عروض الأسعار المبرمَجة
RESPONSIVE_SEARCH_AD_ASSET	إضافة مواد عرض الإعلانات المتجاوبة على شبكة البحث إلى إعلان
RESPONSIVE_SEARCH_AD_IMPROVE_AD_STRENGTH	تحسين قوة إعلان متجاوب على شبكة البحث
DISPLAY_EXPANSION_OPT_IN	تعديل حملة لاستخدام ميزة "الانتشار على الشبكة الإعلانية"
SEARCH_PARTNERS_OPT_IN	توسيع نطاق الوصول إلى الجمهور من خلال الشركاء في "شبكة بحث Google"
CUSTOM_AUDIENCE_OPT_IN	إنشاء جمهور مخصّص
IMPROVE_DEMAND_GEN_AD_STRENGTH	تحسين قوة الإعلانات في "حملات زيادة الطلب"
UPGRADE_SMART_SHOPPING_CAMPAIGN_TO_PERFORMANCE_MAX	ترقية حملة تسوّق ذكية إلى حملة الأداء الأفضل
UPGRADE_LOCAL_CAMPAIGN_TO_PERFORMANCE_MAX	ترقية حملة محلية قديمة إلى "حملة أداء أفضل"
SHOPPING_MIGRATE_REGULAR_SHOPPING_CAMPAIGN_OFFERS_TO_PERFORMANCE_MAX	نقل العروض التي تستهدفها "حملات Shopping العادية" إلى "حملات الأداء الأفضل" الحالية
MIGRATE_DYNAMIC_SEARCH_ADS_CAMPAIGN_TO_PERFORMANCE_MAX	نقل "الإعلانات الديناميكية على شبكة البحث" إلى "حملات الأداء الأفضل"
PERFORMANCE_MAX_OPT_IN	إنشاء "حملات الأداء الأفضل" في حسابك
IMPROVE_PERFORMANCE_MAX_AD_STRENGTH	تحسين قوة مجموعة مواد العرض في "حملة الأداء الأفضل" للحصول على تقييم "ممتاز"
PERFORMANCE_MAX_FINAL_URL_OPT_IN	تفعيل ميزة "توسيع عنوان URL النهائي" في "حملات الأداء الأفضل"
RAISE_TARGET_CPA_BID_TOO_LOW	رفع سقف التكلفة المحدد لكل إجراء عندما يكون منخفضًا جدًا ولا يحقّق أي إحالات ناجحة أو يحقّق عددًا قليلاً جدًا منها
FORECASTING_SET_TARGET_ROAS	زيادة الميزانية قبل فعالية موسمية من المتوقّع أن تؤدي إلى زيادة عدد الزيارات، وتغيير استراتيجية عروض الأسعار من "تحقيق الحد الأقصى من قيمة الإحالات الناجحة" إلى "عائد الإنفاق الإعلاني المستهدَف"
LEAD_FORM_ASSET	إضافة مواد عرض نماذج العملاء المحتملين إلى حملة
CALLOUT_ASSET	إضافة مواد عرض وسائل الشرح على مستوى الحملة أو العميل
SITELINK_ASSET	إضافة مواد عرض روابط أقسام الموقع على مستوى الحملة أو العميل
CALL_ASSET	إضافة مواد عرض المكالمات على مستوى الحملة أو العميل
SHOPPING_ADD_AGE_GROUP	أضِف سمة الفئة العمرية إلى العروض التي تم تخفيض ترتيبها بسبب عدم توفّر فئة عمرية
SHOPPING_ADD_COLOR	إضافة لون إلى العروض التي تم تخفيض ترتيبها بسبب عدم توفّر لون
SHOPPING_ADD_GENDER	إضافة قيمة الجنس إلى العروض التي تم خفض ترتيبها بسبب عدم توفّر قيمة الجنس
SHOPPING_ADD_GTIN	إضافة رقم GTIN (الرقم التجاري العالمي للسلعة) إلى العروض التي تم تخفيض ترتيبها بسبب عدم توفّر رقم GTIN
SHOPPING_ADD_MORE_IDENTIFIERS	أضِف المزيد من المعرّفات إلى العروض التي تم خفض ترتيبها بسبب عدم توفّر معرّفات
SHOPPING_ADD_SIZE	إضافة المقاس إلى العروض التي تم تخفيض ترتيبها بسبب عدم توفّر المقاس
SHOPPING_ADD_PRODUCTS_TO_CAMPAIGN	إضافة منتجات لعرضها في حملة
SHOPPING_FIX_DISAPPROVED_PRODUCTS	حلّ المشاكل في المنتجات المرفوضة
SHOPPING_TARGET_ALL_OFFERS	أنشِئ حملة شاملة تستهدف جميع العروض
SHOPPING_FIX_SUSPENDED_MERCHANT_CENTER_ACCOUNT	حلّ مشاكل تعليق حساب Merchant Center
SHOPPING_FIX_MERCHANT_CENTER_ACCOUNT_SUSPENSION_WARNING	حلّ المشاكل المتعلّقة بتحذيرات تعليق حساب Merchant Center
DYNAMIC_IMAGE_EXTENSION_OPT_IN	تفعيل إضافات الصور الديناميكية في الحساب
RAISE_TARGET_CPA	رفع سقف التكلفة المحدد لكل إجراء
LOWER_TARGET_ROAS	خفض عائد الإنفاق الإعلاني المستهدَف
FORECASTING_SET_TARGET_CPA	ضبط سقف تكلفة محدّد لكل إجراء في الحملات التي لا تتضمّن سقفًا محدّدًا، وذلك قبل فعالية موسمية من المتوقّع أن تؤدي إلى زيادة عدد الزيارات
SET_TARGET_CPA	ضبط سقف تكلفة محدد لكل إجراء في الحملات التي لم يتم تحديد سقف لها
SET_TARGET_ROAS	ضبط عائد إنفاق إعلاني مستهدَف للحملات التي لم يتم تحديد عائد لها
REFRESH_CUSTOMER_MATCH_LIST	تعديل قائمة عملاء لم يتم تعديلها في آخر 90 يومًا
IMPROVE_GOOGLE_TAG_COVERAGE	نشر "علامة تتبُّع من Google" على المزيد من الصفحات
CAMPAIGN_SPECIFIC_APP_GOAL	إضافة هدف إحالة ناجحة للتطبيق خاص بالحملة
RAISE_TARGET_CPA_PERFORMANCE_BID_TOO_LOW	زيادة سقف التكلفة المحدد لكل إجراء عندما يكون منخفضًا جدًا في "الحملات على شبكة البحث"
LOWER_TARGET_ROAS_PERFORMANCE_BID_TOO_LOW	خفض عائد الإنفاق الإعلاني المستهدَف عندما يكون منخفضًا جدًا بالنسبة إلى "الحملات على شبكة البحث"
RAISE_BUDGET_PERFORMANCE_TOO_LOW	زيادة الميزانية عندما تكون منخفضة جدًا في "الحملات على شبكة البحث" تتوفّر هذه الميزة بدءًا من الإصدار v26. يتم عرض تفاصيل الاقتراحات في Recommendation.raise_budget_performance_too_low_recommendation ويتم تطبيقها باستخدام ApplyRecommendationOperation.raise_budget_performance_too_low.
‫KEYWORD_MATCH_TYPE (متوقّفة نهائيًا)	تم إيقاف هذه السياسة نهائيًا، لذا يُرجى استخدام سياسة USE_BROAD_MATCH_KEYWORD بدلاً منها.

استرداد الاقتراحات

كما هو الحال مع معظم الكيانات الأخرى في Google Ads API، يتم جلب Recommendationالكائنات باستخدام GoogleAdsService.SearchStream مع طلب بحث بلغة طلبات البحث في "إعلانات Google".

يتم تقديم تفاصيل كل نوع من الاقتراحات في حقل خاص بالاقتراح. على سبيل المثال، تظهر تفاصيل الاقتراحات المتعلّقة بـ CAMPAIGN_BUDGET في الحقل campaign_budget_recommendation، ويتم تضمينها في العنصر CampaignBudgetRecommendation.

يمكنك العثور على جميع الحقول الخاصة بالاقتراحات في حقل الاتحاد recommendation.

تأثير الاقتراح

تُعبئ بعض أنواع الاقتراحات الحقل impact للاقتراح. يتضمّن RecommendationImpact تقديرًا لتأثير تطبيق الاقتراح على أداء الحساب. تتوفّر مقاييس الاقتراحات التالية في الحقلَين impact.base_metrics وimpact.potential_metrics:

• impressions

• clicks

• cost_micros

• conversions

• all_conversions

• video_views

حتى عند ملء الحقل impact، يختلف مدى توفّر المقاييس حسب نوع الاقتراح ونوع الحملة، من بين عوامل أخرى. بشكل عام، تحقَّق من توفّر كل مقياس من مقاييس التأثير قبل محاولة استخدامه.

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

يستردّ الرمز النموذجي التالي جميع الاقتراحات المتاحة والمرفوضة من النوع KEYWORD من أحد الحسابات ويطبع بعض تفاصيلها:

جافا

try (GoogleAdsServiceClient googleAdsServiceClient =
        googleAdsClient.getLatestVersion().createGoogleAdsServiceClient();
    RecommendationServiceClient recommendationServiceClient =
        googleAdsClient.getLatestVersion().createRecommendationServiceClient()) {
  // Creates a query that retrieves keyword recommendations.
  String query =
      "SELECT recommendation.resource_name, "
          + "  recommendation.campaign, "
          + "  recommendation.keyword_recommendation "
          + "FROM recommendation "
          + "WHERE recommendation.type = KEYWORD";
  // Constructs the SearchGoogleAdsStreamRequest.
  SearchGoogleAdsStreamRequest request =
      SearchGoogleAdsStreamRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setQuery(query)
          .build();

  // Issues the search stream request to detect keyword recommendations that exist for the
  // customer account.
  ServerStream<SearchGoogleAdsStreamResponse> stream =
      googleAdsServiceClient.searchStreamCallable().call(request);

  // Creates apply operations for all the recommendations found.
  List<ApplyRecommendationOperation> applyRecommendationOperations = new ArrayList<>();
  for (SearchGoogleAdsStreamResponse response : stream) {
    for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
      Recommendation recommendation = googleAdsRow.getRecommendation();
      System.out.printf(
          "Keyword recommendation '%s' was found for campaign '%s'%n",
          recommendation.getResourceName(), recommendation.getCampaign());
      KeywordInfo keyword = recommendation.getKeywordRecommendation().getKeyword();
      System.out.printf("\tKeyword = '%s'%n", keyword.getText());
      System.out.printf("\tMatch type = '%s'%n", keyword.getMatchType());

      // Creates an ApplyRecommendationOperation that will apply this recommendation, and adds
      // it to the list of operations.
      applyRecommendationOperations.add(buildRecommendationOperation(recommendation));
    }
  }
DetectAndApplyRecommendations.java
      

#C

// Get the GoogleAdsServiceClient.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V25.GoogleAdsService);

// Creates a query that retrieves keyword recommendations.
string query = "SELECT recommendation.resource_name, " +
    "recommendation.campaign, recommendation.keyword_recommendation " +
    "FROM recommendation WHERE " +
    $"recommendation.type = KEYWORD";

List<ApplyRecommendationOperation> operations =
    new List<ApplyRecommendationOperation>();

try
{
    // Issue a search request.
    googleAdsService.SearchStream(customerId.ToString(), query,
        delegate (SearchGoogleAdsStreamResponse resp)
        {
            Console.WriteLine($"Found {resp.Results.Count} recommendations.");
            foreach (GoogleAdsRow googleAdsRow in resp.Results)
            {
                Recommendation recommendation = googleAdsRow.Recommendation;
                Console.WriteLine("Keyword recommendation " +
                    $"{recommendation.ResourceName} was found for campaign " +
                    $"{recommendation.Campaign}.");

                if (recommendation.KeywordRecommendation != null)
                {
                    KeywordInfo keyword =
                        recommendation.KeywordRecommendation.Keyword;
                    Console.WriteLine($"Keyword = {keyword.Text}, type = " +
                        "{keyword.MatchType}");
                }

                operations.Add(
                    BuildApplyRecommendationOperation(recommendation.ResourceName)
                );
            }
        }
    );
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");
    Console.WriteLine($"Failure: {e.Failure}");
    Console.WriteLine($"Request ID: {e.RequestId}");
    throw;
}
DetectAndApplyRecommendations.cs
      

PHP

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that retrieves keyword recommendations.
$query = 'SELECT recommendation.resource_name, recommendation.campaign, '
    . 'recommendation.keyword_recommendation '
    . 'FROM recommendation '
    . 'WHERE recommendation.type = KEYWORD ';
// Issues a search request to detect keyword recommendations that exist for the
// customer account.
$response =
    $googleAdsServiceClient->search(SearchGoogleAdsRequest::build($customerId, $query));

$operations = [];
// Iterates over all rows in all pages and prints the requested field values for
// the recommendation in each row.
foreach ($response->iterateAllElements() as $googleAdsRow) {
    /** @var GoogleAdsRow $googleAdsRow */
    $recommendation = $googleAdsRow->getRecommendation();
    printf(
        "Keyword recommendation with resource name '%s' was found for campaign "
        . "with resource name '%s':%s",
        $recommendation->getResourceName(),
        $recommendation->getCampaign(),
        PHP_EOL
    );
    if (!is_null($recommendation->getKeywordRecommendation())) {
        $keyword = $recommendation->getKeywordRecommendation()->getKeyword();
        printf(
            "\tKeyword = '%s'%s\ttype = '%s'%s",
            $keyword->getText(),
            PHP_EOL,
            KeywordMatchType::name($keyword->getMatchType()),
            PHP_EOL
        );
    }
    // Creates an ApplyRecommendationOperation that will be used to apply this
    // recommendation, and adds it to the list of operations.
    $operations[] = self::buildRecommendationOperation($recommendation->getResourceName());
}
DetectAndApplyRecommendations.php
      

Python

googleads_service = client.get_service("GoogleAdsService")
query: str = """
    SELECT
      recommendation.campaign,
      recommendation.keyword_recommendation
    FROM recommendation
    WHERE
      recommendation.type = KEYWORD"""

# Detects keyword recommendations that exist for the customer account.
response: Iterable[GoogleAdsRow] = googleads_service.search(
    customer_id=customer_id, query=query
)

operations: List[ApplyRecommendationOperation] = []
for row in response:
    recommendation = row.recommendation
    print(
        f"Keyword recommendation ('{recommendation.resource_name}') "
        f"was found for campaign '{recommendation.campaign}."
    )

    keyword = recommendation.keyword_recommendation.keyword
    print(
        f"\tKeyword = '{keyword.text}'\n" f"\tType = '{keyword.match_type}'"
    )

    # Create an ApplyRecommendationOperation that will be used to apply
    # this recommendation, and add it to the list of operations.
    operations.append(
        build_recommendation_operation(client, recommendation.resource_name)
    )
detect_and_apply_recommendations.py
      

Ruby

query = <<~QUERY
  SELECT recommendation.resource_name, recommendation.campaign,
      recommendation.keyword_recommendation
  FROM recommendation
  WHERE recommendation.type = KEYWORD
QUERY

google_ads_service = client.service.google_ads

response = google_ads_service.search(
  customer_id: customer_id,
  query: query,
)

operations = response.each do |row|
  recommendation = row.recommendation

  puts "Keyword recommendation ('#{recommendation.resource_name}') was found for "\
    "campaign '#{recommendation.campaign}'."

  if recommendation.keyword_recommendation
    keyword = recommendation.keyword_recommendation.keyword
    puts "\tKeyword = '#{keyword.text}'"
    puts "\ttype = '#{keyword.match_type}'"
  end

  build_recommendation_operation(client, recommendation.resource_name)
end
detect_and_apply_recommendations.rb
      

Perl

# Create the search query.
my $search_query =
  "SELECT recommendation.resource_name, " .
  "recommendation.campaign, recommendation.keyword_recommendation " .
  "FROM recommendation " .
  "WHERE recommendation.type = KEYWORD";

# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();

my $search_stream_handler =
  Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
    service => $google_ads_service,
    request => {
      customerId => $customer_id,
      query      => $search_query
    }});

# Create apply operations for all the recommendations found.
my $apply_recommendation_operations = ();
$search_stream_handler->process_contents(
  sub {
    my $google_ads_row = shift;
    my $recommendation = $google_ads_row->{recommendation};
    printf "Keyword recommendation '%s' was found for campaign '%s'.\n",
      $recommendation->{resourceName}, $recommendation->{campaign};
    my $keyword = $recommendation->{keywordRecommendation}{keyword};
    printf "\tKeyword = '%s'\n",    $keyword->{text};
    printf "\tMatch type = '%s'\n", $keyword->{matchType};
    # Creates an ApplyRecommendationOperation that will apply this recommendation, and adds
    # it to the list of operations.
    push @$apply_recommendation_operations,
      build_recommendation_operation($recommendation);
  });
detect_and_apply_recommendations.pl
      

curl

# Gets keyword recommendations.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
"query": "
  SELECT
    recommendation.campaign,
    recommendation.keyword_recommendation
  FROM recommendation
  WHERE
    recommendation.type = KEYWORD
"
}
EOF
detect_and_apply_recommendations.sh
      

اتخاذ إجراء

يمكن تطبيق أي اقتراح تم استرداده أو رفضه.

استنادًا إلى نوع الاقتراح، يمكن أن تتغيّر الاقتراحات يوميًا أو حتى عدة مرات في اليوم. عند حدوث ذلك، يمكن أن يصبح resource_name الخاص بكائن الاقتراح قديمًا بعد استرداد الاقتراح.

من الممارسات الجيدة اتّخاذ الإجراءات بشأن الاقتراحات بعد استردادها بفترة قصيرة.

تطبيق الاقتراحات

يمكنك تطبيق الاقتراحات النشطة أو المرفوضة باستخدام طريقة ApplyRecommendation في RecommendationService.

يمكن أن تتضمّن أنواع الاقتراحات مَعلمات إلزامية أو اختيارية. تتضمّن معظم الاقتراحات قيمًا مقترَحة يتم استخدامها تلقائيًا.

لا يمكن ضبط الحسابات للتطبيق التلقائي للاقتراحات لجميع أنواع الاقتراحات. ومع ذلك، يمكنك تنفيذ سلوك مشابه لأنواع الاقتراحات المتوافقة بالكامل مع Google Ads API. لمزيد من المعلومات، يُرجى الرجوع إلى مثال رمز DetectAndApplyRecommendations.

استخدِم حقل الاتحاد apply_parameters في ApplyRecommendationOperation لتطبيق الاقتراحات التي تتضمّن قيم مَعلمات محدّدة. يحتوي كل نوع اقتراح مناسب على حقل خاص به. لا تستخدم أي قيمة معلَمة لأنواع الاقتراحات غير المدرَجة في الحقل apply_parameters.

ملاحظة مهمة: عند تطبيق الكلمات الرئيسية التي يُنصح بها من اقتراح إضافة كلمات رئيسية جديدة، ستكون مسؤولاً عن ضمان التزام إعلاناتك بالسياسات الإعلانية بعد إدراج تلك الكلمات الرئيسية.

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

يوضّح الرمز التالي كيفية إنشاء ApplyRecommendationOperation وكيفية إلغاء القيم المقترَحة إذا أردت استبدالها بقيمك الخاصة.

جافا

/** Creates and returns an ApplyRecommendationOperation to apply the given recommendation. */
private ApplyRecommendationOperation buildRecommendationOperation(Recommendation recommendation) {
  // If you have a recommendation ID instead of a resource name, you can create a resource name
  // like this:
  // String resourceName = ResourceNames.recommendation(customerId, recommendationId);

  // Creates a builder to construct the operation.
  Builder operationBuilder = ApplyRecommendationOperation.newBuilder();

  // Each recommendation type has optional parameters to override the recommended values. Below is
  // an example showing how to override a recommended ad when a TextAdRecommendation is applied.
  // operationBuilder.getTextAdBuilder().getAdBuilder().setResourceName("INSERT_AD_RESOURCE_NAME");

  // Sets the operation's resource name to the resource name of the recommendation to apply.
  operationBuilder.setResourceName(recommendation.getResourceName());
  return operationBuilder.build();
}
DetectAndApplyRecommendations.java
      

#C

private ApplyRecommendationOperation BuildApplyRecommendationOperation(
    string recommendationResourceName
)
{
    // If you have a recommendation_id instead of the resource_name you can create a
    // resource name from it like this:
    // string recommendationResourceName =
    //    ResourceNames.Recommendation(customerId, recommendationId)

    // Each recommendation type has optional parameters to override the recommended values.
    // This is an example to override a recommended ad when a TextAdRecommendation is
    // applied.
    // For details, please read
    // https://developers.google.com/google-ads/api/reference/rpc/latest/ApplyRecommendationOperation.
    /*
    Ad overridingAd = new Ad()
    {
        Id = "INSERT_AD_ID_AS_LONG_HERE"
    };
    applyRecommendationOperation.TextAd = new TextAdParameters()
    {
        Ad = overridingAd
    };
    */

    ApplyRecommendationOperation applyRecommendationOperation =
    new ApplyRecommendationOperation()
    {
        ResourceName = recommendationResourceName
    };

    return applyRecommendationOperation;
}
DetectAndApplyRecommendations.cs
      

PHP

private static function buildRecommendationOperation(
    string $recommendationResourceName
): ApplyRecommendationOperation {
    // If you have a recommendation_id instead of the resource name, you can create a resource
    // name from it like this:
    /*
    $recommendationResourceName =
        ResourceNames::forRecommendation($customerId, $recommendationId);
    */

    // Each recommendation type has optional parameters to override the recommended values.
    // This is an example to override a recommended ad when a TextAdRecommendation is applied.
    // For details, please read
    // https://developers.google.com/google-ads/api/reference/rpc/latest/ApplyRecommendationOperation.
    /*
    $overridingAd = new Ad([
        'id' => 'INSERT_AD_ID_AS_INTEGER_HERE'
    ]);
    $applyRecommendationOperation->setTextAd(new TextAdParameters(['ad' => $overridingAd]));
    */

    // Issues a mutate request to apply the recommendation.
    $applyRecommendationOperation = new ApplyRecommendationOperation();
    $applyRecommendationOperation->setResourceName($recommendationResourceName);
    return $applyRecommendationOperation;
}
DetectAndApplyRecommendations.php
      

Python

def build_recommendation_operation(
    client: GoogleAdsClient, recommendation: str
) -> ApplyRecommendationOperation:
    """Creates a ApplyRecommendationOperation to apply the given recommendation.

    Args:
        client: an initialized GoogleAdsClient instance.
        recommendation: a resource name for the recommendation to be applied.
    """
    # If you have a recommendation ID instead of a resource name, you can create
    # a resource name like this:
    #
    # googleads_service = client.get_service("GoogleAdsService")
    # resource_name = googleads_service.recommendation_path(
    #   customer_id, recommendation.id
    # )

    operation: ApplyRecommendationOperation = client.get_type(
        "ApplyRecommendationOperation"
    )

    # Each recommendation type has optional parameters to override the
    # recommended values. Below is an example showing how to override a
    # recommended ad when a TextAdRecommendation is applied.
    #
    # operation.text_ad.ad.resource_name = "INSERT_AD_RESOURCE_NAME"
    #
    # For more details, see:
    # https://developers.google.com/google-ads/api/reference/rpc/latest/ApplyRecommendationOperation#apply_parameters

    operation.resource_name = recommendation
    return operation
detect_and_apply_recommendations.py
      

Ruby

def build_recommendation_operation(client, recommendation)
  # If you have a recommendation_id instead of the resource_name
  # you can create a resource name from it like this:
  # recommendation_resource =
  #    client.path.recommendation(customer_id, recommendation_id)

  operations = client.operation.apply_recommendation
  operations.resource_name = recommendation_resource

  # Each recommendation type has optional parameters to override the recommended
  # values. This is an example to override a recommended ad when a
  # TextAdRecommendation is applied.
  #
  # text_ad_parameters = client.resource.text_ad_parameters do |tap|
  #   tap.ad = client.resource.ad do |ad|
  #     ad.id = "INSERT_AD_ID_AS_INTEGER_HERE"
  #   end
  # end
  # operation.text_ad = text_ad_parameters
  #
  # For more details, see:
  # https://developers.google.com/google-ads/api/reference/rpc/latest/ApplyRecommendationOperation#apply_parameters

  return operation
end
detect_and_apply_recommendations.rb
      

Perl

sub build_recommendation_operation {
  my ($recommendation) = @_;

  # If you have a recommendation ID instead of a resource name, you can create a resource
  # name like this:
  # my $recommendation_resource_name =
  #   Google::Ads::GoogleAds::V25::Utils::ResourceNames::recommendation(
  #   $customer_id, $recommendation_id);

  # Each recommendation type has optional parameters to override the recommended values.
  # Below is an example showing how to override a recommended ad when a TextAdRecommendation
  # is applied.
  # my $overriding_ad = Google::Ads::GoogleAds::V25::Resources::Ad->new({
  #   id => "INSERT_AD_ID_AS_INTEGER_HERE"
  # });
  # my $text_ad_parameters =
  #   Google::Ads::GoogleAds::V25::Services::RecommendationService::TextAdParameters
  #   ->new({ad => $overriding_ad});
  # $apply_recommendation_operation->{textAd} = $text_ad_parameters;

  # Create an apply recommendation operation.
  my $apply_recommendation_operation =
    Google::Ads::GoogleAds::V25::Services::RecommendationService::ApplyRecommendationOperation
    ->new({
      resourceName => $recommendation->{resourceName}});

  return $apply_recommendation_operation;
}
detect_and_apply_recommendations.pl
      

curl

ملاحظة: على الرغم من عدم توفّر عيّنة تعليمات برمجية مباشرة لواجهة REST لهذه الخطوة هنا، يمكنك تنفيذ ذلك باستخدام طلب REST يدوي.

يُرجى الرجوع إلى مستندات واجهة REST في Google Ads API وصفحات المراجع الخاصة بالطريقة. عليك إنشاء حِمل JSON استنادًا إلى تعريفات proto.

المَراجع الرئيسية:

• باستخدام REST
• بنية واجهة REST
• عمليات ربط حقول JSON
• يُرجى الرجوع إلى مرجع REST API للاطّلاع على الخدمة والطريقة المحدّدة.

يستدعي المثال التالي ApplyRecommendation، ويرسل عمليات تطبيق الاقتراحات التي تم إنشاؤها في الرمز البرمجي السابق.

جافا

// Issues a mutate request to apply the recommendations.
ApplyRecommendationResponse applyRecommendationsResponse =
    recommendationServiceClient.applyRecommendation(
        Long.toString(customerId), applyRecommendationOperations);
for (ApplyRecommendationResult applyRecommendationResult :
    applyRecommendationsResponse.getResultsList()) {
  System.out.printf(
      "Applied recommendation with resource name: '%s'.%n",
      applyRecommendationResult.getResourceName());
}
DetectAndApplyRecommendations.java
      

#C

private void ApplyRecommendation(GoogleAdsClient client, long customerId,
    List<ApplyRecommendationOperation> operations)
{
    // Get the RecommendationServiceClient.
    RecommendationServiceClient recommendationService = client.GetService(
        Services.V25.RecommendationService);

    ApplyRecommendationRequest applyRecommendationRequest = new ApplyRecommendationRequest()
    {
        CustomerId = customerId.ToString(),
    };

    applyRecommendationRequest.Operations.AddRange(operations);

    ApplyRecommendationResponse response =
        recommendationService.ApplyRecommendation(applyRecommendationRequest);
    foreach (ApplyRecommendationResult result in response.Results)
    {
        Console.WriteLine("Applied a recommendation with resource name: " +
            result.ResourceName);
    }
}
DetectAndApplyRecommendations.cs
      

PHP

private static function applyRecommendations(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    array $operations
): void {
    // Issues a mutate request to apply the recommendations.
    $recommendationServiceClient = $googleAdsClient->getRecommendationServiceClient();
    $response = $recommendationServiceClient->applyRecommendation(
        ApplyRecommendationRequest::build($customerId, $operations)
    );
    foreach ($response->getResults() as $appliedRecommendation) {
        /** @var Recommendation $appliedRecommendation */
        printf(
            "Applied a recommendation with resource name: '%s'.%s",
            $appliedRecommendation->getResourceName(),
            PHP_EOL
        );
    }
}
DetectAndApplyRecommendations.php
      

Python

def apply_recommendations(
    client: GoogleAdsClient,
    customer_id: str,
    operations: List[ApplyRecommendationOperation],
) -> None:
    """Applies a batch of recommendations.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        operations: a list of ApplyRecommendationOperation messages.
    """
    # Issues a mutate request to apply the recommendations.
    recommendation_service = client.get_service("RecommendationService")
    response: ApplyRecommendationResult = (
        recommendation_service.apply_recommendation(
            customer_id=customer_id, operations=operations
        )
    )

    for result in response.results:
        print(
            "Applied a recommendation with resource name: "
            f"'{result.resource_name}'."
        )
detect_and_apply_recommendations.py
      

Ruby

def apply_recommendations(client, customer_id, operations)
  # Issues a mutate request to apply the recommendation.
  recommendation_service = client.service.recommendation

  response = recommendation_service.apply_recommendation(
    customer_id: customer_id,
    operations: [operations],
  )

  response.results.each do |applied_recommendation|
    puts "Applied recommendation with resource name: '#{applied_recommendation.resource_name}'."
  end
end
detect_and_apply_recommendations.rb
      

Perl

# Issue a mutate request to apply the recommendations.
my $apply_recommendation_response =
  $api_client->RecommendationService()->apply({
    customerId => $customer_id,
    operations => $apply_recommendation_operations
  });

foreach my $result (@{$apply_recommendation_response->{results}}) {
  printf "Applied recommendation with resource name: '%s'.\n",
    $result->{resourceName};
}
detect_and_apply_recommendations.pl
      

curl

# Applies a recommendation.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   DEVELOPER_TOKEN,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
#   RECOMMENDATION_RESOURCE_NAME: The resource name of the recommendation to
#     apply, from the previous request.
curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/recommendations:apply" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "operations": [
    {
      "resourceName": "${RECOMMENDATION_RESOURCE_NAME}"
    }
  ]
}
EOF
detect_and_apply_recommendations.sh
      

رفض الاقتراحات

يمكنك رفض الاقتراحات باستخدام RecommendationService. تشبه بنية الرمز البرمجي تطبيق الاقتراحات، ولكن بدلاً من ذلك، يمكنك استخدام DismissRecommendationOperation وRecommendationService.DismissRecommendation.

العمليات المجمّعة ومعالجة الأخطاء

يقبل كل من ApplyRecommendation وDismissRecommendation ما يصل إلى 100 عملية لكل طلب. عند إرسال عمليات متعددة في طلب واحد، يُرجى مراعاة السلوكيات التالية:

• الجمع بين أنواع الاقتراحات: بشكل تلقائي (partial_failure = false)، يجب أن تستهدف جميع العمليات في طلب واحد نوع الاقتراح نفسه، وإلا ستعرض واجهة برمجة التطبيقات الخطأ RecommendationError.DIFFERENT_TYPES_NOT_SUPPORTED. لتطبيق اقتراحات من أنواع مختلفة أو رفضها في الطلب نفسه، اضبط قيمة partial_failure على true في الطلب لضمان نجاح العمليات الصالحة بشكل مستقل.
• أخطاء مراحل النشاط: نظرًا لأنّه يتم تقييم الاقتراحات بشكل ديناميكي، يمكن أن تتغيّر حالة الاقتراح بين الاسترداد والإجراء. إذا سبق أن تم تطبيق اقتراح أو رفضه أو لم يعُد منطبقًا، ستعرض واجهة برمجة التطبيقات RECOMMENDATION_ALREADY_APPLIED أو RECOMMENDATION_ALREADY_DISMISSED أو RECOMMENDATION_INVALIDATED في RecommendationError.

تطبيق الاقتراحات تلقائيًا

يمكنك استخدام RecommendationSubscriptionService لتطبيق اقتراحات من نوع معيّن تلقائيًا.

للاشتراك في نوع اقتراح معيّن، أنشئ عنصر RecommendationSubscription، واضبط الحقل type على أحد أنواع الاقتراحات المتوافقة، واضبط الحقل status على ENABLED.

أنواع الاقتراحات المتوافقة مع الاشتراك

• ENHANCED_CPC_OPT_IN
• KEYWORD
• KEYWORD_MATCH_TYPE
• LOWER_TARGET_ROAS
• MAXIMIZE_CLICKS_OPT_IN
• OPTIMIZE_AD_ROTATION
• RAISE_TARGET_CPA
• RESPONSIVE_SEARCH_AD
• RESPONSIVE_SEARCH_AD_IMPROVE_AD_STRENGTH
• SEARCH_PARTNERS_OPT_IN
• SET_TARGET_CPA
• SET_TARGET_ROAS
• TARGET_CPA_OPT_IN
• TARGET_ROAS_OPT_IN
• USE_BROAD_MATCH_KEYWORD

استرداد الاشتراكات

للحصول على معلومات عن اشتراكات الاقتراحات في حساب معيّن، يمكنك الاستعلام عن المورد recommendation_subscription.

للاطّلاع على التغييرات التي تم تطبيقها تلقائيًا، استخدِم طلب بحث في مورد change_event، مع فلترة change_event.client_type إلى GOOGLE_ADS_RECOMMENDATIONS_SUBSCRIPTION.

الاقتراحات في عملية إنشاء الحملة

يمكنك استخدام RecommendationService.GenerateRecommendationsRequest لإنشاء اقتراحات أثناء إنشاء الحملة، وذلك لمجموعة معيّنة من أنواع الاقتراحات.

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

ملاحظة مهمة: لا يعرض RecommendationService أخطاء عند تقديم بيانات غير كافية لنوع اقتراح معيّن. يمكنك الرجوع إلى المستندات لتحديد البيانات التي يجب تقديمها.

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

RecommendationType	حقول مطلوبة	حقول اختيارية
CAMPAIGN_BUDGET	بالنسبة إلى كلّ من "الحملات على شبكة البحث" و"حملات الأداء الأفضل"، يجب ملء الحقول التالية: asset_group_info final_url bidding_strategy_type بالنسبة إلى "الحملات على شبكة البحث" فقط، يجب أيضًا ملء الحقول التالية: country_code language_code positive_location_id أو negative_location_id ad_group_info.keywords ‫bidding_info. bidding_strategy_target_info. target_impression_share_info إذا تم ضبط استراتيجية عروض الأسعار على TARGET_IMPRESSION_SHARE	budget_info بالنسبة إلى "حملات الأداء الأفضل"، أدخِل قيمة في الحقل merchant_center_account_id لإعلام RecommendationsService بإنشاء اقتراحات لـ "حملات الأداء الأفضل" للبيع بالتجزئة بدلاً من "حملات الأداء الأفضل" العادية.
KEYWORD	seed_info	ad_group_info
MAXIMIZE_CLICKS_OPT_IN	conversion_tracking_status bidding_info
MAXIMIZE_CONVERSIONS_OPT_IN	conversion_tracking_status bidding_info
MAXIMIZE_CONVERSION_VALUE_OPT_IN	conversion_tracking_status bidding_info
SET_TARGET_CPA	conversion_tracking_status bidding_info
SET_TARGET_ROAS	conversion_tracking_status bidding_info
SITELINK_ASSET ملاحظة: سيحتوي العنصر الذي تم عرضه SitelinkAssetRecommendation على قوائم فارغة. إذا كان الردّ GenerateRecommendations يتضمّن SitelinkAssetRecommendation، يمكن اعتباره إشارة لإضافة مادة عرض رابط إلى قسم الموقع واحدة على الأقل إلى الحملة.	campaign_sitelink_count
TARGET_CPA_OPT_IN	conversion_tracking_status bidding_info
TARGET_ROAS_OPT_IN	conversion_tracking_status bidding_info

مثال على مسار الاستخدام

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

قد يبدو سير الاستخدام على النحو التالي:

1. يصل مستخدم إلى تطبيقك لإنشاء "حملة أداء أفضل".

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

3. أرسلت طلب GenerateRecommendationsRequest يضبط الحقول التالية:

   • استبدِل campaign_sitelink_count بالقيمة 1، وهي عدد مواد عرض روابط أقسام الموقع في الحملة قيد الإنشاء.

   • bidding_info: اضبط الحقل المُدمَج bidding_strategy_type على TARGET_SPEND.

   • ‫conversion_tracking_status: يتم ضبطها على ConversionTrackingStatus لهذا العميل. للحصول على إرشادات حول كيفية استرداد هذا الحقل، يُرجى الانتقال إلى دليل البدء الخاص بإدارة الإحالات الناجحة.

   • ‫recommendation_types: تم ضبطها على [SITELINK_ASSET, MAXIMIZE_CLICKS_OPT_IN].

   • ‫advertising_channel_type: اضبط السمة على PERFORMANCE_MAX.

   • customer_id: يتم ضبطه على رقم تعريف العميل الذي ينشئ الحملة.

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