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에서 추가하세요:
dependencies:
respondo_sdk: ^0.3.0import 'package:respondo_sdk/respondo_sdk.dart';초기화
SDK가 여러분의 BuildContext 없이 채팅 시트를 열 수 있도록 Respondo.navigatorKey를 여러분의 MaterialApp에 바인딩하고, 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();
// 파일 저장 디렉터리는 호스트 앱 플러그인에서 옵니다. SDK 자체는 순수하게 유지됩니다.
final dir = await getApplicationSupportDirectory();
await Respondo.init(
RespondoConfig(
agentId: '<agent-uuid>',
channelId: '<channel-uuid>', // Settings › Channels › Mobile SDK
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진수로 인코딩합니다. 이 시크릿은 신원이 진짜임을 증명하므로 오직 여러분의 백엔드에만 있어야 하고 앱에 절대 포함되어서는 안 됩니다. 전체 공식과 서버 측 예제는 신원 확인 페이지를 참고하세요.
// 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,
signedUpAt: session.signedUpAt,
));
// 3. 로그아웃 시: 세션을 폐기하고 새 익명 방문자를 시작합니다.
Respondo.reset();해시가 없거나 잘못되어도 아무것도 예외를 던지지 않습니다: 백엔드는 방문자를 조용히 익명으로 유지하고, 채팅은 계속 동작하며, 유효한 해시가 제공될 때까지 단지 기기 간 연결만 잃을 뿐입니다. 검증은 에이전트에 identity_secret이 설정되어 있을 때만 실행됩니다 — 개발 중에는 비워 두면 userId / 이메일이 있는 그대로 받아들여집니다.
관찰 가능한 값 및 콜백
모든 것이 브로드캐스트 Stream, 콜백 세터, 현재 값 게터로 제공됩니다.
// 읽지 않은 개수의 반응형 스트림(배지용).
Respondo.unreadCountStream.listen((n) => setBadge(n));
// 또는 콜백 세터.
Respondo.onUnreadChanged = (n) => setBadge(n);
// 링크/CTA를 가로챕니다. 호스트가 직접 URL을 열었다면 true를 반환합니다.
Respondo.onUrlRequested = (url) {
openInAppBrowser(url);
return true;
};화면 추적
능동적 티저와 페이지 수준 타기팅이 대조할 수 있도록 내비게이션마다 현재 화면을 보고하세요. null을 전달하면 지워지며, 변경될 때마다 새 화면에 대해 능동적 티저가 다시 평가됩니다.
같은 이름이 팝업 설문의 화면 규칙과 비교되므로, 번역된 제목 대신 «Checkout» 같은 고정 식별자를 사용하세요. 페이지 주소 규칙은 웹사이트에서만 적용됩니다.
Respondo.setCurrentScreen('pricing');코드에서 설문 열기
게시 중인 팝업 설문을 사용자가 어느 화면에 있든 즉시 엽니다. Show on, 화면 규칙, 화면 체류 시간, 트리거 이벤트, 대상은 무시됩니다. ID는 설문 편집기(Additional ways to share)에서 복사하세요. 사용자가 이미 응답한 설문은 다시 표시되지 않습니다.
Respondo.startSurvey('<survey-id>');다음 단계
푸시 알림과 신원 확인을 추가하세요. 전체 API 표면, 인게이지먼트 표면, 문제 해결은 pub.dev 패키지 페이지의 Flutter SDK 시작 가이드에서 다룹니다.