iOS / Swift

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

iOS·macOS SDK는 공개 Swift Package Manager 저장소에서 설치합니다. iOS 14 이상과 macOS 12 이상을 지원합니다.

Xcode의 File 메뉴에서 Add Package Dependencies… 를 열고 https://github.com/greedy-co/abto-sdk를 추가하세요.

다른 Swift 패키지에서는 상단에 표시된 현재 버전으로 .package(...) 를 선언합니다.

import AbtoApp

let abto = try AbtoClient(
  projectKey: "ek-abto-…",
  endpoint: "https://api.abto.app/v1/collect/events",
  environment: .production,
)
abto.identify(userId: "user-123", tenantId: "tenant-123")
abto.capture("checkout_completed", properties: ["order_id": "order-123"])
abto.flush()

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

기본 UserDefaults 저장소는 앱 재시작 사이에 device_id를 유지하고, reset 시 새 값으로 교체합니다. 앱의 기존 저장소를 쓰려면 AbtoKeyValueStore 구현을 전달합니다. abto.deviceId를 관련 서버 요청의 x-abto-device-id로 전송하면 앱 이벤트와 Gateway 호출이 연결됩니다.

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

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

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

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

let backendResponse = try await callBackend(
    deviceId: abto.deviceId,
    featureId: trace.featureId,
    prompt: promptText
)

trace.attachRequestId(fromHeaders: backendResponse.allHeaderFields)
trace.markResponseVisible(responseId: "resp-123", timeToVisibleMs: 1_200)
trace.captureOutcome(.copied, responseId: "resp-123")

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

callBackend는 애플리케이션의 기존 네트워크 함수를 가리킵니다. attachRequestId() 이후의 응답 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 종료 후 복구되지 않으므로 앱이 background 로 전환되기 전에 flush() 를 호출하세요.

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