مروری بر Merchant Promotions API

از تبلیغات برای نمایش پیشنهادات ویژه برای محصولاتی که در Google می فروشید استفاده کنید. تبلیغات در دارایی های مختلف Google، از جمله جستجوی Google، خرید، و Chrome نمایش داده می شود.

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

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

پیش نیازها

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

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

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

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

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

از datasource.create API برای ایجاد فید تبلیغاتی استفاده کنید. اگر فید تبلیغاتی موجود در دسترس است، از datasource.get برای واکشی datasource.name استفاده کنید

فرم درخواست به شرح زیر است:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{account}/dataSources/{datasource}

مثال

مثال یک درخواست و پاسخ معمولی را نشان می دهد.

درخواست:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/123/dataSources {"displayName": "test api feed", "promotionDataSource":{"targetCountry":"US", "contentLanguage":"en"}}

پاسخ:

{
  "name": "accounts/123/dataSources/1000000573361824",
  "dataSourceId": "1000000573361824",
  "displayName": "test api feed",
  "promotionDataSource": {
    "targetCountry": "US",
    "contentLanguage": "en"
  },
  "input": "API"
}

تبلیغات ایجاد کنید

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

ایجاد یک تبلیغ به datasource.name نیاز دارد.

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

فرم درخواست:

POST https://merchantapi.googleapis.com/promotions/v1beta/{parent=accounts/*/}promotions:insert

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

نمونه 1: یک تبلیغ محلی قابل اجرا برای همه محصولات و همه فروشگاه ها

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/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"
      },
      "minimum_purchase_quantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/123/dataSources/1000000573361824"
}

نمونه 2: یک تبلیغ آنلاین که برای محصولات انتخاب شده با کد بازخرید اعمال می شود

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/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/123/dataSources/1000000573361824"
}

یادداشت های ویژه

پس از ایجاد تبلیغات، ممکن است چند دقیقه طول بکشد تا تبلیغات ایجاد شود.

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

قبل از ایجاد و مدیریت تبلیغات، به بهترین روش‌های تبلیغات مراجعه کنید.

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

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

به عنوان مثال:

GET https://merchantapi.googleapis.com/promotions/v1beta/{name=accounts/*/promotions/*}

این نمونه ها را مطالعه کنید.

نمونه 1: یک تبلیغ محلی

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/promotions/in_store~en~US~buy_2_get_10_off

{
 "name": "accounts/123/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"
   },
   "minimum_purchase_quantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/123/dataSources/1000000573361824"
}

نمونه 2. یک تبلیغ آنلاین

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/promotions/online~en~US~25_pct_off
{
 "name": "accounts/123/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}/dataSources/{dataSource}"
}

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

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

GET https://merchantapi.googleapis.com/promotions/v1beta/{parent=accounts/*}/promotions

وضعیت ارتقاء

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

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

نمونه وضعیت ارتقاء

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

نمونه 1. بدنه پاسخ زیر یک تبلیغ آنلاین را نشان می دهد که به دلیل نگاشت محصول از دست رفته رد می شود. 

  "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"
        ]
      }
    ]
  }

نمونه 2. بدنه پاسخگوی زیر یک تبلیغ تایید شده را نشان می دهد. 

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

نمونه 3. یک تبلیغ تایید شده و زنده 

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

بیشتر بدانید

برای جزئیات بیشتر، به مرکز راهنمایی تبلیغات مراجعه کنید.

برای اطلاع از مهاجرت از Content API برای خرید، به مدیریت تبلیغات مهاجرت مراجعه کنید.