Эта страница переведена с помощью Cloud Translation API.

Стимулы

Бонусы — это рекламные предложения, предоставляемые пользователям для стимулирования использования Google Ads. В этом руководстве объясняется, как использовать API Google Ads для программного получения и применения бонусов Google Ads для ваших клиентов.

Примечание: Для упрощения детальной программной обработки сбоев, IncentiveError в IncentiveErrorEnum включает в себя специфические режимы обработки сбоев, введенные в v23 ( INVALID_INCENTIVE_ID , MAX_INCENTIVES_REDEEMED и ACCOUNT_TOO_OLD ) и добавленные в v25 ( BILLING_COUNTRY_NOT_ELIGIBLE , USER_IS_MCC_MANAGER , USER_SUSPENDED , MAX_PENDING_INCENTIVES , ACCOUNT_HAD_RECENT_SPEND , MAX_INCENTIVES_REDEEMED_FROM_OFFER и MISMATCHING_BILLING_COUNTRY_CODE ). Следите за предстоящими объявлениями и примечаниями к выпуску, чтобы убедиться, что ваши приложения могут обрабатывать эти режимы обработки сбоев.

Получите бонусы

Для получения информации о доступных бонусах для клиента можно использовать метод IncentiveService.FetchIncentive . Этот метод может возвращать персонализированные варианты бонусов, которые можно выбрать самостоятельно (CYO).

Запрос FetchIncentiveRequest может включать в себя:

language_code : Языковой код клиента в соответствии с BCP 47 (по умолчанию en ).
country_code : Двухбуквенный код страны клиента по стандарту ISO 3166-1 alpha-2 (по умолчанию — US ).
email : Адрес электронной почты клиента. Начиная с v24 , если указан недействительный адрес электронной почты, FetchIncentive возвращает стандартные предложения по бонусам; в v23 недействительный адрес электронной почты вызывает ошибку AuthenticationError.INVALID_EMAIL_ADDRESS .
incentive_type (в v25 и более поздних; именованный type с вложенным перечислением FetchIncentiveRequest.IncentiveType в v24 и более ранних): IncentiveType стимула для получения (по умолчанию ACQUISITION , если опущен). API Google Ads поддерживает стимулы типа ACQUISITION , которые предназначены только для новых аккаунтов (аккаунтов, которые показывают рекламу менее 14 дней).

Объект FetchIncentiveResponse содержит объект IncentiveOffer , который включает в себя consolidated_terms_and_conditions_url . Если OfferType в offer_type (именованный type с вложенным перечислением IncentiveOffer.OfferType в v24 и более ранних) равен CYO_INCENTIVE , то поле cyo_incentives содержит low_offer , medium_offer и high_offer , каждый из которых представляет собой Incentive с такими подробностями, как incentive_id , incentive_type (именованный type в v24 и более ранних), requirement и incentive_terms_and_conditions_url . Если для пользователя нет доступного объекта IncentiveOffer, то поле IncentiveOffer offer_type имеет значение NO_INCENTIVE , а поле incentive_details не устанавливается.

Следующий пример показывает, как получить поощрительные выплаты:

Java

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.ads.googleads.examples.incentives;

import com.beust.jcommander.Parameter;
import com.google.ads.googleads.examples.utils.ArgumentNames;
import com.google.ads.googleads.examples.utils.CodeSampleParams;
import com.google.ads.googleads.lib.GoogleAdsClient;
import com.google.ads.googleads.v25.errors.GoogleAdsError;
import com.google.ads.googleads.v25.errors.GoogleAdsException;
import com.google.ads.googleads.v25.services.CyoIncentives;
import com.google.ads.googleads.v25.services.FetchIncentiveRequest;
import com.google.ads.googleads.v25.enums.IncentiveTypeEnum.IncentiveType;
import com.google.ads.googleads.v25.services.FetchIncentiveResponse;
import com.google.ads.googleads.v25.services.Incentive;
import com.google.ads.googleads.v25.services.IncentiveServiceClient;
import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * This example fetches the available incentives for a user.
 */
public class FetchIncentives {

  private static class FetchIncentivesParams extends CodeSampleParams {

    @Parameter(
        names = ArgumentNames.EMAIL_ADDRESS,
        required = true,
        description = "The email of the user to fetch incentives for.")
    private String email;

    @Parameter(
        names = ArgumentNames.LANGUAGE_CODE,
        description = "The language for the returned incentive.")
    private String languageCode = "en";

    @Parameter(
        names = ArgumentNames.COUNTRY_CODE,
        description = "The country for the returned incentive.")
    private String countryCode = "US";
  }

  public static void main(String[] args) throws IOException {
    FetchIncentivesParams params = new FetchIncentivesParams();
    if (!params.parseArguments(args)) {
      // Either pass the required parameters for this example on the command line, or insert them
      // into the code here. See the parameter class definition above for more information.
      params.email = "INSERT_EMAIL_HERE";
    }

    GoogleAdsClient googleAdsClient = null;
    try {
      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
    } catch (FileNotFoundException fnfe) {
      System.err.printf(
          "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
      System.exit(1);
    } catch (IOException ioe) {
      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
      System.exit(1);
    }

    try {
      new FetchIncentives()
          .runExample(googleAdsClient, params.email, params.languageCode, params.countryCode);
    } catch (GoogleAdsException gae) {
      // GoogleAdsException is the base class for most exceptions thrown by an API request.
      // Instances of this exception have a message and a GoogleAdsFailure that contains a
      // collection of GoogleAdsError instances that detail the underlying causes of the
      // exception.
      System.err.printf(
          "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
          gae.getRequestId());
      int i = 0;
      for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
        System.err.printf("  Error %d: %s%n", i++, googleAdsError);
      }
      System.exit(1);
    }
  }

  /**
   * Runs the example.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param email the email of the user to fetch incentives for.
   * @param languageCode the language of the incentives.
   * @param countryCode the country of the incentives.
   */
  private void runExample(
      GoogleAdsClient googleAdsClient, String email, String languageCode, String countryCode) {
    try (IncentiveServiceClient incentiveServiceClient =
        googleAdsClient.getLatestVersion().createIncentiveServiceClient()) {
      FetchIncentiveRequest request = FetchIncentiveRequest.newBuilder().setCountryCode(countryCode)
          .setLanguageCode(languageCode).setEmail(email).setIncentiveType(IncentiveType.ACQUISITION).build();

      // Issues the request.
      FetchIncentiveResponse response =
          incentiveServiceClient.fetchIncentive(request);

      // Processes the response.
      if (!response.hasIncentiveOffer()) {
        System.out.print("No incentive offer was found");
        return;
      }

      // If the offer type is CHOOSE_YOUR_OWN_INCENTIVE, there will be 3 incentives in the
      // response. At the time this example was written, all incentive offers are CYO incentive offers.
      if (response.getIncentiveOffer().hasCyoIncentives()) {
        CyoIncentives cyoIncentives = response.getIncentiveOffer().getCyoIncentives();
        printIncentiveDetails(cyoIncentives.getLowOffer());
        printIncentiveDetails(cyoIncentives.getMediumOffer());
        printIncentiveDetails(cyoIncentives.getHighOffer());
      }
    }
  }

  private void printIncentiveDetails(Incentive incentive) {
    System.out.println("====================================================================");
    System.out.printf("Incentive ID: '%s'%n", incentive.getIncentiveId());
    System.out.printf("Incentive requirement: '%s'%n", incentive.getRequirement());
    System.out.printf(
        "Incentive terms and conditions: '%s'%n", incentive.getIncentiveTermsAndConditionsUrl());
    System.out.println("====================================================================");
  }
}


FetchIncentives.java

C#

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.Gax.Lib;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V25.Errors;
using Google.Ads.GoogleAds.V25.Services;
using System;
using static Google.Ads.GoogleAds.V25.Enums.IncentiveTypeEnum.Types;


namespace Google.Ads.GoogleAds.Examples.V25
{
    /// <summary>
    /// This code example fetches the available incentives for a user.
    /// </summary>
    public class FetchIncentives : ExampleBase
    {
         /// <summary>
        /// Command line options for running the <see cref="FetchIncentives"/> example.
        /// </summary>
        public class Options : OptionsBase
        {
            /// <summary>
            /// The email of the user to fetch incentives for.
            /// </summary>
            [Option("email", Required = true, HelpText =
                "The email of the user to fetch incentives for.")]
            public string Email { get; set; }

            /// <summary>
            /// The language for the returned incentive.
            /// </summary>
            [Option("languageCode", Required = true, HelpText =
                "The language for the returned incentive.")]
            public string LanguageCode { get; set; }

            /// <summary>
            /// The country for the returned incentive.
            /// </summary>
            [Option("countryCode", Required = true, HelpText =
                "The country for the returned incentive.")]
            public string CountryCode { get; set; }
        }

        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            Options options = ExampleUtilities.ParseCommandLine<Options>(args);

            FetchIncentives codeExample = new FetchIncentives();
            Console.WriteLine(codeExample.Description);
            codeExample.Run(new GoogleAdsClient(), options.Email,
            options.LanguageCode, options.CountryCode);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description =>
            "This code example fetches the available incentives for a user.";

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="email">The email of the user to fetch incentives for.</param>
        /// <param name="languageCode">The language for the returned incentive.</param>
        /// <param name="countryCode">The country for the returned incentive.</param>
        public void Run(GoogleAdsClient client, string email, string languageCode,
            string countryCode)
        {
            IncentiveServiceClient incentiveService = client.GetService(
                Services.V25.IncentiveService);

            FetchIncentiveRequest request = new FetchIncentiveRequest()
            {
                CountryCode = countryCode,
                LanguageCode = languageCode,
                Email = email,
                IncentiveType = IncentiveType.Acquisition                
            };

            try
            {
                FetchIncentiveResponse response =
                    incentiveService.FetchIncentive(request);

                if (response.IncentiveOffer.IsEmpty())
                {
                    Console.WriteLine("No incentive offer was found.");
                    return;
                }

                if (!response.IncentiveOffer.CyoIncentives.IsEmpty())
                {
                    CyoIncentives cyoIncentives = response.IncentiveOffer.CyoIncentives;
                    printIncentiveDetails(cyoIncentives.LowOffer);
                }

            } catch  (GoogleAdsException e)
            {
                Console.WriteLine("Failure:");
                Console.WriteLine($"Message: {e.Message}");
                Console.WriteLine($"Failure: {e.Failure}");
                Console.WriteLine($"Request ID: {e.RequestId}");
                throw;
            }
        }

        private void printIncentiveDetails(Incentive incentive)
        {
            Console.WriteLine("===========================================");
            Console.WriteLine($"Incentive ID: {incentive.IncentiveId}");
            Console.WriteLine($"Incentive requirement: {incentive.Requirement}");
            Console.WriteLine($"Incentive terms and conditions: {incentive.IncentiveTermsAndConditionsUrl}");
            Console.WriteLine("===========================================");
        }

    }
}FetchIncentives.cs

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

#!/usr/bin/env python
# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""This example returns incentives for a given user.

To apply an incentive, use apply_incentive.py.
"""

import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
from google.ads.googleads.v24.services import (
    FetchIncentiveRequest,
    FetchIncentiveResponse,
)
from google.ads.googleads.v24.services.services.incentive_service.client import (
    IncentiveServiceClient,
)


def main(
    client: GoogleAdsClient,
    email_address: str,
    language_code: str,
    country_code: str,
) -> None:
    """Returns incentives for a given user.

    Args:
        client: An initialized GoogleAdsClient instance.
        email_address: The email of the user to fetch incentives for.
        language_code: The language code of the user (e.g. 'en').
        country_code: The country code of the user (e.g. 'US').
    """
    incentive_service: IncentiveServiceClient = client.get_service(
        "IncentiveService"
    )
    fetch_incentive_request: FetchIncentiveRequest = client.get_type(
        "FetchIncentiveRequest"
    )

    fetch_incentive_request.email = email_address
    fetch_incentive_request.language_code = language_code
    fetch_incentive_request.country_code = country_code

    response: FetchIncentiveResponse = incentive_service.fetch_incentive(
        request=fetch_incentive_request
    )

    if response.incentive_offer and response.incentive_offer.cyo_incentives:
        print("Fetched incentive.")
        # If the offer type is CHOOSE_YOUR_OWN_INCENTIVE, there will be three
        # incentives in the response. At the time this example was written, all
        # incentive offers are CYO incentive offers.
        cyo_incentives = response.incentive_offer.cyo_incentives
        print(cyo_incentives.low_offer)
        print(cyo_incentives.medium_offer)
        print(cyo_incentives.high_offer)
    else:
        print("No incentives found.")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Returns incentives for a given user."
    )
    # The following argument(s) should be provided to run the example.
    parser.add_argument(
        "-e",
        "--email_address",
        type=str,
        required=True,
        help="The email of the user to fetch incentives for.",
    )
    parser.add_argument(
        "-l",
        "--language_code",
        type=str,
        required=False,
        default="en",
        help="The language code of the user (e.g. 'en').",
    )
    parser.add_argument(
        "-k",
        "--country_code",
        type=str,
        required=False,
        default="US",
        help="The country code of the user (e.g. 'US').",
    )
    args = parser.parse_args()

    # GoogleAdsClient will read the google-ads.yaml configuration file in the
    # home directory if none is specified.
    googleads_client = GoogleAdsClient.load_from_storage(version="v24")

    try:
        main(
            googleads_client,
            args.email_address,
            args.language_code,
            args.country_code,
        )
    except GoogleAdsException as ex:
        print(
            f'Request with ID "{ex.request_id}" failed with status '
            f'"{ex.error.code().name}" and includes the following errors:'
        )
        for error in ex.failure.errors:
            print(f'\tError with message "{error.message}".')
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)
fetch_incentives.py

Руби

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

локон

Примечание: Хотя здесь не приводится прямой пример REST-кода для этого шага, вы можете сделать это с помощью ручного REST-запроса.

Обратитесь к документации по REST-интерфейсу Google Ads API и справочным страницам по конкретным методам. Вам потребуется сформировать полезную нагрузку JSON на основе определений протоколов.

Основные ресурсы:

Использование REST
Структура REST-интерфейса
Сопоставление полей JSON
Для получения информации о конкретном сервисе и методе обратитесь к справочнику REST API .

Примените стимулы

После того, как клиент выберет бонус, вы можете использовать метод IncentiveService.ApplyIncentive , чтобы применить его к конкретному аккаунту клиента в Google Ads.

Метод ApplyIncentiveRequest требует наличия следующих полей (в v25 и выше все три поля помечены как REQUIRED в определении protobuf и поддерживаются как метод с тремя аргументами; в v24 и более ранних версиях selected_incentive_id и customer_id помечены как необязательные в схеме):

selected_incentive_id : Идентификатор выбранного клиентом бонуса.
customer_id : Идентификатор клиента, к учетной записи которого применяется бонус.
country_code : Двухбуквенный код страны клиента в формате ISO 3166-1 alpha-2, который должен совпадать со страной выставления счетов в аккаунте Google Ads.

Функция ApplyIncentiveResponse возвращает coupon_code примененного бонуса и время creation_time (в формате "yyyy-MM-dd HH:mm:ss" в UTC).

Следующий пример демонстрирует, как применять систему поощрений:

Java

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.ads.googleads.examples.incentives;

import com.beust.jcommander.Parameter;
import com.google.ads.googleads.examples.utils.ArgumentNames;
import com.google.ads.googleads.examples.utils.CodeSampleParams;
import com.google.ads.googleads.lib.GoogleAdsClient;
import com.google.ads.googleads.v25.errors.GoogleAdsError;
import com.google.ads.googleads.v25.errors.GoogleAdsException;
import com.google.ads.googleads.v25.services.ApplyIncentiveRequest;
import com.google.ads.googleads.v25.services.ApplyIncentiveResponse;
import com.google.ads.googleads.v25.services.IncentiveServiceClient;
import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * This example applies an incentive to a user's account.
 *
 * <p>This example is a no-op if the user already has an accepted incentive. If the user attempts to
 * apply a new incentive, the response will simply return the existing incentive that has already
 * been applied to the account.
 */
public class ApplyIncentive {

  private static class ApplyIncentiveParams extends CodeSampleParams {

    @Parameter(
        names = ArgumentNames.CUSTOMER_ID,
        required = true,
        description = "The Google Ads customer ID.")
    private Long customerId;

    @Parameter(
        names = ArgumentNames.INCENTIVE_ID,
        required = true,
        description = "The ID of the incentive to apply.")
    private Long incentiveId;

    @Parameter(
        names = ArgumentNames.COUNTRY_CODE,
        required = true,
        description = "The country for the incentive to apply.")
    private String countryCode = "US";
  }

  public static void main(String[] args) throws IOException {
    ApplyIncentiveParams params = new ApplyIncentiveParams();
    if (!params.parseArguments(args)) {
      // Either pass the required parameters for this example on the command line, or insert them
      // into the code here. See the parameter class definition above for more information.
      params.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
      params.incentiveId = Long.parseLong("INSERT_INCENTIVE_ID_HERE");
    }

    GoogleAdsClient googleAdsClient = null;
    try {
      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
    } catch (FileNotFoundException fnfe) {
      System.err.printf("Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
          fnfe);
      System.exit(1);
    } catch (IOException ioe) {
      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
      System.exit(1);
    }

    try {
      new ApplyIncentive().runExample(googleAdsClient, params.customerId, params.incentiveId,
          params.countryCode);
    } catch (GoogleAdsException gae) {
      // GoogleAdsException is the base class for most exceptions thrown by an API request.
      // Instances of this exception have a message and a GoogleAdsFailure that contains a
      // collection of GoogleAdsError instances that detail the underlying causes of the
      // exception.
      System.err.printf("Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
          gae.getRequestId());
      int i = 0;
      for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
        System.err.printf("  Error %d: %s%n", i++, googleAdsError);
      }
      System.exit(1);
    }
  }

  /**
   * Runs the example.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param customerId the client customer ID.
   * @param incentiveId the ID of the incentive to apply.
   * @param countryCode the country of the incentive.
   */
  private void runExample(GoogleAdsClient googleAdsClient, long customerId, long incentiveId,
      String countryCode) {
    try (IncentiveServiceClient incentiveServiceClient = googleAdsClient.getLatestVersion()
        .createIncentiveServiceClient()) {
      ApplyIncentiveRequest request = ApplyIncentiveRequest.newBuilder()
          .setCustomerId(String.valueOf(customerId))
          .setSelectedIncentiveId(incentiveId)
          .setCountryCode(countryCode).build();
      // Issues the request.
      ApplyIncentiveResponse response = incentiveServiceClient.applyIncentive(request);

      // Processes the response.
      System.out.println("====================================================================");
      System.out.printf("Applied incentive with coupon code '%s'.%n", response.getCouponCode());
      System.out.printf("Incentive was created at '%s'.%n", response.getCreationTime());
      System.out.println("====================================================================");
    }
  }
}
ApplyIncentive.java

C#

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.Gax.Lib;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V25.Errors;
using Google.Ads.GoogleAds.V25.Services;
using System;

namespace Google.Ads.GoogleAds.Examples.V25
{
    /// <summary>
    /// This code example applies an incentive to a user's account.
    /// </summary>
    public class ApplyIncentive : ExampleBase
    {
         /// <summary>
        /// Command line options for running the <see cref="FetchIncentives"/> example.
        /// </summary>
        public class Options : OptionsBase
        {
            /// <summary>
            /// The customer ID for which the call is made.
            /// </summary>
            [Option("customerId", Required = true, HelpText =
                "The customer ID for which the call is made.")]
            public long CustomerId { get; set; }

            /// <summary>
            /// The ID of the incentive to apply.
            /// </summary>
            [Option("incentiveId", Required = true, HelpText =
                "The ID of the incentive to apply.")]
            public long IncentiveId { get; set; }

            /// <summary>
            /// The country for the incentive to apply.
            /// </summary>
            [Option("countryCode", Required = true, HelpText =
                "The country for the incentive to apply.")]
            public string CountryCode { get; set; }
        }

        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            Options options = ExampleUtilities.ParseCommandLine<Options>(args);

            ApplyIncentive codeExample = new ApplyIncentive();
            Console.WriteLine(codeExample.Description);              
            codeExample.Run(new GoogleAdsClient(), options.CustomerId,
            options.IncentiveId, options.CountryCode);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description =>
            "This code example applies an incentive to a user's account.";

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="customerId">The client customer ID.</param>
        /// <param name="incentiveId">The ID of the incentive to apply.</param>
        /// <param name="countryCode">The country for the returned incentive.</param>
        public void Run(GoogleAdsClient client, long customerId,
            long incentiveId, string countryCode)
        {
            IncentiveServiceClient incentiveService = client.GetService(
                Services.V25.IncentiveService);

            ApplyIncentiveRequest request = new ApplyIncentiveRequest()
            {
                CustomerId = customerId.ToString(),
                SelectedIncentiveId = incentiveId,
                CountryCode = countryCode
            };

            try
            {
                ApplyIncentiveResponse response =
                    incentiveService.ApplyIncentive(request);

                Console.WriteLine("===========================================");
                Console.WriteLine($"Applied incentive with coupon code: {response.CouponCode}");
                Console.WriteLine($"Incentive was created at: {response.CreationTime}");
                Console.WriteLine("===========================================");

            } catch  (GoogleAdsException e)
            {
                Console.WriteLine("Failure:");
                Console.WriteLine($"Message: {e.Message}");
                Console.WriteLine($"Failure: {e.Failure}");
                Console.WriteLine($"Request ID: {e.RequestId}");
                throw;
            }
        }
    }
}ApplyIncentive.cs

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

#!/usr/bin/env python
# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""This example applies an incentive to a user's account.

This example is a no-op if the user already has an accepted incentive. If the
user attempts to apply a new incentive, the response will simply return the
existing incentive that has already been applied to the account. Use the
fetch_incentives.py example to get the available incentives.
"""

import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
from google.ads.googleads.v24.services import (
    ApplyIncentiveRequest,
    ApplyIncentiveResponse,
)
from google.ads.googleads.v24.services.services.incentive_service.client import (
    IncentiveServiceClient,
)


def main(
    client: GoogleAdsClient,
    customer_id: str,
    incentive_id: str,
    country_code: str,
) -> None:
    """Applies an incentive for the ads customer.

    Args:
        client: An initialized GoogleAdsClient instance.
        customer_id: The client customer ID.
        country_code: The country code of the user.
        incentive_id: The incentive ID to select.
    """
    incentive_service: IncentiveServiceClient = client.get_service(
        "IncentiveService"
    )
    apply_incentive_request: ApplyIncentiveRequest = client.get_type(
        "ApplyIncentiveRequest"
    )

    apply_incentive_request.customer_id = customer_id
    apply_incentive_request.selected_incentive_id = incentive_id

    if country_code:
        apply_incentive_request.country_code = country_code

    response: ApplyIncentiveResponse = incentive_service.apply_incentive(
        request=apply_incentive_request
    )

    print("Applied incentive.")
    print(f"Coupon Code: {response.coupon_code}")
    print(f"Creation Time: {response.creation_time}")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Applies an incentive for the ads customer."
    )
    # The following argument(s) should be provided to run the example.
    parser.add_argument(
        "-c",
        "--customer_id",
        type=str,
        required=True,
        help="The Google Ads customer ID.",
    )
    parser.add_argument(
        "-i",
        "--incentive_id",
        type=int,
        required=True,
        help="The incentive ID to select.",
    )
    parser.add_argument(
        "-k",
        "--country_code",
        type=str,
        required=True,
        help="The country code of the user (e.g. 'US').",
    )
    args = parser.parse_args()

    # GoogleAdsClient will read the google-ads.yaml configuration file in the
    # home directory if none is specified.
    googleads_client = GoogleAdsClient.load_from_storage(version="v24")

    try:
        main(
            googleads_client,
            args.customer_id,
            args.incentive_id,
            args.country_code,
        )
    except GoogleAdsException as ex:
        print(
            f'Request with ID "{ex.request_id}" failed with status '
            f'"{ex.error.code().name}" and includes the following errors:'
        )
        for error in ex.failure.errors:
            print(f'\tError with message "{error.message}".')
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)
apply_incentive.py

Руби

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

локон

Использование REST
Структура REST-интерфейса
Сопоставление полей JSON
Для получения информации о конкретном сервисе и методе обратитесь к справочнику REST API .

Получить примененные льготы

Вы можете запросить доступный только для чтения ресурс AppliedIncentive ( applied_incentive ) через GoogleAdsService.Search и GoogleAdsService.SearchStream , чтобы получить подробную информацию о примененных стимулах.

В AppliedIncentive доступны следующие ключевые поля:

resource_name : Название ресурса в формате customers/{customer_id}/appliedIncentives/{coupon_code} .
coupon_code : Код купона на получение бонуса.
incentive_state : Текущее IncentiveState поощрения (например, REDEEMED , FULFILLED , REWARD_GRANTED , EXPIRED , REWARD_EXHAUSTED или INVALIDATED ).
redemption_date_time , fulfillment_expiration_date_time , reward_grant_date_time и reward_expiration_date_time : метки времени в формате "yyyy-MM-dd HH:mm:ss" в UTC.
currency_code , reward_amount_micros , granted_amount_micros , required_min_spend_micros , current_spend_towards_fulfillment_micros и reward_balance_remaining_micros : Валюта и денежные суммы в микросах.

Следующий запрос Google Ads Query Language (GAQL) извлекает все поля из AppliedIncentive :

SELECT
  applied_incentive.resource_name,
  applied_incentive.coupon_code,
  applied_incentive.incentive_state,
  applied_incentive.redemption_date_time,
  applied_incentive.fulfillment_expiration_date_time,
  applied_incentive.reward_grant_date_time,
  applied_incentive.reward_expiration_date_time,
  applied_incentive.currency_code,
  applied_incentive.reward_amount_micros,
  applied_incentive.granted_amount_micros,
  applied_incentive.required_min_spend_micros,
  applied_incentive.current_spend_towards_fulfillment_micros,
  applied_incentive.reward_balance_remaining_micros
FROM
  applied_incentive

Счет

Стимулы Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Получите бонусы

Java

C#

PHP

Python

Руби

Perl

локон

Примените стимулы

Java

C#

PHP

Python

Руби

Perl

локон

Получить примененные льготы

Стимулы