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

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

نمای کلی

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

مفاهیم کلیدی

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

پیش‌نیازها

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

  • راه‌اندازی حساب: مطمئن شوید که حساب Merchant Center فعالی دارید (یا اگر ارائه‌دهنده وفاداری شخص ثالث هستید، دسترسی مجاز به حساب فروشنده دارید). برای استفاده از «سرویس مطابقت مشتری وفادار» لازم نیست حساب Google Ads ایجاد کنید.
  • پیکربندی برنامه وفاداری: برنامه وفاداری را در حساب Merchant Center خود فعال کنید و مطمئن شوید که سطوح وفاداری را تعریف کرده‌اید.
  • آگاهی از ترتیب سطح: از ترتیبی که سطوح وفاداری شما در میانای کاربری Merchant Center تعریف شده‌اند آگاه باشید. میانای برنامه‌سازی کاربردی از همین توالی برای نگاشت 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: نشانی ایمیل مشتری.
  • address: نشانی فیزیکی مشتری. کد پستی الزامی است.
  • phoneNumber: شماره تلفن مشتری. قالب E.164 توصیه می‌شود.

آشنایی با نگاشت loyaltyTier

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

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

مثال:

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

  1. نام سطح: «وضعیت نقره‌ای»، برچسب سطح: «نقره‌ای»
  2. نام سطح: «عضو طلایی»، برچسب سطح: «طلایی»
  3. نام رده: «Platinum Elite»، برچسب رده: «platinum»

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

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

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

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (Used to signal removal of the customer's loyalty association)

درک کردن متن پاسخ 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"
  }'

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

{}

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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 دریافت خواهید کرد.

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

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

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

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

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

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

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

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

قبلی
Manage loyalty programs