نظرة عامة على خدمة "مطابقة العملاء" في برنامج الولاء

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

نظرة عامة

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

المفاهيم الرئيسية

  • واجهة موحّدة: نقطة نهاية فريدة لإضافة تفاصيل فئة ولاء العملاء أو تعديلها أو إزالتها.
  • تصميم يركّز على الخصوصية أولاً: لحماية خصوصية المستخدم ومنع فحص الحسابات غير المصرّح به، لا تتيح واجهة برمجة التطبيقات عمليات GET أو LIST، ما يضمن إدارة البيانات بدون استرجاع أو تدقيق.
  • تحديد الهوية بمرونة: يمكنك مطابقة المستخدمين باستخدام معرّف صالح واحد على الأقل، مثل عنوان البريد الإلكتروني أو العنوان أو رقم الهاتف.
  • المعالجة المستندة إلى الموافقة: تخزّن الخدمة بيانات العملاء وتستخدمها فقط عندما يمنح المستخدم النهائي موافقته اللازمة إلى Google. لحماية حالة الموافقة ومنع التحقّق من وجود الحساب، تعرض الخدمة نجاحًا غير مرئي إذا لم يتم العثور على تطابق أو لم يتم منح الموافقة.

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

يجب استيفاء المتطلبات التالية لاستخدام "خدمة مطابقة العملاء" في برنامج الولاء:

  • إعداد الحساب: تأكَّد من أنّ لديك حسابًا نشطًا على Merchant Center. لست بحاجة إلى إنشاء حساب على "إعلانات Google" لاستخدام خدمة "مطابقة العملاء" في برنامج الولاء.
  • إعداد برنامج الولاء: فعِّل برنامج الولاء في حسابك على Merchant Center، وتأكَّد من أنّك حدّدت مستويات الولاء.
  • الوعي بترتيب الفئات: يجب الانتباه إلى ترتيب فئات برنامج الولاء عند تحديدها في واجهة مستخدم Merchant Center. تستخدم واجهة برمجة التطبيقات هذا التسلسل الدقيق لربط القيم المتعدّدة الثوابت.

الطريقة: ManageLoyaltyCustomerMatch

تعمل طريقة ManageLoyaltyCustomerMatch كواجهة مركزية لإدارة عمليات الربط بين العملاء وبرامج الولاء. استنادًا إلى المعلومات المقدَّمة، تحدّد الخدمة تلقائيًا ما إذا كان يجب إدراج حالة مستوى الولاء للعميل أو تعديلها أو إزالتها. العملية متكررة: الطلبات المتطابقة المتكررة لها التأثير نفسه الذي يحدثه طلب واحد.

يوضّح الطلب التالي كيفية إدارة عمليات الربط ببرامج ولاء العملاء من خلال واجهة برمجة التطبيقات:

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: عنوان البريد الإلكتروني للعميل.
  • العنوان: العنوان الجغرافي للعميل. يجب إدخال الرمز البريدي.
  • استبدِل phoneNumber برقم هاتف العميل. ننصحك باستخدام تنسيق E.164.

فهم عملية ربط loyaltyTier

لا تستخدم واجهة برمجة التطبيقات الأسماء المخصّصة. قيم التعداد loyaltyTier (من TIER1 إلى TIER7) هي تصنيفات دلالية. ولا تستخدم الأسماء المخصّصة (مثل "مكافآت ذهبية") أو التصنيفات المخصّصة (مثل "المستوى الذهبي") التي حدّدتها في واجهة مستخدم Merchant Center. بدلاً من ذلك، يتم ربطها بشكل صارم بترتيب تحديد مستوياتك في إعدادات برنامج الولاء في Merchant Center:

  • ‫TIER1: تتوافق مع المستوى الأول المُدرَج في إعدادات برنامج الولاء في Merchant Center.
  • ‫TIER2: تتوافق مع المستوى الثاني المُدرَج في إعدادات برنامج الولاء في Merchant Center.
  • ‫TIER3 إلى TIER7: تتوافق مع المستويات من الثالث إلى السابع المدرَجة في إعدادات برنامج الولاء في حسابك على Merchant Center.

مثال:

إذا كان برنامج الولاء في Merchant Center يتضمّن مستويات محدّدة بهذا الترتيب:

  1. اسم المستوى: "Silver Status"، تصنيف المستوى: "silver"
  2. اسم المستوى: "Gold Member"، تصنيف المستوى: "gold"
  3. اسم المستوى: "Platinum Elite"، تصنيف المستوى: "platinum"

بعد ذلك، في accounts.loyaltyCustomers.manage طلبات البيانات من واجهة برمجة التطبيقات:

  • لتحديد حالة العميل على أنّها "الحالة الفضية"، يجب استخدام 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، أو إذا لم يوافق المستخدم المطابِق على استخدام بيانات برنامج الولاء، ستعرض واجهة برمجة التطبيقات حالة 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
  }'

عندما يتم العثور على تطابق مع مستخدم بنجاح ويوافق على المشاركة، تعرض واجهة برمجة التطبيقات الاستجابة التالية:

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

عندما لا يكون هناك تطابق أو لم يوافق المستخدم، تعرض واجهة برمجة التطبيقات الردّ التالي:

{}

لإزالة ربط برنامج الولاء الخاص بأحد العملاء باستخدام رقم هاتف، أرسِل الطلب التالي:

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

تكون الاستجابة مشابهة للمثال الأول، وذلك حسب المطابقة والموافقة.

معالجة الأخطاء

تستخدِم واجهة برمجة التطبيقات رموز HTTP العادية. تشمل سلاسل الأخطاء الشائعة ما يلي:

رمز HTTP سلسلة الخطأ الوصف
400 INVALID_ARGUMENT user_identifier أو loyalty_tier غير متوفّرَين، أو المعرّف فارغ.
401 UNAUTHENTICATED بيانات الاعتماد غير صالحة أو غير متوفّرة.
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 متوفّر ولكنّه لا يحتوي على أي حقول معرّف فعلية.

ملاحظة حول التحقّق من صحة المعرّف:

  • تجري واجهة برمجة التطبيقات عمليات تحقّق أساسية من التنسيق على المعرّفات (على سبيل المثال، بنية البريد الإلكتروني، وتوفّر postalCode في العناوين).
  • ومع ذلك، قد لا تتطابق بعض المعرّفات التي تجتاز عمليات التحقّق الأولية مع أي حساب مستخدم على Google، أو قد لا تكون بالتنسيق الذي يتعرّف عليه نظام المطابقة الخلفي. في مثل هذه الحالات، ستتلقّى الردّ الناجح الصامت الفارغ {} مع حالة HTTP 200 OK.

أفضل الممارسات

اتّبِع أفضل الممارسات التالية لتحسين عملية الدمج.

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

  • إدارة الحصة: الحصة التلقائية هي 1,000,000 طلب في اليوم و10,000 طلب في الدقيقة. لمعرفة كيفية مراقبة حصصك والتحقّق منها، اطّلِع على الحصص والحدود.

  • تحديد أولوية عنوان البريد الإلكتروني: متى أمكن ذلك، يجب تضمين emailAddress العميل في userIdentifier. تُعدّ عناوين البريد الإلكتروني بشكل عام المعرّف الأكثر دقة وموثوقية لمطابقة المستخدمين مع حساباتهم على Google.

  • التعامل مع الردود الفارغة: صمِّم تطبيقك بطريقة تتيح له تفسير الردود الفارغة {} بشكل صحيح على أنّها ناجحة، مع العلم أنّ ذلك يعني أنّه لم يتم تخزين البيانات لأسباب تتعلّق بالخصوصية (عدم العثور على تطابق أو عدم الحصول على الموافقة). عدم إعادة محاولة تنفيذ الطلب

  • التحقّق من ترتيب فئات برنامج الولاء: احرص دائمًا على تأكيد ترتيب فئات برنامج الولاء في واجهة مستخدم Merchant Center لضمان استخدام قيم التعداد TIER1 إلى TIER7 الصحيحة في طلبات البيانات من واجهة برمجة التطبيقات. ويستند هذا الربط إلى الترتيب المحدّد في واجهة المستخدم، وليس إلى الأسماء.

  • مراقبة الأخطاء: سجِّل استجابات واجهة برمجة التطبيقات وراقِبها، مع الانتباه إلى أي أخطاء 4xx لرصد مشاكل الدمج، خاصةً أخطاء 404 التي قد تشير إلى عدم تطابق في فهم المستوى.