نظرة عامة على واجهة برمجة التطبيقات للرسائل الترويجية للتاجر

استخدِم العروض الترويجية لعرض عروض خاصة للمنتجات التي تبيعها على Google. تظهر العروض الترويجية على خدمات Google المختلفة، بما في ذلك "بحث Google" و التسوّق وChrome.

عند إضافة عروض ترويجية إلى منتجاتك، سيرى المتسوّقون رابط عرض خاص، مثلاً "خصم% 15" أو "شحن مجاني". يمكن أن تساهم روابط العروض في زيادة جاذبية منتجاتك وتشجيع المتسوّقين على إجراء عملية شراء.

لمزيد من المعلومات، اطّلِع على أساسيات المحتوى الترويجي.

المتطلبات الأساسية

يجب أن تقدّم إلى Google معلومات محدّدة عن نشاطك التجاري ومنتجاتك قبل عرض عروضك الترويجية. يجب توفّر ما يلي:

• خلاصة منتجات نشطة في Google Merchant Center
• خلاصة عروض ترويجية نشطة في Google Merchant Center
• حساب على إعلانات Google لحملات Shopping

بالإضافة إلى ذلك، يجب تسجيل حساب التاجر في برنامج "العروض الترويجية". إذا لم تكن متأكدًا مما إذا سبق لك الاشتراك، يُرجى التحقّق من ذلك في Merchant Center.

إذا لم تكن مسجّلاً، أكمِل نموذج طلب. وسيُعلمك فريق الرسائل الترويجية عندما يصبح بإمكانك استخدامها.

لمزيد من المعلومات، يُرجى الاطّلاع على معايير ومتطلبات المشاركة في البرنامج.

إنشاء مصدر بيانات

استخدِم واجهة برمجة التطبيقات datasource.create لإنشاء خلاصة عروض ترويجية. إذا كانت هناك خلاصة عروض ترويجية حالية متاحة، استخدِم طريقة accounts.dataSources.get للحصول على اسم مصدر البيانات.

في ما يلي نموذج الطلب:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT}/dataSources

مثال

يعرض المثال طلبًا واستجابةً نموذجيَين.

الطلب:

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 واسم مصدر بيانات كمدخلات. ويعرض الإجراء الترويجي الجديد أو المعدَّل في حال نجاح العملية.

يتطلّب إنشاء عرض ترويجي اسم مصدر البيانات.

ملاحظة مهمة: يؤدي هذا الطلب إلى استبدال مورد العروض الترويجية بالكامل، لذا يجب أن يتضمّن الطلب جميع تفاصيل العروض الترويجية لتجنّب فقدان المعلومات.

يراجع فريق 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"
      },
      "minimumPurchaseQuantity": 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"
}

ملاحظات خاصة

بعد إنشاء العرض الترويجي، قد يستغرق ظهوره في قاعدة بيانات Shopping بضع دقائق.

للحصول على قائمة بالسمات المتعلّقة بالعروض الترويجية، اطّلِع على إضافة سمات البيانات المنظَّمة.

قبل إنشاء العروض الترويجية وإدارتها، اطّلِع على أفضل الممارسات المتعلّقة بالعروض الترويجية.

الاطّلاع على العروض الترويجية

لعرض عرض ترويجي، استخدِم 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"
   },
   "minimumPurchaseQuantity": 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 for Shopping، يُرجى الاطّلاع على مقالة نقل إدارة العروض الترويجية.