Flutter / Dart

클라이언트 SDK브라우저와 모바일 앱에서 실행 (Event Key)

Flutter SDK는 pub.dev에 공개돼 있고 Dart 3.4 이상을 요구합니다. 코어가 순수 Dart(dart:io)로 구현돼 Flutter의 iOS, Android, 데스크톱과 서버 환경을 지원합니다. Flutter Web에서는 브라우저용 JavaScript SDK를 사용하세요.

아래 영속 저장소 어댑터를 사용하는 Flutter 앱은 SDK 설치 후 의존성을 추가하세요.

flutter pub add shared_preferences

import 'package:abto/abto.dart';
import 'package:shared_preferences/shared_preferences.dart';

class SharedPreferencesStore implements AbtoKeyValueStore {
  SharedPreferencesStore(this._preferences);

  final SharedPreferences _preferences;

  @override
  String? get(String key) => _preferences.getString(key);

  @override
  void set(String key, String value) {
    _preferences.setString(key, value);
  }
}

final preferences = await SharedPreferences.getInstance();

final abto = AbtoClient(
  AbtoConfig(
    projectKey: 'ek-abto-…',
    endpoint: 'https://api.abto.app/v1/collect/events',
    environment: AbtoEnvironment.production,
  ),
  store: SharedPreferencesStore(preferences),
);

abto.identify('user-123', 'tenant-123');
abto.capture('checkout_completed', properties: {'order_id': 'order-123'});
await abto.flush();

클라이언트에는 Event Key(ek-abto-…)만 사용합니다. Calling Key와 provider key는 앱에 넣지 마세요. 두 번째 tenantId는 선택이며, 로그아웃할 때는 abto.reset()으로 사용자와 tenant context를 지우고 새 device_id와 session을 만듭니다.

위처럼 앱의 기존 shared_preferences를 AbtoKeyValueStore로 연결하면 앱 재시작 사이에 device_id가 유지되고, reset 시 새 값으로 교체됩니다. store를 생략하면 in-memory identity를 쓰므로 앱 재시작마다 device_id가 바뀝니다. abto.deviceId를 관련 서버 요청의 x-abto-device-id로 전송하면 앱 이벤트와 Gateway 호출이 연결됩니다. 전송에 실패한 이벤트는 내부 버퍼로 복귀해 다음 flush에서 재전송됩니다.

AI 요청과 응답 행동 연결하기

Mobile SDK는 모델이나 Gateway를 직접 호출하지 않습니다. deviceId와 featureId를 앱의 백엔드로 보내고, 백엔드가 Server SDK context로 검증·전달한 뒤 x-abto-request-id를 응답에 포함해야 합니다. 백엔드 쪽 연결은 Node / Server JavaScript와 Python에 있습니다.

final trace = abto.startLlmTrace(
  featureId: 'resume.make',
  taskType: 'draft_generation',
  surface: 'editor',
);

trace.submitPrompt(prompt: promptText, language: 'ko');

final backendResponse = await callBackend(
  deviceId: abto.deviceId,
  featureId: trace.featureId,
  prompt: promptText,
);

trace.attachRequestIdFromHeaders(backendResponse.headers);
trace.markResponseVisible(responseId: 'resp-123', timeToVisibleMs: 1200);
trace.captureOutcome(AbtoResponseInteraction.copied, responseId: 'resp-123');

AbtoResponseInteraction은 canonical 응답 행동 12개를 제공합니다. 기존 문자열 호출은 0.x 동안 source compatibility를 위해 유지하며 runtime 검증을 거칩니다. 지원하지 않는 문자열은 enqueue 전에 경고와 함께 제외되므로, 제품 고유 행동은 Custom Event로 기록하세요.

callBackend는 애플리케이션의 기존 네트워크 함수를 가리킵니다. attachRequestIdFromHeaders() 이후의 응답 event에는 Gateway 호출과 같은 $request_id가 실립니다.

수집과 전송 한계

capture()에 넣은 Custom Property는 Browser DOM masking을 거치지 않고 전달됩니다. Secret이나 원문 개인정보를 property에 넣지 마세요.
LLM trace의 prompt와 response helper는 원문 대신 길이 등 metadata_only 정보를 기록합니다.
Event 이름은 비어 있거나 $로 시작할 수 없고 UTF-16 기준 최대 200자입니다. $로 시작하는 Custom Property는 제외됩니다.
batchSize는 1~100이며 기본값은 20, 기본 flush 간격은 5초입니다.
Metric value는 유한한 수이면서 정수부 38자리·소수부 12자리 이하여야 하고, scale은 최대 16자입니다. 범위를 벗어난 metric만 제외하고 event는 보냅니다.
전송 버퍼는 메모리에 최대 1,000건을 유지하며, 넘치면 가장 오래된 것부터 버립니다. 408, 429, 5xx와 event별 retry를 최대 5회 또는 최초 적재 후 30분까지 재시도하고, 지수 백오프에 jitter를 더해 최대 2분까지 벌립니다.
전송 실패는 앱으로 throw되지 않습니다. 메모리 버퍼는 process 종료 후 복구되지 않으므로 app lifecycle의 background 지점에서 flush()를 호출하세요.

이벤트 이름과 Custom Property를 정하는 기준은 이벤트 설계에 있습니다.