الردّ التلقائي على الويب

عنوان URL يحدّده الشريك، وتنشر فيه منصة RCS for Business الرسائل والأحداث. يعمل عنوان URL هذا كنقطة نهاية تتلقّى طلبات HTTPS POST تحتوي على بيانات حول الأحداث. وهذا يعني أنّه يتم إرسال البيانات إلى تطبيقك بشكل آمن عبر HTTPS.

قد يبدو رابط ويب هوك على النحو التالي: https://[your company name].com/api/rbm-events. بعد ضبط Webhook، يمكنك البدء في تلقّي الرسائل والأحداث.

الويب هوك الخاص بالشريك والويب هوك الخاص بالوكيل

يمكنك ضبط الويب هوك إمّا على مستوى الشريك أو على مستوى الوكيل.

في حال ضبطت ويب هوك خاصًا بالشريك وآخر خاصًا بموظّف الدعم، سيتم تطبيق الويب هوك الخاص بموظّف الدعم على موظّف الدعم المعنيّ، بينما سيتم تطبيق الويب هوك الخاص بالشريك على أي موظّف دعم لا يتوفّر له ويب هوك خاص به.

ضبط الويب هوك الخاص بالوكيل

تتلقّى الرسائل المُرسَلة إلى موظّف الدعم في ويب هوك الشريك. إذا كنت تريد أن تصل رسائل وكيل معيّن إلى ويب هوك مختلف، عليك ضبط ويب هوك للوكيل.

  1. افتح Business Communications Developer Console وسجِّل الدخول باستخدام حساب Google الخاص بشريك RCS for Business.
  2. انقر على الوكيل.
  3. انقر على عمليات الدمج.
  4. بالنسبة إلى Webhook، انقر على ضبط.
  5. بالنسبة إلى عنوان URL لنقطة نهاية الويب هوك، أدخِل رابط ويب هوك يبدأ بـ "https://‎".
  6. دوِّن قيمة clientToken. تحتاج إلى هذا الرقم للتأكّد من أنّ الرسائل التي تتلقّاها واردة من Google.

  7. اضبط إعدادات الويب هوك لقبول طلب POST يتضمّن المَعلمة clientToken المحدّدة وإرسال ردّ 200 OK يتضمّن قيمة نصية عادية للمَعلمة secret كجزء من نص الردّ.

    على سبيل المثال، إذا تلقّى خطاف الويب طلب POST يتضمّن محتوى النص الأساسي التالي

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    بعد ذلك، يجب أن يؤكّد الويب هوك قيمة clientToken، وإذا كانت clientToken صحيحة، يجب أن يعرض الرد 200 OK مع 1234567890 كنص الرد:

    // clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});

  8. في Developer Console، انقر على تأكيد. عندما تتحقّق خدمة RCS for Business من عنوان URL الخاص بخدمة الويب، يتم إغلاق مربّع الحوار.

التحقّق من الرسائل الواردة

بما أنّ خطافات الويب يمكنها تلقّي رسائل من أي مرسل، عليك التأكّد من أنّ Google هي من أرسل الرسائل الواردة قبل معالجة محتوى الرسالة.

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

  1. استخرِج عنوان X-Goog-Signature للرسالة. هذه نسخة مجزأة ومشفّرة باستخدام base64 من حمولة نص الرسالة.
  2. فك ترميز حمولة RCS for Business باستخدام Base-64 في العنصر message.body من الطلب.
  3. باستخدام الرمز المميز للعميل الخاص بخطاف الويب (الذي حدّدته عند إعداد خطاف الويب)، أنشئ رمز SHA512 HMAC من وحدات البايت الخاصة بحمولة الرسالة التي تم فك ترميزها باستخدام base-64، ثم أعد ترميز النتيجة باستخدام base64.
  4. قارِن قيمة التجزئة X-Goog-Signature بقيمة التجزئة التي أنشأتها.
    • في حال تطابقت التجزئات، يعني ذلك أنّك أكّدت أنّ Google أرسلت الرسالة.

    • في حال عدم تطابق قيم التجزئة، تحقَّق من عملية التجزئة على رسالة معروفة بأنّها صحيحة.

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

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

التعامل مع الرسائل

يُعدّ إرجاع أي شيء آخر غير 200 OK من الويب هوك فشلاً في التسليم.

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

  • تأكَّد من ضبط إعدادات الحماية من هجمات حجب الخدمة الموزّعة (DDoS) للتعامل مع المعدّل المتوقّع لإشعارات الويب هوك.
  • تأكَّد من عدم نفاد الموارد، مثل مجموعات ربط قواعد البيانات، ومن عدم حدوث مهلات أو ظهور الردود 500.

على المطوّرين تصميم أنظمتهم بطريقة تتم فيها معالجة أحداث RBM بشكل غير متزامن، وبما لا يمنع Webhook من عرض 200 OK.

معالجة خطاف الويب غير المتزامنة

من المهم عدم معالجة حدث RBM ضمن رمز ربط الويب نفسه. قد يؤثر أي خطأ أو تأخير أثناء المعالجة في رمز الإرجاع الخاص بخطاف الويب:

معالجة Webhook المتزامنة

السلوك في حال تعذّر التسليم

إذا كان رمز حالة Webhook يعرض أي شيء آخر غير 200 OK، تستخدم منصة RCS for Business آلية للتراجع وإعادة المحاولة لإعادة تسليم البيانات. وهذا يعني أنّ النظام يزيد تدريجيًا التأخير بين كل محاولة تسليم، إلى أن يصل في النهاية إلى الحد الأقصى لمعدل التكرار وهو محاولة إعادة إرسال واحدة كل 10 دقائق لكل رسالة معلّقة. تستمر دورة إعادة المحاولة لمدة سبعة أيام، وبعد ذلك يتم حذف الرسالة نهائيًا.

تأثيرات الويب هوك على مستوى الوكيل

تضع ميزة RCS for Business الرسائل في قائمة انتظار واحدة للشريك. تتشارك جميع الحسابات الفرعية ضمن حساب شريك واحد قائمة انتظار واحدة. نتيجةً لذلك، يمكن أن يؤدي تعذُّر تنفيذ أحد طلبات الويب هوك إلى حظر قائمة الانتظار بأكملها، ما يمنع وصول أحداث المستخدمين إلى الشريك.

يمكن أن يؤدي عدم تلقّي إشعارات استلام عدة رسائل إلى حدوث ارتفاع كبير في أحداث إعادة المحاولة. على سبيل المثال، إذا لم يقرّ وكيل باستلام 1,600 إيصال تسليم، وبلغت وتيرة إعادة المحاولة الحدّ الأقصى البالغ 10 دقائق، يمكن أن يؤدي ذلك إلى حدوث حوالي 230,000 خطأ محتمل في اليوم:

1,600 رسالة × 6 محاولات إعادة إرسال في الساعة × 24 ساعة في اليوم = حوالي 230,000 خطأ في اليوم

يمكن أن يؤدي هذا العدد الكبير من محاولات إعادة الإرسال إلى حظر قائمة انتظار Pub/Sub المشترَكة والتسبّب في تأخيرات كبيرة في تلقّي أحداث المستخدمين لجميع حملات أحد الشركاء.

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

لضمان موثوقية عدد الزيارات في مرحلة الإنتاج وتجنُّب المشاكل التي تعيق عمل قائمة الانتظار، اتّبِع أفضل الممارسات التالية:

  • إرجاع 200 OK على الفور: يجب أن يتلقّى ويب هوك الرسالة ويخزّنها في قائمة انتظار محلية، ثم يعرض استجابة 200 OK في أقل من خمس ثوانٍ.
  • فصل المعالجة: استخدِم عمليات تنفيذ منفصلة في الخلفية لمعالجة منطق الرسائل من قائمة الانتظار المحلية.
  • مراقبة الوكلاء التجريبيين: يجب التعامل مع وكلاء التطوير على أنّهم وكلاء إنتاج، لأنّهم قد يحظرون أيضًا قائمة انتظار الشريك المشتركة في حال حدوث خطأ.
  • حسابات مخصّصة للاختبار: يُفضّل استخدام حساب مطوِّر واحد لبرامج الإنتاج وحساب مطوِّر مخصّص لبرامج الاختبار.
  • التحقّق من زيارات Google: استخدِم نظام أسماء النطاقات العكسي أو العنوان X-Goog-Signature بدلاً من القائمة المسموح بها الثابتة لعناوين IP، لأنّ Google تستخدم عناوين IP ديناميكية بنظام البث المتعدّد. للحصول على مزيد من المعلومات حول عملية التحقّق اليدوي وتحديد نطاقات IP الخاصة بمحرك بحث Google، يُرجى الاطّلاع على مستند التحقّق من طلبات Google، وتحديدًا ملفات JSON الخاصة ببرامج الجلب التي يشغّلها المستخدم وبرامج الجلب التي يشغّلها المستخدم من Google.

الخطوات التالية

بعد ضبط Webhook، سيتمكّن الوكيل من تلقّي الرسائل من أجهزة الاختبار. أرسِل رسالة للتحقّق من صحة عملية الإعداد.

التالي
Dialogflow