Flutter SDK

Respondo のサポートチャットのための純粋な Dart クライアント——コンパイルやデバッグが必要なネイティブのプラットフォームコードはありません。

要件#

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から追加します：

pubspec.yamlyaml

dependencies:
  respondo_sdk: ^0.1.2

Dartdart

import 'package:respondo_sdk/respondo_sdk.dart';

初期化#

Respondo.navigatorKey を MaterialApp に紐づけると、SDK はあなたの BuildContext なしでチャットシートを開けます。 Respondo.init を一度呼び出し、その後 Respondo.open() を呼び出します。

main.dartdart

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();

  // ファイル保存ディレクトリはホストアプリのプラグインから取得。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 キーはありません——各会話は、バックエンドが発行しメッセージごとに前へスライドさせる会話ごとのセッショントークンで保護されるため、匿名の訪問者が再認証する必要は決してありません。

ユーザーがサインインしたら identify を一度呼び出します。これにより実際の身元が紐づけられ、履歴が複数デバイスや再インストールをまたいで追随し、受信トレイでは匿名の訪問者ではなく名前とメールアドレスが会話の横に表示されます。

userHash はあなたのバックエンドがエージェントの identity_secret から計算する署名です—— HMAC-SHA256(secret, userId) （userId がない場合はメールアドレス）を小文字の hex でエンコードします。シークレットは身元が本物であることを証明するため、あなたのバックエンドにのみ置き、アプリに同梱してはいけません。完全な数式とサーバー側の例については本人確認のページを参照してください。

Dartdart

// 1. 自分のバックエンドに対してサインインし、事前計算済みのハッシュを読み取る
//    （例：ログインレスポンスと一緒に返されるフィールド）。
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();

ハッシュが欠けているか誤っていても、例外は投げられません。バックエンドは黙って訪問者を匿名のまま保ち、チャットは動作し続け、有効なハッシュが供給されるまで単にデバイス間のリンクが失われるだけです。検証はエージェントに identity_secret が設定されている場合にのみ実行されます——開発中は空のままにしておけば userId / メールアドレスはそのまま受け入れられます。

監視可能な値とコールバック#

すべてがブロードキャストの Stream、コールバックのセッター、および現在値のゲッターとして利用できます。

Dartdart

// 未読数のリアクティブなストリーム（バッジ向け）。
Respondo.unreadCountStream.listen((n) => setBadge(n));

// あるいはコールバックのセッター。
Respondo.onUnreadChanged = (n) => setBadge(n);

// リンク／CTA をインターセプト。ホストが URL を自分で開いたら true を返す。
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

画面のトラッキング#

ナビゲーションのたびに現在の画面を報告すると、プロアクティブなティーザーとページ単位のターゲティングがそれに一致できるようになります。 null を渡すとクリアされます。変更のたびに、新しい画面に対してプロアクティブティーザーが再評価されます。

Dartdart

Respondo.setCurrentScreen('pricing');

次のステップ#

プッシュ通知と本人確認を追加しましょう。完全な API サーフェス、エンゲージメントサーフェス、トラブルシューティングは pub.dev のパッケージページにある Flutter SDK のスタートガイドで扱っています。