مروری بر API فرعی تبلیغات، مروری بر API فرعی تبلیغات

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

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

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

پیش‌نیازها

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

علاوه بر این، شما باید حساب مرکز فروشندگان خود را در برنامه تبلیغات ثبت کنید. اگر مطمئن نیستید که قبلاً ثبت نام کرده‌اید، مرکز فروشندگان را بررسی کنید.

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

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

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

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

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

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

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

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

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

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

{
  "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

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

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

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

اچ‌تی‌پی 

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 --request POST \
'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert?key=[YOUR_API_KEY]' \
--header 'Authorization: Bearer [YOUR_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 قابل بازیابی باشد یا در مرکز فروشندگان ظاهر شود.

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

جاوا 

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

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .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>");
  }
}
InsertPromotionsAsyncSample.java

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

یک پروموشن محلی که برای همه محصولات و همه فروشگاه‌ها قابل اجرا است

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

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 الزامی است. این فیلد نوع تبلیغاتی را که اجرا می‌کنید نشان می‌دهد. برای مشاهده لیست مقادیر پشتیبانی، به بخش Coupon value type مراجعه کنید. بسته به نوع مقدار کوپنی که انتخاب کرده‌اید، برخی ویژگی‌ها الزامی هستند .

فیلد 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 منبع مربوط به تبلیغات را برمی‌گرداند.

برای مثال:

اچ‌تی‌پی 

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

حلقه 

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

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

  • {ACCOUNT_ID} : شناسه منحصر به فرد حساب مرکز فروشندگان شما.
  • {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 برای مشاهده‌ی تمام پروموشن‌های ایجاد شده استفاده کنید.

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

اچ‌تی‌پی 

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

حلقه 

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer [YOUR_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 امکان‌پذیر نیست. برای حذف یک تبلیغ، باید به رابط کاربری مرکز فروشندگان دسترسی داشته باشید. برای اطلاعات بیشتر، به ویرایش یک تبلیغ یا تغییر وضعیت تبلیغ مراجعه کنید.

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

بیشتر بدانید