بررسی اجمالی سرویس تطبیق مشتری وفاداری

این راهنما نحوه استفاده از سرویس تطبیق مشتری وفاداری در رابط برنامه‌نویسی کاربردی فروشنده (Merchant API) را شرح می‌دهد. این سرویس به فروشندگان امکان می‌دهد داده‌های وفاداری مشتری، مانند شناسه‌های کاربر و اطلاعات رده‌بندی را برای شخصی‌سازی ارگانیک در جستجوی گوگل، بدون نیاز به حساب فعال تبلیغات گوگل، مدیریت کنند.

نمای کلی

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

مفاهیم کلیدی

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

پیش‌نیازها

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

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

روش: ManageLoyaltyCustomerMatch

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

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

POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage

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

  • api_version : نسخه API مانند v1.
  • account_id : شناسه حساب مرکز فروشندگان.

یک شیء loyaltyCustomer را در بدنه درخواست قرار دهید.

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

فیلدهای وفاداری مشتری

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

فیلدهای شناسه کاربر

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

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

نقشه‌برداری loyaltyTier mapping) را درک کنید

این API از نام‌های سفارشی استفاده نمی‌کند. مقادیر شمارشی loyaltyTier ( TIER1 تا TIER7 ) برچسب‌های معنایی هستند. آن‌ها از نام‌های سفارشی (مثلاً "Gold Rewards") یا برچسب‌های سفارشی (مثلاً "gold_tier") که شما در رابط کاربری مرکز فروشندگان خود تعیین کرده‌اید، استفاده نمی‌کنند. در عوض، آن‌ها دقیقاً به ترتیبی که سطوح خود را در تنظیمات برنامه وفاداری در مرکز فروشندگان تعریف کرده‌اید، نگاشت می‌شوند:

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

مثال:

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

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

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

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

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

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

بدنه پاسخ ManageLoyaltyCustomerMatch را درک کنید

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

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

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

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

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

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

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

پاسخ یک شیء JSON خالی است:

{}
  • عدم تطابق / عدم رضایت (موفقیت خاموش): اگر userIdentifier ارائه شده با یک حساب گوگل مطابقت نداشته باشد، یا اگر کاربر مطابقت داده شده به استفاده از داده‌های وفاداری رضایت نداده باشد، 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 رشته خطا توضیحات
۴۰۰ آرگومان نامعتبر شناسه کاربری یا ردیف وفاداری کاربر وجود ندارد، یا شناسه خالی است.
۴۰۱ احراز هویت نشده اعتبارنامه‌های نامعتبر یا مفقود.
۴۰۳ مجوز_رد_شد کاربر احراز هویت شده به حساب مرکز فروشندگان مشخص شده دسترسی ندارد.
۴۰۴ یافت نشد برچسب سطح وفاداری مشخص شده در پیکربندی شما وجود ندارد.
۴۱۲ پیش‌شرط ناموفق شما برنامه وفاداری را در حساب خود پیکربندی نکرده‌اید.
۴۲۹ منابع_تمام_شده سقف سهمیه تکمیل شد.

مثال‌های خطا

مثال برای خطای ۴۰۴ 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"
        }
      }
    ]
  }
}

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

نمونه‌هایی از خطای ۴۰۰ 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 الزامی است.

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

{
  "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 مورد نیاز را ندارد، بنابراین یک شناسه معتبر محسوب نمی‌شود.

اگر درخواست یک شاخص سطح (tier index) داشته باشید که خارج از محدوده برنامه پیکربندی شده باشد، خطایی رخ می‌دهد:

سناریو: تاجر فقط یک سطح در مرکز بازرگانان پیکربندی کرده است. 

{
  "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 در آدرس‌ها).
  • با این حال، برخی از شناسه‌هایی که بررسی‌های اولیه را با موفقیت پشت سر می‌گذارند، ممکن است با هیچ حساب کاربری گوگلی مطابقت نداشته باشند یا ممکن است در قالبی نباشند که توسط سیستم تطبیق backend شناخته شده باشد. در چنین مواردی، پاسخ بی‌صدای success empty {} با وضعیت HTTP 200 OK دریافت خواهید کرد.

بهترین شیوه‌ها

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

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

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

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

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

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

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