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';

초기화#

SDK가 여러분의 BuildContext 없이 채팅 시트를 열 수 있도록 Respondo.navigatorKey를 여러분의 MaterialApp에 바인딩하고, 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'),
          ),
        ),
      ),
    );
  }
}

모든 파사드 메서드는 멱등적이고, init 전에 호출해도 안전하며(버퍼링 후 재생), 여러분의 앱으로 예외를 던지지 않습니다.

사용자 식별#

기본적으로 모든 방문자는 익명입니다. 첫 실행 시 SDK는 안정적인 visitor_id를 생성해 로컬 스토리지에 보관하므로, 다시 방문한 사용자는 자신의 대화를 다시 찾습니다. 내장할 API 키는 없습니다 — 각 대화는 백엔드가 발급하고 메시지마다 앞으로 밀어주는 대화별 세션 토큰으로 보호되므로, 익명 방문자는 재인증할 필요가 전혀 없습니다.

사용자가 로그인하면 identify를 한 번 호출하세요. 이렇게 하면 실제 신원이 연결되어 여러 기기와 재설치에 걸쳐 대화 이력이 따라오고, Inbox의 대화 옆에 익명 방문자 대신 이름과 이메일이 표시됩니다.

userHash는 여러분의 백엔드가 에이전트의 identity_secret으로 계산하는 서명입니다 — HMAC-SHA256(secret, userId)(userId가 없으면 이메일), 소문자 16진수로 인코딩합니다. 이 시크릿은 신원이 진짜임을 증명하므로 오직 여러분의 백엔드에만 있어야 하고 앱에 절대 포함되어서는 안 됩니다. 전체 공식과 서버 측 예제는 신원 확인 페이지를 참고하세요.

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 시작 가이드에서 다룹니다.