Flutter SDK

Yêu cầu#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (dòng 3.x).
• Dart thuần: không cầu nối native, không pod install, không chỉnh sửa Gradle. Các phụ thuộc bắc cầu là các gói Dart thuần túy (http, web_socket_channel, uuid).

Cài đặt#

Thêm gói từ pub.dev:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

Khởi tạo#

Gắn Respondo.navigatorKey vào MaterialApp của bạn để SDK có thể mở sheet trò chuyện mà không cần BuildContext của bạn, gọi Respondo.init một lần, rồi 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();

  // Thư mục lưu trữ tệp đến từ một plugin của ứng dụng host; SDK vẫn thuần túy.
  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, // bắt buộc để SDK có thể mở chat
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

Mọi phương thức của mặt tiền đều có tính idempotent, an toàn khi gọi trước init (chúng đệm lại và phát lại), và không bao giờ ném lỗi vào ứng dụng của bạn.

Nhận diện người dùng#

Theo mặc định mọi khách truy cập đều ẩn danh. Trong lần khởi chạy đầu tiên, SDK tạo một visitor_id ổn định và giữ nó trong bộ nhớ cục bộ, nhờ đó một người dùng quay lại tìm thấy cuộc hội thoại của họ. Không có API key nào cần nhúng — mỗi cuộc hội thoại được bảo vệ bởi một session token theo từng cuộc hội thoại mà backend đúc ra và trượt về phía trước sau mỗi tin nhắn, nhờ đó một khách ẩn danh không bao giờ phải xác thực lại.

Gọi identify một khi người dùng của bạn đã đăng nhập. Điều này gắn danh tính thực của họ để lịch sử theo họ qua các thiết bị và lần cài lại, và tên cùng email của họ hiển thị bên cạnh cuộc hội thoại trong hộp thư của bạn thay vì một khách ẩn danh.

userHash là một chữ ký mà backend của bạn tính từ identity_secret của agent — HMAC-SHA256(secret, userId) (hoặc email khi không có userId), mã hóa dưới dạng hex chữ thường. Secret chứng minh danh tính là xác thực, nên nó chỉ được sống trên backend của bạn và không bao giờ được đóng gói trong ứng dụng. Xem trang Xác minh danh tính để biết công thức đầy đủ và các ví dụ phía máy chủ.

// 1. Đăng nhập vào backend của riêng bạn và đọc hash đã tính sẵn
//    (ví dụ, một trường trả về cùng với phản hồi đăng nhập).
final session = await api.login(email, password);

// 2. Trao userHash đã hoàn tất cho SDK — đừng bao giờ tính nó trong ứng dụng.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. Khi đăng xuất: thu hồi session và khởi tạo một khách ẩn danh mới.
Respondo.reset();

Nếu hash bị thiếu hoặc sai, không có ngoại lệ nào được ném ra: backend âm thầm giữ khách truy cập ẩn danh, cuộc hội thoại vẫn hoạt động, và bạn chỉ đơn giản mất liên kết đa thiết bị cho đến khi cung cấp một hash hợp lệ. Việc xác minh chỉ chạy khi agent có identity_secret được đặt — hãy để trống trong quá trình phát triển và userId / email được chấp nhận nguyên trạng.

Observable & callback#

Mọi thứ đều có sẵn dưới dạng một Stream broadcast, một setter callback, và một getter giá trị hiện tại.

// Stream phản ứng của số tin chưa đọc (cho một huy hiệu).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// Hoặc một setter callback.
Respondo.onUnreadChanged = (n) => setBadge(n);

// Chặn link/CTA; trả về true nếu host đã tự mở URL.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

Theo dõi màn hình#

Báo cáo màn hình hiện tại trên mỗi lần điều hướng để teaser chủ động và nhắm mục tiêu cấp trang có thể khớp với nó. Truyền null để xóa nó; trên mỗi thay đổi, teaser chủ động được đánh giá lại cho màn hình mới.

Respondo.setCurrentScreen('pricing');

Bước tiếp theo#

Thêm Thông báo đẩy và Xác minh danh tính. Toàn bộ bề mặt API, các bề mặt tương tác, và xử lý sự cố được đề cập trong hướng dẫn bắt đầu của Flutter SDK trên trang gói pub.dev.