نمای کلی برنامه‌های وفاداری

بااستفاده از برنامه‌های وفاداری، مزایای فروشگاهتان را در Google نمایش دهید. می‌توانید طیفی از مزایا را ارسال کنید، مثل ارسال رایگان، امتیازهای قابل‌پس‌خرید، و قیمت‌گذاری انحصاری برای اعضا. مزایای برنامه وفاداری شما می‌تواند در فهرستگان‌های رایگان، آگهی‌های Shopping، و آگهی‌های فهرست موجودی محلی در سراسر سطوح Google، ازجمله «جستجوی Google»، زبانه Shopping، و «کیف پول Google» نشان داده شود.

با Merchant API، فروشندگان و ارائه‌دهندگان طرف سوم برنامه وفاداری که ازطرف فروشندگان اقدام می‌کنند می‌توانند برنامه‌های وفاداری را به‌صورت برنامه‌نویسی‌شده بااستفاده از LoyaltyProgramService پیکربندی و نگهداری کنند. این سرویس به شما امکان می‌دهد برنامه‌های وفاداری را ایجاد، بازیابی، فهرست، به‌روزرسانی، و حذف کنید.

برای اطلاعات بیشتر درباره الزامات کسب‌وکار و رهنمودهای خط‌مشی، به درباره برنامه وفاداری فروشنده در «مرکز راهنمایی Merchant Center» مراجعه کنید.

مفاهیم کلیدی

هنگام کار با برنامه‌های وفاداری، مفاهیم و محدودیت‌های زیر را به‌خاطر داشته باشید:

  • شناسه سطح حساب: Merchant API برنامه‌های وفاداری را براساس شناسه حساب Merchant Center مالک شناسایی می‌کند.

  • محدودیت برنامه تکی: Merchant API فقط از یک برنامه وفاداری برای هر حساب فروشنده پشتیبانی می‌کند.

  • مالکیت مستقیم حساب: برنامه‌های وفاداری باید مستقیماً در حساب فروشنده هدف (accounts/{ACCOUNT_ID}) پیکربندی شوند. این سرویس از مدیریت برنامه‌های وفاداری در سطح حساب پیشرفته برای حساب‌های فرعی پشتیبانی نمی‌کند. ارائه‌دهندگان وفاداری طرف سوم با دسترسی مجاز به حساب فروشنده می‌توانند برنامه را ازطرف فروشنده مدیریت کنند.

  • بازبینی سردبیری: پس‌از ایجاد یا به‌روزرسانی برنامه وفاداری، برنامه تحت بازبینی قرار می‌گیرد. فیلد review_result.review_status نشان می‌دهد که برنامه UNDER_REVIEW، APPROVED، یا REJECTED است. هر به‌روزرسانی موفق، برنامه را به صف بازبینی برمی‌گرداند، حتی اگر به‌روزرسانی تغییر مهمی ایجاد نکند. Google برنامه را درطول فرایند بازبینی از خریداران پنهان می‌کند. بررسی ممکن است تا ۴۸ ساعت طول بکشد.

  • مناطق پشتیبانی‌شده: برنامه‌های وفاداری فروشنده در کشورهای پشتیبانی‌شده ازجمله آلمان، اسپانیا، استرالیا، ایالات متحده، ایتالیا، برزیل، پادشاهی متحد، ژاپن، فرانسه، کانادا، کره جنوبی، مکزیک، هلند، و هند دردسترس است.

  • مناطق فعال: regionCodes برنامه وفاداری باید زیرمجموعه‌ای از activeRegionCodes accounts/{ACCOUNT_ID}/programs/loyalty باشد. درغیراین‌صورت، درخواست‌های ایجاد، به‌روزرسانی، و حذف با خطای LOYALTY_PROGRAM_DISABLED مواجه می‌شوند. وقتی برافزای برنامه «وفاداری» فعال باشد و حساب شرایط واجدشرایط بودن را در آن کشور داشته باشد، Google کشور پشتیبانی‌شده را فعال می‌کند. برای مثال، اگر برنامه «فهرستگان رایگان» فعال باشد و منبع داده‌های محصول اصلی، کشور مقصد FREE_LISTINGS را هدف‌یابی کند، حساب واجدشرایط است. برای اینکه بدانید چرا کشوری فعال نیست، به بررسی مناطق فعال مراجعه کنید.

  • الزامات سطح: سطوح می‌توانند بدون هزینه برای پیوستن باشند، نیاز به هزینه عضویت داشته باشند، نیاز به آستانه هزینه داشته باشند، یا نیاز به کارت اعتباری با نمانام فروشنده داشته باشند. از سطوح مبتنی بر شغل (مانند سطوح دانشجویی یا نظامی) پشتیبانی نمی‌شود.

  • هدایا و مزایا: برنامه‌ها از ارسال رایگان، امتیازهای قابل‌پس‌خرید، و قیمت‌گذاری برای اعضا پشتیبانی می‌کنند. در آگهی‌ها، قیمت‌گذاری برای اعضا مستلزم تخفیف حداقل ۵٪ یا ۵ واحد پولی کمتر از قیمت عادی یا حراجی است.

پیش‌نیازها

پیش‌از مدیریت برنامه‌های وفاداری با Merchant API، مطمئن شوید که الزامات زیر را برآورده می‌کنید:

  • باید حساب Merchant Center فعال داشته باشید (یا اگر ارائه‌دهنده وفاداری شخص ثالث هستید، دسترسی مجاز به حساب فروشنده داشته باشید).
  • برافزای برنامه وفاداری را برای حسابتان فعال کنید. می‌توانید برافزا را بااستفاده از یکی از گزینه‌های زیر فعال کنید:

  • کشورهایی که می‌خواهید برنامه وفاداری‌تان را در آن‌ها ارائه دهید باید برای حسابتان فعال باشند. برای اینکه بدانید کدام کشورها فعال هستند، بررسی مناطق فعال را ببینید.

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

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

cURL

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

بررسی مناطق فعال

پس‌از فعال کردن برافزای «برنامه وفاداری»، روش accounts.programs.get را برای accounts/{ACCOUNT_ID}/programs/loyalty فراخوانی کنید. پاسخ نشان می‌دهد که در کجا می‌توانید از برنامه‌های وفاداری استفاده کنید و چرا دیگر کشورهای پشتیبانی‌شده غیرفعال هستند.

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

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty

cURL

curl --request GET \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --compressed

{ACCOUNT_ID} را با شناسه یکتای حساب Merchant Center خودتان جایگزین کنید.

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

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}

در این پاسخ، فیلدهای زیر را مشاهده کنید:

  • activeRegionCodes: کشورهایی که می‌توانید در regionCodes برنامه وفاداری‌تان استفاده کنید. در نمونه قبلی، فقط US فعال است.
  • unmetRequirements: دلیل غیرفعال بودن سایر کشورهای پشتیبانی‌شده. برای برنامه‌های وفاداری، این شرط IS_ELIGIBLE_FOR_LOYALTY است.

در نمونه قبلی، هنوز نمی‌توانید از کشورهای موجود در affectedRegionCodes استفاده کنید. اگر regionCodes برنامه وفاداری‌تان شامل یکی از آن‌ها باشد، درخواست‌های ایجاد، به‌روزرسانی، و حذف با خطای LOYALTY_PROGRAM_DISABLED ناموفق می‌شود. برای فعال کردن کشور، کارهای زیر را انجام دهید:

  1. حساب را در آن کشور واجدشرایط کنید. برای مثال، برنامه «فهرستگان‌های رایگان» را فعال کنید و منبع داده محصول اصلی را برای هدف‌یابی کشور برای مقصد FREE_LISTINGS تنظیم کنید. برای دیدن همه روش‌های واجدشرایط شدن، الزامات واجدشرایط بودن را ببینید.
  2. دوباره با accounts.programs.get تماس بگیرید و بررسی کنید که کشور در activeRegionCodes باشد.

affectedRegionCodes می‌تواند شامل کشورهایی باشد که در آن‌ها فروش ندارید. برای این کشورها لازم نیست اقدامی انجام دهید. این موارد بر کشورهای موجود در activeRegionCodes تأثیر نمی‌گذارد.

روش‌ها

برنامه‌های وفاداری را بااستفاده از روش‌های زیر مدیریت کنید:

ایجاد کردن برنامه وفاداری

برای ایجاد برنامه وفاداری جدید برای حساب، از روش loyaltyPrograms.create استفاده کنید. جزئیاتی مانند شرح برنامه، نشانی وب ثبت‌نام، و سطوح برنامه با مزایا و الزامات منحصربه‌فرد آن‌ها را مشخص کنید.

program_label الزامی شناسه یکتای برنامه وفاداری را تنظیم می‌کند. برای مثال، ارائه برچسب my-rewards منجر به منبع name از accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards می‌شود.

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

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

{ACCOUNT_ID} را با شناسه یکتای حساب Merchant Center خودتان جایگزین کنید.

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

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

بازیابی برنامه وفاداری

برای بازیابی جزئیات برنامه وفاداری تحت مالکیت خود، از روش loyaltyPrograms.get استفاده کنید.

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

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{ACCOUNT_ID} را با شناسه حسابتان و {PROGRAM_LABEL} را با برچسب یکتای برنامه وفاداری (برای مثال، my-rewards) جایگزین کنید.

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

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

فهرست کردن برنامه‌های وفاداری

برای فهرست کردن همه برنامه‌های وفاداری تحت مالکیت خودتان که با حسابتان مرتبط است، از روش loyaltyPrograms.list استفاده کنید.

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

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

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

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

به‌روزرسانی برنامه وفاداری

برای به‌روزرسانی برنامه وفاداری موجود، از روش loyaltyPrograms.update استفاده کنید. بااستفاده از update_mask، به‌روزرسانی جزئی انجام دهید یا با حذف کردن ماسک، جایگزینی کامل انجام دهید. هر به‌روزرسانی موفق باعث راه‌اندازی بازبینی سرمقاله‌ای جدید می‌شود، بنابراین فقط وقتی مقدار تغییر می‌کند به‌روزرسانی ارسال کنید.

به‌روزرسانی جزئی با ماسک به‌روزرسانی

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

نمونه درخواست زیر فقط programDescriptions و advancedSettings را به‌روز می‌کند:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

در این مثال، سرویس signupUrl را نادیده می‌گیرد زیرا در update_mask گنجانده نشده است. فیلد programDescriptions به‌طور کامل جایگزین هرگونه شرحی می‌شود که قبلاً پیکربندی شده است.

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

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

جایگزینی کامل بدون ماسک به‌روزرسانی

وقتی پارامتر update_mask را حذف می‌کنید، درخواست جایگزینی کامل پیکربندی برنامه وفاداری را انجام می‌دهد.

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

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

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

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

حذف برنامه وفاداری

برای حذف برنامه وفاداری از حسابتان، از روش loyaltyPrograms.delete استفاده کنید.

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

HTTP

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

اگر موفقیت‌آمیز باشد، بدنه پاسخ خالی است.

مراحل بعدی