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 שלכם כדי שה-SDK יוכל לפתוח את גיליון הצ׳אט בלי ה- 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();

  // תיקיית אחסון הקבצים מגיעה מ-plugin של אפליקציית המארח; ה-SDK נשאר טהור.
  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, // נדרש כדי שה-SDK יוכל לפתוח את הצ׳אט
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

כל שיטות הפאסאד אידמפוטנטיות, בטוחות לקריאה לפני האתחול (הן נצברות ומופעלות מחדש), ולעולם אינן זורקות שגיאה אל תוך האפליקציה שלכם.

זיהוי משתמשים#

כברירת מחדל כל מבקר הוא אנונימי. בהפעלה הראשונה ה-SDK מייצר visitor_id יציב ושומר אותו באחסון המקומי, כך שמשתמש חוזר מוצא את השיחה שלו שוב. אין מפתח API להטמיע — כל שיחה מוגנת על ידי אסימון סשן ייעודי לשיחה שה-backend מנפיק ומקדם קדימה בכל הודעה, כך שמבקר אנונימי אינו צריך לעולם לאמת מחדש.

קראו ל-identify ברגע שהמשתמש שלכם מחובר. פעולה זו מצרפת את זהותו האמיתית כך שההיסטוריה שלו עוקבת אחריו בין מכשירים והתקנות מחדש, ושמו והאימייל שלו מופיעים ליד השיחה בתיבת הפניות שלכם במקום מבקר אנונימי.

ה-userHash הוא חתימה שה-backend שלכם מחשב מתוך identity_secret של הסוכן — HMAC-SHA256(secret, userId) (או האימייל כשאין userId), מקודדת כ-hex באותיות קטנות. הסוד מוכיח שהזהות אמיתית, ולכן הוא חייב להתקיים רק ב-backend שלכם ולעולם אינו נשלח באפליקציה. ראו את עמוד אימות הזהות לנוסחה המלאה ולדוגמאות צד שרת.

// 1. התחברו מול ה-backend שלכם וקראו את ה-hash המחושב מראש
//    (למשל, שדה שמוחזר לצד תגובת ההתחברות).
final session = await api.login(email, password);

// 2. מסרו את ה-userHash המוכן ל-SDK — לעולם אל תחשבו אותו באפליקציה.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. בהתנתקות: בטלו את הסשן והתחילו מבקר אנונימי חדש.
Respondo.reset();

אם ה-hash חסר או שגוי, שום דבר לא נזרק כשגיאה: ה-backend שומר את המבקר אנונימי בשקט, הצ׳אט ממשיך לעבוד, ואתם פשוט מאבדים את הקישור החוצה-מכשירי עד שיסופק hash תקין. האימות רץ רק כאשר לסוכן מוגדר identity_secret — השאירו אותו ריק בזמן הפיתוח ואז userId / אימייל מתקבלים כמות שהם.

Observables וקריאות חוזרות#

הכול זמין כ- Stream משדר (broadcast), כ-setter של קריאה חוזרת, וכ-getter של הערך הנוכחי.

// stream ריאקטיבי של מספרי הודעות שלא נקראו (לתג).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// או setter של קריאה חוזרת.
Respondo.onUnreadChanged = (n) => setBadge(n);

// יירוט קישורים/CTA; החזירו true אם המארח פתח את ה-URL בעצמו.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

מעקב מסכים#

דווחו על המסך הנוכחי בכל ניווט כדי שטיזרים יזומים ומיקוד ברמת העמוד יוכלו להתאים אליו. העבירו null כדי לנקות אותו; בכל שינוי הטיזר היזום מוערך מחדש עבור המסך החדש.

Respondo.setCurrentScreen('pricing');

השלבים הבאים#

הוסיפו התראות דחיפה ו-אימות זהות. משטח ה-API המלא, משטחי המעורבות (engagement), ופתרון תקלות מכוסים במדריך ההתחלה של Flutter SDK ב- עמוד החבילה ב-pub.dev.