Skor pengoptimalan dan rekomendasi

Rekomendasi dapat meningkatkan kualitas kampanye Anda dengan beberapa cara:

  • Memperkenalkan fitur baru yang relevan
  • Dapatkan hasil maksimal dari anggaran Anda dengan bid, kata kunci, dan iklan yang lebih baik
  • Meningkatkan keseluruhan performa dan efisiensi kampanye Anda

Untuk meningkatkan skor pengoptimalan, Anda dapat menggunakan RecommendationService untuk mengambil rekomendasi, lalu menerapkan atau menolaknya. Anda juga dapat berlangganan untuk menerapkan rekomendasi secara otomatis menggunakan RecommendationSubscriptionService.

Skor pengoptimalan

Skor pengoptimalan adalah estimasi seberapa baik penyiapan akun Google Ads Anda agar berperforma maksimal dan tersedia di tingkat Customer dan Campaign.

Ada metrik terkait pengoptimalan yang tersedia untuk laporan customer dan campaign:

  1. metrics.optimization_score_url menyediakan deep link ke akun untuk melihat informasi tentang rekomendasi terkait di UI Google Ads.
  2. metrics.optimization_score_uplift menunjukkan seberapa besar skor pengoptimalan akan meningkat jika semua rekomendasi terkait diterapkan. Ini adalah estimasi berdasarkan semua rekomendasi yang tersedia secara keseluruhan, bukan hanya jumlah skor peningkatan untuk setiap rekomendasi.

Untuk mengelompokkan dan mengurutkan rekomendasi yang ditampilkan, Anda dapat menyegmentasikan kedua metrik ini menurut jenis rekomendasi menggunakan segments.recommendation_type dalam kueri Anda.

Jenis rekomendasi

Tabel berikut mencantumkan jenis rekomendasi yang didukung di Google Ads API untuk mengambil, menerapkan, dan menolak rekomendasi. Jika akun memiliki jenis rekomendasi di UI Google Ads yang tidak didukung di API, Anda dapat menggunakan metrics.optimization_score_url untuk menautkan pengguna langsung ke halaman Rekomendasi di UI Google Ads untuk meninjau dan menindaklanjuti rekomendasi tersebut.

Jenis rekomendasi yang didukung sepenuhnya

RecommendationType Deskripsi
CAMPAIGN_BUDGET Perbaiki kampanye yang dibatasi anggaran
KEYWORD Tambahkan kata kunci baru
TEXT_AD Tambahkan rekomendasi iklan
TARGET_CPA_OPT_IN Ajukan bid dengan Target CPA
MAXIMIZE_CONVERSIONS_OPT_IN Mengajukan bid dengan Maksimalkan Konversi
MAXIMIZE_CONVERSION_VALUE_OPT_IN Ajukan bid dengan Maksimalkan Nilai Konversi
ENHANCED_CPC_OPT_IN Ajukan bid dengan Enhanced CPC
MAXIMIZE_CLICKS_OPT_IN Ajukan bid dengan Maksimalkan Klik
OPTIMIZE_AD_ROTATION Menggunakan rotasi iklan yang dioptimalkan
MOVE_UNUSED_BUDGET Memindahkan anggaran yang tidak terpakai ke anggaran yang terbatas
TARGET_ROAS_OPT_IN Ajukan bid dengan Target ROAS
FORECASTING_CAMPAIGN_BUDGET Perbaiki kampanye yang diperkirakan akan dibatasi anggaran pada masa mendatang
RESPONSIVE_SEARCH_AD Menambahkan iklan penelusuran responsif baru
MARGINAL_ROI_CAMPAIGN_BUDGET Menyesuaikan anggaran kampanye untuk meningkatkan ROI
USE_BROAD_MATCH_KEYWORD Gunakan pencocokan luas untuk kampanye berbasis konversi dengan bidding otomatis
RESPONSIVE_SEARCH_AD_ASSET Menambahkan aset iklan penelusuran responsif ke iklan
RESPONSIVE_SEARCH_AD_IMPROVE_AD_STRENGTH Meningkatkan daya iklan penelusuran responsif
DISPLAY_EXPANSION_OPT_IN Memperbarui kampanye untuk menggunakan Perluasan Display
SEARCH_PARTNERS_OPT_IN Perluas jangkauan dengan partner Penelusuran Google
CUSTOM_AUDIENCE_OPT_IN Buat audiens kustom
IMPROVE_DEMAND_GEN_AD_STRENGTH Meningkatkan daya iklan di kampanye Peningkat Permintaan
UPGRADE_SMART_SHOPPING_CAMPAIGN_TO_PERFORMANCE_MAX Mengupgrade kampanye Shopping Pintar ke kampanye Performa Maksimal
UPGRADE_LOCAL_CAMPAIGN_TO_PERFORMANCE_MAX Mengupgrade kampanye lokal lama ke kampanye Performa Maksimal
SHOPPING_MIGRATE_REGULAR_SHOPPING_CAMPAIGN_OFFERS_TO_PERFORMANCE_MAX Memigrasikan penawaran yang ditargetkan oleh Kampanye Shopping Standar ke kampanye Performa Maksimal yang ada
MIGRATE_DYNAMIC_SEARCH_ADS_CAMPAIGN_TO_PERFORMANCE_MAX Memigrasikan Iklan Penelusuran Dinamis ke kampanye Performa Maksimal
PERFORMANCE_MAX_OPT_IN Membuat kampanye Performa Maksimal di akun Anda
IMPROVE_PERFORMANCE_MAX_AD_STRENGTH Meningkatkan kekuatan grup aset kampanye Performa Maksimal ke rating "Sangat Baik"
PERFORMANCE_MAX_FINAL_URL_OPT_IN Mengaktifkan perluasan URL Final untuk kampanye Performa Maksimal
RAISE_TARGET_CPA_BID_TOO_LOW Naikkan target CPA jika terlalu rendah dan konversi sangat sedikit atau tidak ada
FORECASTING_SET_TARGET_ROAS Naikkan anggaran sebelum acara musiman yang diperkirakan akan meningkatkan traffic, dan ubah strategi bidding dari maksimalkan nilai konversi menjadi target ROAS
LEAD_FORM_ASSET Menambahkan aset formulir prospek ke kampanye
CALLOUT_ASSET Menambahkan aset info ke tingkat kampanye atau pelanggan
SITELINK_ASSET Menambahkan aset sitelink ke tingkat kampanye atau pelanggan
CALL_ASSET Menambahkan aset panggilan ke tingkat kampanye atau pelanggan
SHOPPING_ADD_AGE_GROUP Tambahkan atribut kelompok usia ke penawaran yang didemosi karena kelompok usia tidak ada
SHOPPING_ADD_COLOR Menambahkan warna ke penawaran yang diturunkan karena warna tidak ada
SHOPPING_ADD_GENDER Tambahkan gender ke penawaran yang didemosi karena tidak ada gender
SHOPPING_ADD_GTIN Tambahkan GTIN (Nomor Barang Perdagangan Global) ke penawaran yang didemosi karena tidak memiliki GTIN
SHOPPING_ADD_MORE_IDENTIFIERS Tambahkan lebih banyak ID ke penawaran yang didemosi karena tidak ada ID
SHOPPING_ADD_SIZE Tambahkan ukuran ke penawaran yang diturunkan karena ukuran tidak ada
SHOPPING_ADD_PRODUCTS_TO_CAMPAIGN Menambahkan produk agar kampanye dapat ditayangkan
SHOPPING_FIX_DISAPPROVED_PRODUCTS Perbaiki produk yang tidak disetujui
SHOPPING_TARGET_ALL_OFFERS Membuat kampanye umum yang menargetkan semua penawaran
SHOPPING_FIX_SUSPENDED_MERCHANT_CENTER_ACCOUNT Memperbaiki masalah penangguhan akun Merchant Center
SHOPPING_FIX_MERCHANT_CENTER_ACCOUNT_SUSPENSION_WARNING Memperbaiki masalah peringatan penangguhan akun Merchant Center
DYNAMIC_IMAGE_EXTENSION_OPT_IN Mengaktifkan ekstensi gambar dinamis di akun
RAISE_TARGET_CPA Naikkan Target CPA
LOWER_TARGET_ROAS Target ROAS yang lebih rendah
FORECASTING_SET_TARGET_CPA Tetapkan target CPA untuk kampanye yang belum memilikinya, sebelum peristiwa musiman yang diperkirakan akan meningkatkan traffic
SET_TARGET_CPA Tetapkan target CPA untuk kampanye yang belum memiliki target CPA
SET_TARGET_ROAS Menetapkan target ROAS untuk kampanye yang belum memiliki target ROAS
REFRESH_CUSTOMER_MATCH_LIST Memperbarui daftar pelanggan yang belum diperbarui dalam 90 hari terakhir
IMPROVE_GOOGLE_TAG_COVERAGE Men-deploy Tag Google di lebih banyak halaman
CAMPAIGN_SPECIFIC_APP_GOAL Menambahkan sasaran konversi aplikasi spesifik per kampanye
RAISE_TARGET_CPA_PERFORMANCE_BID_TOO_LOW Menaikkan Target CPA jika terlalu rendah untuk kampanye Penelusuran
LOWER_TARGET_ROAS_PERFORMANCE_BID_TOO_LOW Turunkan Target ROAS jika terlalu rendah untuk kampanye Penelusuran
RAISE_BUDGET_PERFORMANCE_TOO_LOW Naikkan anggaran jika terlalu rendah untuk kampanye Penelusuran. Tersedia mulai di v26. Detail rekomendasi ditampilkan di Recommendation.raise_budget_performance_too_low_recommendation dan diterapkan menggunakan ApplyRecommendationOperation.raise_budget_performance_too_low.
KEYWORD_MATCH_TYPE (tidak digunakan lagi) Tidak digunakan lagi, gunakan USE_BROAD_MATCH_KEYWORD sebagai gantinya

Mengambil rekomendasi

Seperti kebanyakan entity lainnya di Google Ads API, objek Recommendation diambil menggunakan GoogleAdsService.SearchStream dengan kueri Bahasa Kueri Google Ads.

Untuk setiap jenis rekomendasi, detail diberikan dalam kolom khusus rekomendasi. Misalnya, detail rekomendasi CAMPAIGN_BUDGET ada di kolom campaign_budget_recommendation, dan dibungkus dalam objek CampaignBudgetRecommendation.

Temukan semua kolom khusus rekomendasi di kolom gabungan recommendation.

Dampak rekomendasi

Beberapa jenis rekomendasi mengisi kolom impact rekomendasi. RecommendationImpact berisi estimasi dampak pada performa akun sebagai hasil dari penerapan rekomendasi. Metrik rekomendasi berikut tersedia di kolom impact.base_metrics dan impact.potential_metrics:

  • impressions

  • clicks

  • cost_micros

  • conversions

  • all_conversions

  • video_views

Meskipun kolom impact diisi, ketersediaan metrik bervariasi bergantung pada jenis rekomendasi dan jenis kampanye, di antara faktor lainnya. Secara umum, periksa ketersediaan setiap metrik dampak sebelum mencoba menggunakannya.

Contoh kode

Contoh kode berikut mengambil semua rekomendasi yang tersedia dan ditutup berjenis KEYWORD dari akun dan mencetak beberapa detailnya:

Java

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));
    }
  }

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;
}

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());
}

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)
    )

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

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);
  });

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

Ambil tindakan

Setiap rekomendasi yang diambil dapat diterapkan atau ditolak.

Bergantung pada jenis rekomendasi, rekomendasi dapat berubah setiap hari atau bahkan beberapa kali sehari. Jika hal itu terjadi, resource_name objek rekomendasi dapat menjadi usang setelah rekomendasi diambil.

Sebaiknya ambil tindakan berdasarkan rekomendasi segera setelah pengambilan.

Menerapkan rekomendasi

Anda dapat menerapkan rekomendasi aktif atau yang ditolak dengan metode ApplyRecommendation dari RecommendationService.

Jenis rekomendasi dapat memiliki parameter wajib atau opsional. Sebagian besar rekomendasi disertai dengan nilai yang direkomendasikan yang digunakan secara default.

Menyetel akun untuk penerapan otomatis rekomendasi tidak didukung untuk semua jenis rekomendasi. Namun, Anda dapat menerapkan perilaku serupa untuk jenis rekomendasi yang didukung sepenuhnya oleh Google Ads API. Lihat contoh kode DetectAndApplyRecommendations untuk mempelajari lebih lanjut.

Gunakan kolom gabungan apply_parameters dari ApplyRecommendationOperation untuk menerapkan rekomendasi dengan nilai parameter tertentu. Setiap jenis rekomendasi yang sesuai memiliki kolomnya sendiri. Jenis rekomendasi apa pun yang tidak tercantum dalam kolom apply_parameters tidak menggunakan nilai parameter ini.

Contoh kode

Kode berikut menunjukkan cara membuat ApplyRecommendationOperation dan cara mengganti nilai yang direkomendasikan jika Anda ingin menggantinya dengan nilai Anda sendiri.

Java

/** 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();
}

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;
}

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;
}

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

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

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;
}

curl

Contoh berikutnya memanggil ApplyRecommendation, yang mengirimkan operasi penerapan rekomendasi yang dibuat dalam kode sebelumnya.

Java

// 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());
}

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);
    }
}

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
        );
    }
}

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

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

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};
}

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

Menolak rekomendasi

Anda dapat menolak rekomendasi dengan RecommendationService. Struktur kodenya mirip dengan menerapkan rekomendasi, tetapi Anda menggunakan DismissRecommendationOperation dan RecommendationService.DismissRecommendation.

Operasi massal dan penanganan error

ApplyRecommendation dan DismissRecommendation menerima hingga 100 operasi per permintaan. Saat mengirim beberapa operasi dalam satu permintaan, perhatikan perilaku berikut:

  • Mencampur jenis rekomendasi: Secara default (partial_failure = false), semua operasi dalam satu permintaan harus menargetkan jenis rekomendasi yang sama; jika tidak, API akan menampilkan RecommendationError.DIFFERENT_TYPES_NOT_SUPPORTED. Untuk menerapkan atau menolak rekomendasi dari berbagai jenis dalam permintaan yang sama, tetapkan partial_failure ke true pada permintaan agar operasi yang valid berhasil secara independen.
  • Error siklus proses: Karena rekomendasi dievaluasi secara dinamis, status rekomendasi dapat berubah antara pengambilan dan tindakan. Jika rekomendasi sudah diterapkan, sudah ditutup, atau tidak lagi berlaku, API akan menampilkan RECOMMENDATION_ALREADY_APPLIED, RECOMMENDATION_ALREADY_DISMISSED, atau RECOMMENDATION_INVALIDATED di RecommendationError.

Terapkan rekomendasi secara otomatis

Anda dapat menggunakan RecommendationSubscriptionService untuk menerapkan rekomendasi jenis tertentu secara otomatis.

Untuk berlangganan jenis rekomendasi tertentu, buat objek RecommendationSubscription, tetapkan kolom type ke salah satu jenis rekomendasi yang didukung, dan tetapkan kolom status ke ENABLED.

Jenis rekomendasi yang mendukung langganan

  • 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

Mengambil langganan

Untuk mendapatkan informasi tentang langganan rekomendasi akun, buat kueri resource recommendation_subscription.

Untuk melihat perubahan yang diterapkan secara otomatis, buat kueri resource change_event, dengan memfilter change_event.client_type ke GOOGLE_ADS_RECOMMENDATIONS_SUBSCRIPTION.

Rekomendasi dalam pembuatan kampanye

Anda dapat menggunakan RecommendationService.GenerateRecommendationsRequest untuk membuat rekomendasi selama pembuatan kampanye, untuk kumpulan jenis rekomendasi tertentu.

GenerateRecommendations menerima ID pelanggan sebagai input, jenis saluran iklan yang harus berupa SEARCH atau PERFORMANCE_MAX, daftar jenis rekomendasi yang akan dibuat, dan berbagai titik data yang bergantung pada jenis yang ditentukan. Model ini menampilkan daftar objek Recommendation berdasarkan data yang Anda berikan. Jika data yang cukup untuk membuat rekomendasi untuk recommendation_types yang diminta tidak ada, atau jika kampanye sudah dalam status yang direkomendasikan, set hasil tidak akan berisi rekomendasi untuk jenis tersebut. Pastikan aplikasi Anda menangani kasus saat tidak ada rekomendasi yang ditampilkan untuk jenis rekomendasi yang diminta.

Tabel berikut menjelaskan jenis rekomendasi yang didukung GenerateRecommendations, dan kolom yang harus Anda berikan untuk menerima rekomendasi untuk jenis tersebut. Sebagai praktik terbaik, kirim permintaan GenerateRecommendations setelah semua informasi dikumpulkan terkait jenis rekomendasi yang diminta. Untuk mengetahui detail tambahan tentang kolom wajib dan opsional, termasuk kolom bertingkat, lihat dokumentasi referensi.

RecommendationType Kolom wajib diisi Kolom opsional
CAMPAIGN_BUDGET Untuk kampanye Penelusuran dan Performa Maksimal, kolom berikut wajib diisi:
  • asset_group_info
  • final_url
  • bidding_strategy_type
Khusus untuk kampanye Penelusuran, kolom berikut juga wajib diisi:
  • country_code
  • language_code
  • positive_location_id atau negative_location_id
  • ad_group_info.keywords
  • bidding_info.
    bidding_strategy_target_info.
    target_impression_share_info     jika strategi bidding ditetapkan ke TARGET_IMPRESSION_SHARE
  • budget_info
  • Untuk kampanye Performa Maksimal, berikan nilai di kolom merchant_center_account_id untuk menunjukkan kepada RecommendationsService agar membuat rekomendasi untuk kampanye Performa Maksimal retail, bukan standar.
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
Catatan: Objek SitelinkAssetRecommendation yang ditampilkan akan berisi daftar kosong. Jika respons GenerateRecommendations berisi SitelinkAssetRecommendation, respons tersebut dapat dianggap sebagai sinyal untuk menambahkan setidaknya satu aset sitelink ke kampanye.
  • campaign_sitelink_count
TARGET_CPA_OPT_IN
  • conversion_tracking_status
  • bidding_info
TARGET_ROAS_OPT_IN
  • conversion_tracking_status
  • bidding_info

Contoh alur penggunaan

Misalkan perusahaan Anda adalah agensi periklanan yang menyediakan alur kerja pembuatan kampanye kepada pengguna, dan Anda ingin menawarkan saran kepada pengguna selama alur tersebut. Anda dapat menggunakan GenerateRecommendationsRequest untuk membuat rekomendasi sesuai permintaan, dan menggabungkan rekomendasi tersebut ke dalam antarmuka pengguna pembuatan kampanye.

Alur penggunaannya mungkin terlihat seperti berikut:

  1. Seorang pengguna membuka aplikasi Anda untuk membuat kampanye Performa Maksimal.

  2. Pengguna memberikan beberapa informasi awal sebagai bagian dari alur pembuatan kampanye. Misalnya, mereka memberikan detail untuk membuat satu SitelinkAsset, dan mereka memilih TARGET_SPEND sebagai strategi Smart Bidding mereka.

  3. Anda mengirim GenerateRecommendationsRequest yang menetapkan kolom berikut:

    • campaign_sitelink_count: ditetapkan ke 1, yang merupakan jumlah aset sitelink di kampanye yang sedang dikerjakan.

    • bidding_info: tetapkan kolom bidding_strategy_type bertingkat ke TARGET_SPEND.

    • conversion_tracking_status: ditetapkan ke ConversionTrackingStatus pelanggan ini. Untuk panduan tentang cara mengambil kolom ini, buka panduan Memulai untuk pengelolaan konversi.

    • recommendation_types: tetapkan ke [SITELINK_ASSET, MAXIMIZE_CLICKS_OPT_IN].

    • advertising_channel_type: tetapkan ke PERFORMANCE_MAX.

    • customer_id: ditetapkan ke ID pelanggan yang membuat kampanye.

  4. Anda dapat mengambil rekomendasi di GenerateRecommendationsResponse — dalam hal ini, SitelinkAssetRecommendation dan MaximizeClicksOptInRecommendation — dan menyarankannya kepada pengguna dengan menampilkannya dalam antarmuka pembuatan kampanye Anda. Jika pengguna menerima saran, Anda dapat menggabungkannya ke dalam permintaan pembuatan kampanye setelah pengguna menyelesaikan alur pembuatan kampanye.