Android / Kotlin

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

Android SDK는 android.* 의존성이 없는 순수 Kotlin/JVM JAR 입니다. Android 앱에서는 기존 SharedPreferences를 AbtoKeyValueStore에 연결해 설치별 device_id를 유지합니다.

설치

상단 Maven Central 배지에서 현재 공개 버전을 확인할 수 있습니다.

초기화

클라이언트에는 Event Key(ek-abto-…)만 사용합니다. Calling Key와 provider key는 앱에 넣지 마세요.

import android.content.Context
import app.abto.sdk.AbtoClient
import app.abto.sdk.AbtoConfig
import app.abto.sdk.AbtoEnvironment

val abto = AbtoClient(
  AbtoConfig(
    projectKey = "ek-abto-…",
    environment = AbtoEnvironment.PRODUCTION,
  ),
  store = SharedPreferencesStore(
    context.getSharedPreferences("abto", Context.MODE_PRIVATE),
  ),
)

abto.identify("user-123", "tenant-123")
abto.capture("checkout_completed", mapOf("order_id" to "order-123"))

두 번째 tenantId는 선택입니다. 로그아웃할 때는 abto.reset()으로 사용자와 tenant context를 지우고 새 device_id와 session을 만듭니다. 영속 저장소는 reset에서 새로 만든 device_id를 이후 앱 재시작에도 유지합니다.

Android 영속 저장소 연결

import android.content.SharedPreferences
import app.abto.sdk.AbtoKeyValueStore

class SharedPreferencesStore(
  private val preferences: SharedPreferences,
) : AbtoKeyValueStore {
  override fun get(key: String): String? = preferences.getString(key, null)

  override fun set(key: String, value: String) {
    preferences.edit().putString(key, value).apply()
  }
}

abto.deviceId를 관련 서버 요청의 x-abto-device-id로 전달하면 앱에서 관측한 행동과 Gateway의 모델 호출이 같은 흐름으로 연결됩니다.

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

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

val trace = abto.startLlmTrace(
  featureId = "resume.make",
  taskType = "draft_generation",
  surface = "editor",
)

trace.submitPrompt(prompt = promptText, language = "ko")

val backendResponse = callBackend(
  deviceId = abto.deviceId,
  featureId = trace.featureId,
  prompt = promptText,
)

trace.attachRequestId(backendResponse.headerFields)
trace.markResponseVisible(responseId = "resp-123", timeToVisibleMs = 1_200)
trace.captureOutcome(AbtoResponseInteraction.COPIED, responseId = "resp-123")

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

callBackend는 애플리케이션의 기존 네트워크 함수를 가리킵니다. Calling Key와 provider key를 앱에서 보내지 마세요. attachRequestId() 이후의 응답 event에는 Gateway 호출과 같은 $request_id가 실립니다.

앱 lifecycle에서 전송하기

앱이 background 로 전환되는 기존 lifecycle 지점에서 버퍼를 flush 하세요. 전송은 전용 daemon thread에서 처리하므로 UI thread를 블로킹하지 않습니다.

override fun onStop() {
  abto.flush()
  super.onStop()
}

전송에 실패한 이벤트는 내부 버퍼로 복귀해 다음 flush에서 재전송됩니다.

수집과 전송 한계

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 종료 후 복구되지 않으므로 background 진입 전에 flush 해야 합니다.

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