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

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

نظرة عامة

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

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

  • واجهة موحّدة: نقطة نهاية فريدة لإضافة تفاصيل فئة الولاء للعملاء أو تعديلها أو إزالتها
  • تصميم يركّز على الخصوصية: لحماية خصوصية المستخدمين ومنع فحص الحسابات غير المصرَّح به، لا تتيح واجهة برمجة التطبيقات عمليات 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: عنوان البريد الإلكتروني للعميل
  • address: العنوان الجغرافي للعميل يجب إدخال الرمز البريدي.
  • ‫phoneNumber: رقم هاتف العميل ننصح باستخدام تنسيق E.164.

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

لا تستخدم واجهة برمجة التطبيقات الأسماء المخصّصة. إنّ قيم التعداد loyaltyTier (من TIER1 إلى TIER7) هي تصنيفات دلالية. ولا تستخدم الأسماء المخصّصة (مثل "مكافآت ذهبية") أو التصنيفات المخصّصة (مثل "gold_tier") التي حدّدتها في واجهة مستخدم 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.
  • لتعيين عميل إلى "Platinum Elite"، يجب استخدام 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 إلى المستوى الأول المحدّد (على سبيل المثال، 'Basic')، وتشير السمة TIER2 إلى المستوى الثاني (على سبيل المثال، 'Premium').

لإضافة عميل إلى 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 Error String الوصف
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 التي قد تشير إلى عدم تطابق في فهم المستوى.

السابق
Manage loyalty programs