این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

مروری بر Merchant Promotions API

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

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

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

پیش نیازها

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

یک فید محصول فعال در Google Merchant Center .
یک فید تبلیغاتی فعال در Google Merchant Center .
یک حساب Google Ads برای کمپین های خرید .

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

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

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

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

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

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

POST https://merchantapi.googleapis.com/datasources/v1beta/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 تبلیغات شما را قبل از توزیع بررسی و تأیید می کند. برای اطلاعات بیشتر، به فرآیند تأیید تبلیغات مراجعه کنید.

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

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

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

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

مقادیر معتبر برای فیلد 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 ظاهر شود.

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

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

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

POST https://merchantapi.googleapis.com/promotions/v1beta/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/v1beta/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/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

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

{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/v1beta/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/v1beta/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/v1beta/{ACCOUNT_ID}/promotions

پاسخ شامل لیستی از تمام تبلیغات در حساب شما است. برای هر تبلیغ، می‌توانید جزئیاتی مانند 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 تبلیغات تجاری مراجعه کنید.
برای اطلاع از مهاجرت از Content API برای خرید، به مدیریت تبلیغات مهاجرت مراجعه کنید.