نمای کلی میانای برنامه‌سازی کاربردی فرعی «تبلیغات»

از تبلیغات برای نمایش پیشنهادهای ویژه برای محصولاتی که در Google می‌فروشید استفاده کنید. تبلیغات در دارایی‌های مختلف Google، ازجمله «جستجوی Google»، Shopping، و Chrome نمایش داده می‌شود. تبلیغات ویژه برای تأیید شدن باید معیارهای خاصی را برآورده کنند. برای اطلاعات بیشتر، معیارهای تبلیغ را ببینید.

وقتی تبلیغی به محصولاتتان اضافه می‌کنید، خریداران پیوند پیشنهاد ویژه‌ای را می‌بینند. برای مثال، «‎٪۱۵ تخفیف» یا «ارسال رایگان». پیوندهای پیشنهاد می‌توانند جذابیت محصولاتتان را افزایش دهند و خریداران را به خرید تشویق کنند. همه تبلیغ‌های ویژه در تسویه‌حساب یا پایانه فروش اعمال می‌شوند.

برای اطلاعات بیشتر، اصول اولیه تبلیغ را ببینید.

پیش‌نیازها

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

علاوه‌براین، باید حساب Merchant Center خود را در برنامه «تبلیغات» ثبت‌نام کنید. اگر مطمئن نیستید که قبلاً ثبت‌نام کرده‌اید یا نه، Merchant Center را بررسی کنید.

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

برای اطلاعات بیشتر، معیارها و خط‌مشی‌های مشارکت را ببینید.

ایجاد منبع داده

می‌توانید از روش accounts.dataSources.create برای ایجاد منبع داده عرضه ترویجی استفاده کنید. اگر منبع داده عرضه ترویجی موجودی دردسترس است، از روش accounts.dataSources.list برای بازیابی همه منابع داده استفاده کنید. سپس می‌توانید از فیلد name منبع داده عرضه ترویجی برای ایجاد عرضه ترویجی استفاده کنید.

برای ارجاع مستقیم به آن‌ها در فراخوانی‌های میانای برنامه‌سازی کاربردی در آینده، اکیداً توصیه می‌کنیم accounts.dataSources.name را در پایگاه داده محلی‌تان برای هر تبلیغ ذخیره کنید. می‌توانید یک‌بار پایگاه داده محلی‌تان را پر کنید.

درخواست زیر نحوه ایجاد منبع داده برای افزودن تبلیغات را نشان می‌دهد:

POST https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

موارد زیر را جایگزین کنید:

  • {ACCOUNT_ID}: شناسه یکتای حساب شما همان‌طور که در میانای کاربر Merchant Center نشان داده می‌شود.
  • {DISPLAY_NAME}: نام نمایشی منبع داده.
  • {CONTENT_LANGUAGE}: کد زبان دوحرفی ISO 639-1 محصولات در منبع داده.
  • ‫{TARGET_COUNTRY}: کد قلمرو CLDR کشور هدف که می‌خواهید تبلیغات ویژه در آنجا قابل‌مشاهده باشد.

پس‌از اجرای موفقیت‌آمیز درخواست، پاسخ زیر را می‌بینید که حاوی جزئیات مربوط به منبع داده عرضه‌های ترویجی جدیداً ایجادشده است:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

ایجاد تبلیغ ویژه

می‌توانید از روش accounts.promotions.insert برای ایجاد یا به‌روزرسانی عرضه ترویجی استفاده کنید. روش accounts.promotions.insert یک منبع promotions و نام منبع داده را به‌عنوان ورودی می‌گیرد. درصورت موفقیت‌آمیز بودن، تبلیغ جدید یا به‌روزشده را برمی‌گرداند.

برای ایجاد عرضه ترویجی، نام منبع داده لازم است. همچنین باید مقادیر فیلدهای زیر را در درخواستتان ارائه دهید:

  • contentLanguage
  • redemptionChannel
  • promotionId
  • targetCountry
  • attributes.offerType
  • attributes.genericRedemptionCode
  • attributes.couponValueType
  • attributes.productApplicability
  • attributes.promotionEffectiveTimePeriod.endTime
  • attributes.promotionEffectiveTimePeriod.startTime
  • attributes.longTitle

Google پیش‌از توزیع تبلیغ‌هایتان، آن‌ها را بازبینی و تأیید می‌کند. برای اطلاعات بیشتر، فرایند تأیید تبلیغ را ببینید.

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

درخواست زیر نحوه ایجاد تبلیغ آنلاین را نشان می‌دهد:

HTTP

POST https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert

{
"promotion": {
  "name": "{PROMOTION_NAME}",
  "promotionId": "{PROMOTION_ID}",
  "targetCountry": "{TARGET_COUNTRY}",
  "redemptionChannel": [
    "ONLINE"
  ],
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "attributes": {
    "promotionDisplayTimePeriod": {
      "endTime": "{PROMOTION_END_TIME}",
      "startTime": "{PROMOTION_START_TIME}"
    },
    "offerType": "{OFFER_TYPE}",
    "longTitle": "{LONG_TITLE}"
  }
},
"dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

cURL

  curl --request POST \
'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert?key=[YOUR_API_KEY]' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"dataSource":"{DATASOURCE_ID}","promotion":{"name":"accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}y","promotionId":"abc","contentLanguage":"en","targetCountry":"US","redemptionChannel":["ONLINE"]}}' \
--compressed

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

مقادیر معتبر برای فیلد اجباری offerType عبارتند از NO_CODE و GENERIC_CODE. اگر یکی از این مقادیر را ارائه نکنید، درخواست API با پاسخ HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type ناموفق خواهد بود. اگر هیچ‌کدام از فیلدهای اجباری را ارائه نکنید، پیام خطای مشابهی برگردانده می‌شود.

اگر مقداری برای فیلد attributes.genericRedemptionCode ارائه نکنید، درخواست با پاسخ HTTP 400 [genericRedemptionCode] No redemption code provided ناموفق می‌شود.

مقادیر فیلدهای promotion.attributes.promotionDisplayTimePeriod.startTime و promotion.attributes.promotionDisplayTimePeriod.endTime باید در قالب yyyy-mm-ddThh:mm:ssZ باشد. حتماً مقادیر این فیلدها را با تاریخ‌هایی در آینده جایگزین کنید.

برای اطلاعات بیشتر، به مشخصات داده‌های تبلیغات مراجعه کنید.

برای روال‌های مطلوب درباره ایجاد عرضه ترویجی، به روال‌های مطلوب عرضه‌های ترویجی مراجعه کنید.

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

پس‌از اجرای موفقیت‌آمیز درخواست ایجاد تبلیغ، ممکن است چند دقیقه طول بکشد تا تبلیغ بااستفاده از API قابل‌بازیابی باشد یا در Merchant Center ظاهر شود.

در اینجا نمونه‌ای آورده شده است که می‌توانید از آن برای درج چندین تبلیغ به‌صورت ناهمگام استفاده کنید:

جاوا

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.api.gax.grpc.ChannelPoolSettings;
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.promotions.v1.Attributes;
import com.google.shopping.merchant.promotions.v1.CouponValueType;
import com.google.shopping.merchant.promotions.v1.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1.OfferType;
import com.google.shopping.merchant.promotions.v1.ProductApplicability;
import com.google.shopping.merchant.promotions.v1.Promotion;
import com.google.shopping.merchant.promotions.v1.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1.RedemptionChannel;
import com.google.shopping.type.CustomAttribute;
import com.google.shopping.type.Destination.DestinationEnum;
import com.google.type.Interval;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert multiple promotions asynchronously. */
public class InsertPromotionsAsyncSample {

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static Promotion createPromotion(String accountId) {
    String merchantPromotionId = generateRandomString();

    Attributes attributes =
        Attributes.newBuilder()
            .setProductApplicability(ProductApplicability.ALL_PRODUCTS)
            .setOfferType(OfferType.GENERIC_CODE)
            .setGenericRedemptionCode("ABCD1234")
            .setLongTitle("My promotion")
            .setCouponValueType(CouponValueType.PERCENT_OFF)
            .addPromotionDestinations(DestinationEnum.SHOPPING_ADS)
            .setPercentOff(10)
            // Note that promotions have a 6-month limit.
            // For more information, read here: https://support.google.com/merchants/answer/2906014
            // Also note that only promotions valid within the past 365 days are shown in the UI.
            .setPromotionEffectiveTimePeriod(
                Interval.newBuilder()
                    .setStartTime(Timestamp.newBuilder().setSeconds(1726842472))
                    .setEndTime(Timestamp.newBuilder().setSeconds(1726842473))
                    .build())
            .build();

    return Promotion.newBuilder()
        .setName(String.format("accounts/%s/merchantPromotions/%s", accountId, merchantPromotionId))
        .setPromotionId(merchantPromotionId)
        .setContentLanguage("fr")
        .setTargetCountry("CH")
        .addRedemptionChannel(RedemptionChannel.ONLINE)
        .setAttributes(attributes)
        // Custom attributes allow you to add additional information which is not available in
        // Attributes. For example, you might want to pilot experimental functionality.
        .addCustomAttributes(
            CustomAttribute.newBuilder()
                .setName("another example name")
                .setValue("another example value")
                .build())
        .build();
  }

  public static void asyncInsertPromotions(String accountId, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates a channel provider. This provider manages a pool of gRPC channels
    // to enhance throughput for bulk operations. Each individual channel in the pool
    // can handle up to approximately 100 concurrent requests.
    //
    // Channel: A single connection pathway to the service.
    // Pool: A collection of multiple channels managed by this provider.
    //   Requests are distributed across the channels in the pool.
    //
    // We recommend estimating the number of concurrent requests you'll make, divide by 50 (50%
    // utilization of channel capacity), and set the pool size to that number.
    InstantiatingGrpcChannelProvider channelProvider =
        InstantiatingGrpcChannelProvider.newBuilder()
            .setChannelPoolSettings(ChannelPoolSettings.staticallySized(30))
            .build();

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .setTransportChannelProvider(channelProvider)
            .build();

    try (PromotionsServiceClient merchantPromotionsServiceClient =
        PromotionsServiceClient.create(merchantPromotionsServiceSettings)) {

      // Arbitrarily creates five merchant promotions with random IDs.
      List<InsertPromotionRequest> requests = new ArrayList<>();
      for (int i = 0; i < 5; i++) {
        InsertPromotionRequest request =
            InsertPromotionRequest.newBuilder()
                .setParent(String.format("accounts/%s", accountId))
                .setPromotion(createPromotion(accountId))
                .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                .build();
        requests.add(request);
      }

      // Inserts the merchant promotions.
      List<ApiFuture<Promotion>> futures =
          requests.stream()
              .map(
                  request ->
                      merchantPromotionsServiceClient.insertPromotionCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<Promotion>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<Promotion>>() {
            @Override
            public void onSuccess(List<Promotion> results) {
              System.out.println("Inserted merchant promotions below:");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());
    } catch (Exception e) {
      System.out.println(e);
    }
  }


  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    asyncInsertPromotions(config.getAccountId().toString(), "<YOUR_DATA_SOURCE_ID>");
  }
}

در زیر چند نمونه تبلیغ ویژه آورده شده است که می‌توانید برای شروع کار از آن‌ها استفاده کنید.

عرضه ترویجی محلی قابل‌اعمال برای همه محصولات و همه فروشگاه‌ها

نمونه درخواست زیر نشان می‌دهد که چگونه یک تبلیغ محلی ایجاد کنید که برای همه محصولات در حساب Merchant Center شما و همه فروشگاه‌های اضافه‌شده در حساب نمایه کسب‌وکار پیوندشده شما قابل اعمال باشد.

POST https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

فیلد productApplicability الزامی است. این ویژگی نشان می‌دهد که تبلیغ برای همه محصولات قابل‌اعمال است یا فقط برای محصولات خاصی. مقادیر پشتیبانی‌شده ALL_PRODUCTS و SPECIFIC_PRODUCTS است. برای اطلاعات بیشتر، انتخاب محصولات برای تبلیغ را ببینید.

فیلد couponValueType الزامی است. این ویژگی نوع تبلیغی را که اجرا می‌کنید نشان می‌دهد. برای مشاهده فهرست مقادیر پشتیبانی‌شده، نوع مقدار کوپن را ببینید. بسته به نوع ارزش کوپنی که انتخاب کرده‌اید، برخی‌از مشخصه‌ها الزامی است.

فیلد minimumPurchaseQuantity به شما امکان می‌دهد مقدار حداقل تعداد خرید لازم برای پس‌خرید کردن عرضه ترویجی را تنظیم کنید. برای اطلاعات بیشتر، حداقل مقدار خرید برای تبلیغ را ببینید.

به‌طور مشابه، می‌توانید از فیلد minimumPurchaseAmount برای تنظیم حداقل مبلغ خرید لازم برای پس‌خرید کردن تبلیغ استفاده کنید. برای اطلاعات بیشتر، حداقل مبلغ خرید را ببینید.

برای اطلاعات بیشتر درباره مقادیری که باید برای ایجاد عرضه ترویجی محلی ارائه دهید، مشخصات منبع داده برای عرضه‌های ترویجی محلی را ببینید.

تبلیغ آنلاین که با کد پس‌خرید برای محصولات انتخابی اعمال می‌شود

نمونه درخواست زیر نشان می‌دهد که چگونه یک تبلیغ آنلاین ایجاد کنید که با کد پس‌خرید برای محصولات انتخابی اعمال می‌شود.

POST https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

مشاهده تبلیغات

برای مشاهده عرضه ترویجی، از accounts.promotions.get استفاده کنید. این درخواست GET فقط خواندنی است. به merchantId شما و شناسه تبلیغ نیاز دارد. روش GET منبع تبلیغات مربوطه را برمی‌گرداند.

برای مثال:

HTTP

GET https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

cURL

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer {ACCESS_TOKEN}' \
   --header 'Accept: application/json' \
   --compressed

موارد زیر را جایگزین کنید:

  • ‫{ACCOUNT_ID}: شناسه یکتای حساب Merchant Center شما.
  • {PROMOTION_ID}: شناسه یکتای تبلیغی که می‌خواهید بازیابی کنید. قالب {CHANNEL} ~{CONTENT_LANGUAGE}~ {TARGET_COUNTRY}~{PROMOTION_ID} است.

توجه داشته باشید که چند دقیقه طول می‌کشد تا ترویج جدید ایجادشده بااستفاده از API قابل‌بازیابی باشد.

مشاهده عرضه ترویجی محلی

درخواست نمونه زیر عرضه ترویجی محلی‌ای را بازیابی می‌کند که شناسه عرضه ترویجی آن in_store~en~US~buy_2_get_10_off است.

GET https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

پس‌از موفقیت‌آمیز بودن درخواست، پاسخ زیر را می‌بینید:

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

فیلد moneyOffAmount در این نمونه تخفیفی را که در تبلیغ ارائه می‌شود ارائه می‌دهد. برای اطلاعات بیشتر، مبلغ تخفیف پولی تبلیغ را ببینید.

فیلد promotionUrl در این نمونه پیوند وب‌سایت فروشگاه را ارائه می‌دهد که خریداران می‌توانند اطلاعات بیشتری درباره تبلیغ در آن پیدا کنند. اگر فیلد promotionUrl را اضافه نکنید، تبلیغات آگهی‌های فهرست موجودی محلی با خطا مواجه می‌شود.

مشاهده تبلیغ آنلاین

درخواست نمونه زیر تبلیغ آنلاینی را بازیابی می‌کند که شناسه تبلیغ آن online~en~US~25_pct_off است.

GET https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

فیلد itemIdInclusion استفاده‌شده در این نمونه به محصولاتی اشاره می‌کند که واجدشرایط عرضه ترویجی هستند. برای اطلاعات بیشتر، شناسه محصول برای تبلیغ را ببینید.

فهرست کردن تبلیغات

می‌توانید از روش promotions.list برای مشاهده همه تبلیغات ایجادشده استفاده کنید.

در اینجا یک درخواست نمونه آورده شده است:

HTTP

GET https://merchantapi.googleapis.com/promotions/v1/{ACCOUNT_ID}/promotions

cURL

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer {ACCESS_TOKEN}' \
   --header 'Accept: application/json' \
   --compressed

پاسخ حاوی فهرست همه تبلیغات در حسابتان است. برای هر تبلیغ، می‌توانید جزئیاتی مثل promotionId، redemptionChannel، dataSource، promotionStatus، و غیره را ببینید.

مشاهده وضعیت تبلیغ ویژه

برای دیدن وضعیت تبلیغ، مشخصه promotionStatus را که با روش promotions.get یا promotions.list برگردانده شده است ببینید.

فیلد promotionStatus می‌تواند مقادیر زیر را داشته باشد:

  • IN_REVIEW: عرضه ترویجی هنوز درحال بازبینی است.
  • ‫REJECTED: تبلیغ رد شده است.
  • ‫LIVE: تبلیغ تأیید شده و فعال است.
  • STOPPED: عرضه ترویجی توسط حساب متوقف شده است.
  • EXPIRED: این تبلیغ ویژه دیگر فعال نیست.
  • PENDING: عرضه ترویجی متوقف نشده است و همه بازبینی‌ها تأیید شده‌اند، اما تاریخ فعال در آینده است.
  • STATE_UNSPECIFIED: وضعیت تبلیغ نامشخص است.

برای درک فرایند تأیید برای تبلیغی که ایجاد کرده‌اید، فرایند تأیید تبلیغ را ببینید.

وضعیت تبلیغ نمونه

نمونه‌های زیر تفاوت بین درخواست‌های موفق و ناموفق را نشان می‌دهد.

نگاشت محصول وجود ندارد

بدنه پاسخ زیر عرضه ترویجی آنلاینی را نشان می‌دهد که به‌دلیل نبود نگاشت محصول رد شده است.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

برای عیب‌یابی تبلیغ‌های تأییدنشده و آشنایی با نحوه جلوگیری از تأیید نشدن در آینده، برطرف کردن مشکلات مربوط به تبلیغ‌های تأییدنشده را ببینید.

اگر تبلیغی که ایجاد کرده‌اید تأیید نشود، ایمیلی دریافت می‌کنید که دلیل رد شدن و دستورالعمل‌های رفع مشکل را ذکر می‌کند.

عرضه ترویجی تحت ارزیابی

متن پاسخ زیر تبلیغ ویژه‌ای را نشان می‌دهد که هنوز درحال ارزیابی است.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

تبلیغ تأییدشده و فعال

بدنه پاسخ زیر تبلیغی را نشان می‌دهد که برای خریداران قابل‌مشاهده است.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

برای اطلاعات بیشتر، پرسشگان وضعیت تبلیغ را ببینید.

حذف کردن تبلیغات ویژه

حذف تبلیغ بااستفاده از API امکان‌پذیر نیست. برای حذف کردن تبلیغ، باید به میانای کاربری Merchant Center دسترسی داشته باشید. برای اطلاعات بیشتر، ویرایش ترویج یا تغییر وضعیت ترویج را ببینید.

برای پایان دادن به یک تبلیغ موجود، می‌توانید از روش accounts.promotions.insert برای به‌روزرسانی فیلد attributes.promotionEffectiveTimePeriod.endTime به زمانی در گذشته استفاده کنید.

بیشتر بدانید