Flutter SDK

المتطلبات#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (خط الإصدار 3.x).
• Dart خالص: بلا جسور أصلية، وبلا pod install، وبلا تعديلات Gradle. التبعيات المتعدية هي حزم Dart عادية (http وweb_socket_channel وuuid).

التثبيت#

أضف الحزمة من pub.dev:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

التهيئة#

اربط Respondo.navigatorKey بـ MaterialApp لديك حتى تتمكن الحزمة من فتح ورقة المحادثة دون BuildContext الخاص بك، واستدعِ Respondo.init مرة واحدة، ثم Respondo.open().

import 'package:flutter/material.dart';
import 'package:path_provider/path_provider.dart';
import 'package:respondo_sdk/respondo_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // يأتي دليل تخزين الملفات من إضافة تطبيق مضيف؛ تبقى الحزمة خالصة.
  final dir = await getApplicationSupportDirectory();

  await Respondo.init(
    RespondoConfig(
      agentId: '<agent-uuid>',
      channelId: '<channel-uuid>',
      storageDirectory: dir.path,
    ),
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Respondo.navigatorKey, // مطلوب حتى تتمكن الحزمة من فتح المحادثة
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

جميع طرق الواجهة مثالية التكرار (idempotent)، وآمنة للاستدعاء قبل التهيئة (تُخزَّن ثم يُعاد تشغيلها)، ولا تُلقي أبداً استثناءً داخل تطبيقك.

تعريف المستخدمين#

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

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

الـ userHash هو توقيع تحسبه خلفيتك من identity_secret الخاص بالوكيل — HMAC-SHA256(secret, userId) (أو البريد الإلكتروني حين لا يوجد userId)، مُرمَّزاً كنظام ست عشري بأحرف صغيرة. يثبت السر أن الهوية أصيلة، لذا يجب أن يبقى على خلفيتك فقط ولا يُشحن أبداً في التطبيق. راجع صفحة التحقق من الهوية للاطلاع على الصيغة الكاملة وأمثلة جانب الخادم.

// 1. سجّل الدخول عبر خلفيتك الخاصة واقرأ التجزئة المحسوبة مسبقاً
//    (مثلاً، حقل يُعاد إلى جانب استجابة تسجيل الدخول).
final session = await api.login(email, password);

// 2. سلّم userHash الجاهز إلى الحزمة — لا تحسبه أبداً داخل التطبيق.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. عند تسجيل الخروج: أبطل الجلسة وابدأ زائراً مجهولاً جديداً.
Respondo.reset();

إذا كان التجزئة مفقودة أو خاطئة، فلا يُلقى أي استثناء: تُبقي الخلفية الزائر مجهولاً بصمت، وتستمر المحادثة في العمل، وتفقد ببساطة الربط عبر الأجهزة حتى يُقدَّم تجزئة صالحة. لا يعمل التحقق إلا عندما يكون للوكيل identity_secret مضبوط — اتركه فارغاً أثناء التطوير ويُقبل userId / البريد الإلكتروني كما هما.

Observables والاستدعاءات الراجعة#

كل شيء متاح على هيئة Stream بثّي، ومحدِّد استدعاء راجع، ودالة جلب للقيمة الحالية.

// تدفق تفاعلي لأعداد غير المقروء (من أجل شارة).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// أو محدِّد استدعاء راجع.
Respondo.onUnreadChanged = (n) => setBadge(n);

// اعترض الروابط/عناصر الحث؛ أعِد true إذا فتح المضيف الرابط بنفسه.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

تتبّع الشاشة#

أبلغ عن الشاشة الحالية عند كل تنقّل حتى تتمكن العروض التشويقية الاستباقية والاستهداف على مستوى الصفحة من المطابقة معها. مرّر null لمسحها؛ ومع كل تغيير يُعاد تقييم العرض التشويقي الاستباقي للشاشة الجديدة.

Respondo.setCurrentScreen('pricing');

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

أضف الإشعارات الفورية والتحقق من الهوية. أما سطح واجهة API الكامل، وأسطح التفاعل، واستكشاف الأخطاء وإصلاحها فمشمولة في دليل بدء استخدام Flutter SDK على صفحة حزمة pub.dev.