نمای کلی «خدمات مطابقت مشتری وفادار»

این راهنما نحوه استفاده از «سرویس تطابق مشتری وفادار» را در Merchant API شرح می‌دهد. این سرویس به فروشندگان و ارائه‌دهندگان وفاداری طرف سوم که ازطرف فروشندگان عمل می‌کنند امکان می‌دهد داده‌های وفاداری مشتری، مثل شناسه‌های کاربر و اطلاعات سطح، را برای شخصی‌سازی غیرپولی در «جستجوی Google» بدون نیاز به حساب فعال Google Ads مدیریت کنند.

نمای کلی

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

مفاهیم کلیدی

  • میانای یکپارچه: نقطه پایانی منحصربه‌فردی برای افزودن، به‌روزرسانی، یا برداشتن جزئیات سطح وفاداری مشتری.
  • طراحی حریم خصوصی‌محور: برای محافظت از حریم خصوصی کاربر و جلوگیری از کاوش غیرمجاز حساب، این میانای برنامه‌سازی کاربردی از عملیات‌های GET یا LIST پشتیبانی نمی‌کند و اطمینان می‌دهد داده‌ها بدون بازیابی یا ممیزی مدیریت می‌شوند.
  • شناسایی انعطاف‌پذیر: کاربران را بااستفاده از حداقل یک شناسه معتبر، مانند نشانی ایمیل، نشانی فیزیکی، یا شماره تلفن مطابقت دهید.
  • پردازش مبتنی بر موافقت: این سرویس فقط زمانی داده‌های مشتری را ذخیره و استفاده می‌کند که کاربر نهایی موافقت لازم را به Google داده باشد. برای محافظت و جلوگیری از کاوش وجود حساب یا وضعیت موافقت، اگر مطابقت پیدا نشود یا موافقت داده نشود، سرویس موفقیت بی‌صدایی برمی‌گرداند.

پیش‌نیازها

برای استفاده از «سرویس مطابقت مشتری وفادار»، این الزامات را دنبال کنید:

  • راه‌اندازی حساب: مطمئن شوید حساب Merchant Center فعال دارید (یا اگر ارائه‌دهنده وفاداری طرف سوم هستید، دسترسی مجاز به حساب فروشنده دارید). برای استفاده از «سرویس مطابقت مشتری وفادار» لازم نیست حساب Google Ads ایجاد کنید.
  • پیکربندی برنامه وفاداری: برنامه وفاداری را در حساب Merchant Center خود فعال کنید و مطمئن شوید که سطوح وفاداری را تعریف کرده‌اید.
  • آگاهی از ترتیب سطح: از ترتیبی که سطوح وفاداری شما در واسط کاربر Merchant Center تعریف شده است آگاه باشید. این API از این توالی دقیق برای نگاشت enum خود استفاده می‌کند.

روش: ManageLoyaltyCustomerMatch

روش ManageLoyaltyCustomerMatch به‌عنوان واسط مرکزی برای مدیریت انجمن‌های وفاداری مشتری عمل می‌کند. براساس ورودی ارائه‌شده، سرویس به‌طور خودکار تعیین می‌کند که وضعیت سطح وفاداری مشتری را درج، به‌روزرسانی، یا حذف کند. این عملیات خودتوان است: درخواست‌های یکسان تکراری همان تأثیر یک درخواست را دارند.

درخواست زیر نشان می‌دهد چگونه ازطریق API انجمن‌های وفاداری مشتری را مدیریت کنید:

POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage

این درخواست پارامترهای مسیر الزامی زیر را تعریف می‌کند:

  • ‫API_VERSION: نسخه «میانای برنامه‌سازی کاربردی» مثل v1.
  • ‫ACCOUNT_ID: شناسه حساب Merchant Center.

شیء loyaltyCustomer را در بدنه درخواست بگنجانید.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

فیلدهای loyaltyCustomer

  • userIdentifier: مجموعه شناسه‌هایی که برای مطابقت دادن مشتری استفاده می‌شود. حداقل یک فیلد در userIdentifier باید ارائه شود و معتبر باشد.
  • loyaltyTier: سطح وفاداری برای مرتبط کردن با مشتری. با ترتیب سطح در راه‌اندازی Merchant Center مطابقت دارد. برای جزئیات بیشتر، آشنایی با نگاشت loyaltyTier را ببینید. از NON_MEMBER برای برداشتن یک ارتباط موجود استفاده کنید.
  • pointBalance: تراز امتیازات فعلی مشتری.

فیلدهای userIdentifier

حداقل یکی از فیلدهای زیر را ارائه دهید:

  • emailAddress: نشانی ایمیل مشتری.
  • نشانی: نشانی فیزیکی مشتری. ‫PostalCode الزامی است.
  • phoneNumber: شماره تلفن مشتری. قالب E.164 توصیه می‌شود.

فهمیدن نگاشت loyaltyTier

«میانای برنامه‌سازی کاربردی» از نام‌های سفارشی استفاده نمی‌کند. مقادیر شمارشی loyaltyTier (TIER1 تا TIER7) برچسب‌های معنایی هستند. آن‌ها از نام‌های سفارشی (برای مثال، «پاداش‌های طلایی») یا برچسب‌های سفارشی (برای مثال، «سطح_طلایی») که در واسط کاربر Merchant Center اختصاص داده‌اید استفاده نمی‌کنند. درعوض، این سطوح دقیقاً به ترتیبی که در تنظیمات برنامه وفاداری در Merchant Center تعریف کرده‌اید مرتبط می‌شوند:

  • ‫TIER1: با اولین سطح فهرست‌شده در پیکربندی برنامه وفاداری Merchant Center شما مطابقت دارد.
  • ‫TIER2: با سطح دوم فهرست‌شده در پیکربندی برنامه وفاداری Merchant Center شما مطابقت دارد.
  • ‫TIER3 تا TIER7: با سطوح سوم تا هفتم فهرست‌شده در پیکربندی برنامه وفاداری Merchant Center شما مطابقت دارد.

مثال:

اگر برنامه وفاداری Merchant Center شما دارای سطوحی است که به این ترتیب تعریف شده‌اند:

  1. نام سطح: «وضعیت نقره‌ای»، برچسب سطح: «نقره‌ای»
  2. نام سطح: «عضو طلایی»، برچسب سطح: «طلایی»
  3. نام سطح: «نخبگان پلاتینیوم»، برچسب سطح: «پلاتینیوم»

سپس، در accounts.loyaltyCustomers.manage فراخوانی‌های API:

  • برای اختصاص دادن مشتری به «وضعیت نقره‌ای»، باید از loyaltyTier: TIER1 استفاده کنید.
  • برای اختصاص دادن مشتری به «عضو طلایی»، باید از loyaltyTier: TIER2 استفاده کنید.
  • برای اختصاص دادن مشتری به «نخبگان پلاتینیوم»، باید از loyaltyTier: TIER3 استفاده کنید.

مقادیر شمارشی LoyaltyTier

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (برای نشان دادن برداشتن ارتباط وفاداری مشتری استفاده می‌شود)

درک کردن متن پاسخ ManageLoyaltyCustomerMatch

متد ManageLoyaltyCustomerMatch یک شیء ManageLoyaltyCustomerMatchResponse را برمی‌گرداند:

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

ملاحظات مهم برای پاسخ‌ها

  • درج/ به‌روزرسانی موفق (داده ذخیره شد): برای ذخیره یا به‌روزرسانی موفقیت‌آمیز ارتباط سطح وفاداری مشتری، شرایط زیر را برآورده کنید:

    • شما با کاربر Google با userIdentifier ارائه‌شده مطابقت دارید
    • شما loyaltyTier را در درخواست روی مقدار معتبری غیراز NON_MEMBER تنظیم کنید
    • کاربر منطبق با استفاده از داده‌های وفاداری موافقت کرده باشد

پاسخ حاوی loyaltyCustomer شیء از درخواست شما است که نشان می‌دهد سرویس داده‌ها را باموفقیت پردازش و ذخیره کرده است:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • حذف موفقیت‌آمیز: برای برداشتن موفقیت‌آمیز هرگونه ارتباط وفاداری موجود برای مشتری با این فروشنده، باید شرایط زیر برآورده شود:
    • شما با کاربر Google با userIdentifier ارائه‌شده مطابقت دارید
    • شما loyaltyTier را در درخواست روی NON_MEMBER تنظیم کردید

پاسخ در قالب شیء JSON خالی است:

{}
  • بدون مطابقت / بدون رضایت (موفقیت بی‌صدا): اگر userIdentifier ارائه‌شده با «حساب Google» مطابقت نداشته باشد، یا اگر کاربر منطبق با استفاده از داده‌های وفاداری موافقت نکرده باشد، API وضعیت HTTP 200 OK را با شیء JSON خالی برمی‌گرداند: {}. این اتفاق برای هر دو تلاش درج/به‌روزرسانی و برداشتن رخ می‌دهد.

مثال‌ها

TIER1 مربوط به اولین سطح تعریف‌شده (برای مثال، «پایه») است و TIER2 مربوط به سطح دوم (برای مثال، «ممتاز») است.

برای افزودن مشتری به TIER2 یا به‌روز کردن وضعیت او بااستفاده از نشانی ایمیل، درخواست زیر را ارسال کنید:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

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

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

وقتی مطابقت وجود ندارد یا کاربر موافقت نکرده است، API پاسخ زیر را برمی‌گرداند:

{}

برای برداشتن ارتباط وفاداری مشتری بااستفاده از شماره تلفن، درخواست زیر را ارسال کنید:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

صرف‌نظر از اینکه سابقه وجود داشته باشد یا نه، میانای برنامه‌سازی کاربردی پاسخ موفقیت‌آمیز زیر را برمی‌گرداند:

{}

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

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

پاسخ بسته به مطابقت و رضایت مشابه مثال اول است.

مدیریت کردن خطا

این API از کدهای استاندارد HTTP استفاده می‌کند. رشته‌های خطای رایج شامل موارد زیر است:

کد HTTP رشته خطا شرح
۴۰۰ INVALID_ARGUMENT user_identifier یا loyalty_tier وجود ندارد، یا شناسه خالی است.
401 اصالت‌سنجی‌نشده اطلاعات اعتباری نامعتبر یا موجود نیست.
403 PERMISSION_DENIED کاربر اصیل‌سازی‌شده به حساب Merchant Center مشخص‌شده دسترسی ندارد.
404 NOT_FOUND برچسب سطح وفاداری مشخص‌شده در پیکربندی شما وجود ندارد.
412 FAILED_PRECONDITION برنامه وفاداری را در حسابتان پیکربندی نکرده‌اید.
429 RESOURCE_EXHAUSTED به سقف سهمیه رسیدید.

نمونه‌های خطا

مثال برای 404 NOT_FOUND:

هرگونه درخواست معتبر به شناسه حسابی که برنامه وفاداری پیکربندی‌شده ندارد.

این API پاسخ خطای زیر را برمی‌گرداند:

{
  "error": {
    "code": 404,
    "message": "The loyalty program is not found for account: {ACCOUNT_ID}.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "notFound",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_ID": "{ACCOUNT_ID}",
          "REASON": "NOT_FOUND_LOYALTY_PROGRAM"
        }
      }
    ]
  }
}

دلیل: حساب فروشنده در مسیر برنامه وفاداری فعال ندارد.

نمونه‌هایی از 400 INVALID_ARGUMENT:

اگر درخواست حاوی مقدار نامعتبر برای فیلد loyaltyTier باشد، خطایی رخ می‌دهد:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

این API پاسخ خطای زیر را برمی‌گرداند:

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "loyalty_customer.loyalty_tier",
            "description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
          }
        ]
      }
    ]
  }
}

دلیل: TIER11 مقدار شمارشی معتبری برای loyaltyTier نیست. همین خطا می‌تواند زمانی رخ دهد که سعی می‌کنید TIER2 را مشخص کنید درحالی‌که فقط یک سطح دردسترس است.

اگر فیلد الزامی loyaltyTier در بدنه درخواست وجود نداشته باشد، خطایی رخ می‌دهد:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "pointBalance": 100
  }
}

این API پاسخ خطای زیر را برمی‌گرداند:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.loyalty_tier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

دلیل: فیلد loyaltyTier الزامی است.

اگر شناسه نشانی ناقص باشد، مثلاً فیلد postalCode وجود نداشته باشد، خطا رخ می‌دهد:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "address": {
        "locality": "Sunnyvale",
        "administrativeArea": "CA",
        "regionCode": "US"
      }
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

این API پاسخ خطای زیر را برمی‌گرداند:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

دلیل: نشانی ارائه شده است، اما فیلد الزامی postalCode در آن وجود ندارد، بنابراین به‌عنوان شناسه معتبر درنظر گرفته نمی‌شود.

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

سناریو: فروشنده فقط یک سطح در Merchant Center پیکربندی کرده است.

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 100
  }
}

این API پاسخ خطای زیر را برمی‌گرداند:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.loyalty_tier",
          "PATTERN": "valid LoyaltyTier",
          "FIELD_VALUE": "TIER2",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

دلیل: TIER2 درخواست شده است، اما برنامه وفاداری پیوندشده به حساب سطح دوم تعریف‌شده ندارد.

اگر درخواست حاوی emailAddress بدشکل باشد، خطایی رخ می‌دهد:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@google"
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

این API پاسخ خطای زیر را برمی‌گرداند:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

دلیل: قالب نشانی ایمیل نامعتبر است.

اگر شیء userIdentifier خالی باشد، خطایی رخ می‌دهد:

{
  "loyaltyCustomer": {
    "userIdentifier": {},
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

این API پاسخ خطای زیر را برمی‌گرداند:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.user_identifier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

دلیل: شیء userIdentifier وجود دارد اما حاوی فیلدهای شناسه واقعی نیست.

توجه: اعتبارسنجی شناسه.:

  • این API بررسی‌های قالب پایه را روی شناسه‌ها انجام می‌دهد (برای مثال، ساختار ایمیل، وجود postalCode در نشانی‌ها).
  • بااین‌حال، برخی‌از شناسه‌هایی که از بررسی‌های اولیه عبور می‌کنند ممکن است با هیچ حساب کاربری Google مطابقت نداشته باشند یا ممکن است در قالبی نباشند که سیستم تطبیق زیرینه آن را تشخیص دهد. در چنین مواردی، پاسخ موفقیت‌آمیز بی‌صدا و خالی {} با وضعیت HTTP 200 OK دریافت خواهید کرد.

روال‌های مطلوب

برای بهینه‌سازی ادغام، این روال‌های مطلوب را دنبال کنید.

  • برای یکپارچه‌سازی در مقیاس بزرگ: ازآنجایی‌که این «میانای برنامه‌سازی کاربردی» براساس درخواست عمل می‌کند، برای دستیابی به توان عملیاتی لازم برای مجموعه‌های داده بزرگ، موازی‌سازی سمت کارخواه ضروری است. یکپارچه‌سازی‌تان را باید به‌گونه‌ای طراحی کنید که بتواند چندین درخواست هم‌زمان را مدیریت کند. برای راهنمایی درباره نحوه ساختاربندی پیاده‌سازی خود برای مدیریت حجم‌های بالاتر ازطریق موازی‌سازی، به راهنمای ما درباره نحوه ارسال درخواست‌های متعدد مراجعه کنید.

  • مدیریت سهمیه: سهمیه پیش‌فرض ۱٬۰۰۰٬۰۰۰ درخواست در روز و ۱۰٬۰۰۰ درخواست در دقیقه است. برای دیدن اینکه چگونه می‌توانید سهمیه‌هایتان را پایش و بررسی کنید، به سهمیه‌ها و محدودیت‌ها مراجعه کنید.

  • اولویت دادن به نشانی ایمیل: هروقت ممکن بود، emailAddress مشتری را در userIdentifier قرار دهید. نشانی‌های ایمیل معمولاً دقیق‌ترین و مطمئن‌ترین شناسه برای مطابقت دادن کاربران با «حساب‌های Google» آن‌ها است.

  • مدیریت پاسخ‌های خالی: برنامه خود را طوری طراحی کنید که پاسخ‌های خالی {} را به‌عنوان موفقیت به‌درستی تفسیر کند، با این درک که این پاسخ‌ها به این معنی است که داده‌ها به‌دلیل ملاحظات حریم خصوصی (عدم تطابق یا عدم رضایت) ذخیره نشده است. درخواست را دوباره امتحان نکنید.

  • تأیید ترتیب سطح: همیشه ترتیب سطوح وفاداری خود را در واسط کاربر Merchant Center تأیید کنید تا مطمئن شوید که از مقادیر TIER1 تا TIER7 enum صحیح در تماس‌های API خود استفاده می‌کنید. این نگاشت براساس ترتیب تعریف‌شده در واسط کاربر است، نه نام آن‌ها.

  • پایش خطاها: پاسخ‌های «میانای برنامه‌سازی کاربردی» را ثبت و پایش کنید و به هرگونه خطای 4xx توجه کنید تا مشکلات یکپارچه‌سازی را، به‌ویژه خطاهای 404 که ممکن است نشان‌دهنده عدم تطابق در درک سطح باشد، شناسایی کنید.

قبلی
Manage loyalty programs