incento 개발자센터iOS 연동
Swift 네이티브 iOS 앱에서 인센토 위젯을 연동하는 가이드입니다.
이 가이드는 Swift로 작성된 네이티브 iOS 앱 기준입니다.
요구사항: iOS 15+, Swift 5.7+. 연동 전 필요한 조건은 SDK > 사전 준비에서 확인하세요.
실제 동작 예제는 github.com/OpenFormatKorea/incento-sdk-sample-apps를 참고해주세요.
연동 절차
파일 추가하기
IncentoService.swift 파일을 Xcode 프로젝트에 추가합니다. 외부 라이브러리 의존성은 없습니다.
Info.plist 설정: 위젯이 네트워크 요청을 하므로 ATS(App Transport Security)가 기본 허용 상태인지 확인하세요. 이미 인터넷을 사용하는 앱이라면 별도 설정이 필요하지 않습니다.
설치하기 — 이벤트 훅 등록
앱 실행 시 한 번만 boot()를 호출합니다. App 구조체의 init()에서 이벤트 훅을 등록합니다.
import SwiftUI
@main
struct MyApp: App {
init() {
IncentoService.shared.on("loginRequired") {
// 로그인 화면으로 이동
}
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}boot — SDK 초기화
// 비로그인 상태
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY")
// 로그인 상태
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY", userId: "회원_고유_ID")
// 기존 회원 — 회원 DB의 원래 가입 일시를 userCreatedAt로 함께 전달 (ISO 8601)
IncentoService.shared.boot(
apiKey: "inc_pk_YOUR_KEY",
userId: "회원_고유_ID",
userCreatedAt: "2023-03-15T09:30:00+09:00"
)SDK 설치 이전부터 존재하던 기존 회원은 userCreatedAt를 함께 전달하세요. 자세한 내용은
boot 파라미터 레퍼런스 — userCreatedAt을 참고하세요.
boot 파라미터
boot 개념과 동작 순서는 boot 파라미터 레퍼런스를 참고하세요. iOS는 아래 파라미터를 받습니다.
Prop
Type
커스텀 런처
기본 런처의 크기·위치·모양은 인센토 대시보드에서 설정한 값이 자동으로 반영됩니다. 이 스타일을 그대로 사용한다면 별도 작업이 필요 없습니다.
대시보드 스타일 대신 앱 내 임의의 버튼으로 위젯을 열고 싶을 때 커스텀 런처를 사용하세요.
핵심 패턴은 boot() 시 visible: false로 런처를 숨기고, 커스텀 런처에서 open()을
호출하는 것입니다.
open()·close()의 상세 동작과 사용 시점은 위젯 열기/닫기 레퍼런스를 참고하세요.
// 1. boot 시 런처 숨기기
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY", userId: userId, visible: false)
// 2. 커스텀 런처에서 위젯 열기
Button("혜택 받기") {
IncentoService.shared.open()
}로그인·로그아웃 등으로 shutdown → boot를 재호출할 때도 반드시 visible: false를
유지하세요. 빠뜨리면 런처가 다시 나타납니다.
func onLoginSuccess(userId: String) {
IncentoService.shared.shutdown()
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY", userId: userId, visible: false)
}
func onLogout() {
IncentoService.shared.shutdown()
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY", visible: false)
}로그인 후 위젯 자동 오픈
위젯 내 로그인 버튼을 눌렀을 때(loginRequired), 로그인 완료 후 위젯이 자동으로 열리게 하려면
autoOpen: true를 사용합니다.
// loginRequired 핸들러에서 플래그 저장 후 로그인 화면 이동
IncentoService.shared.on("loginRequired") {
UserDefaults.standard.set(true, forKey: "pendingIncentoOpen")
// 로그인 화면으로 이동
}
// 로그인 완료 후
func onLoginSuccess(userId: String) {
let shouldOpen = UserDefaults.standard.bool(forKey: "pendingIncentoOpen")
UserDefaults.standard.removeObject(forKey: "pendingIncentoOpen")
IncentoService.shared.shutdown()
IncentoService.shared.boot(
apiKey: "inc_pk_YOUR_KEY",
userId: userId,
visible: false,
autoOpen: shouldOpen,
debug: true,
)
}show / hide — 화면별 위젯 노출 제어
특정 화면에서만 위젯을 표시하고 싶을 때 사용합니다.
IncentoService.shared.show() // 런처 표시
IncentoService.shared.hide() // 런처 숨김 + 위젯이 열려있으면 닫음뷰의 .onAppear / .onDisappear modifier와 연결합니다.
// 마이페이지에서만 위젯 표시 예시
struct MyPageView: View {
var body: some View {
// ...
.onAppear {
IncentoService.shared.show()
}
.onDisappear {
IncentoService.shared.hide()
}
}
}경로 추적 — setPath
화면이 바뀔 때마다 setPath(_:)로 현재 화면 경로를 알려주면, 대시보드의 '경로별 리퍼럴 시도
횟수' 차트에서 어느 화면에서 공유가 일어났는지 집계됩니다. 초기 화면 경로는 boot의
pagePath로 지정합니다.
// boot 시 초기 화면 경로 지정
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY", userId: userId, pagePath: "/home")
// 화면 진입 시 경로 갱신 (.onAppear 등)
struct MyPageView: View {
var body: some View {
// ...
.onAppear {
IncentoService.shared.setPath("/mypage")
}
}
}웹과 같은 차트에 함께 집계되므로 웹 스타일(/screen-name)의 정규화된 저카디널리티(low cardinality) 경로를
넘기세요. 동적 id(/products/123)를 그대로 넣으면 경로가 폭발하므로 /products처럼
정규화합니다. 자세한 내용은 경로별 리퍼럴 시도 추적을
참고하세요.
이벤트 훅
이벤트 목록과 공통 규칙은 이벤트 훅 레퍼런스에 정리되어 있습니다. iOS에서는 앱 초기화 시 한 번만 등록합니다.
// loginRequired — 미등록 시 위젯 내 로그인 버튼이 동작하지 않습니다
IncentoService.shared.on("loginRequired") {
DispatchQueue.main.async {
// @State 또는 환경 객체로 로그인 화면 표시
}
}
IncentoService.shared.on("widgetOpen") {
print("위젯 열림")
}
IncentoService.shared.on("widgetClose") {
print("위젯 닫힘")
}shutdown — SDK 종료 및 인증 상태 변경
로그인·로그아웃 등 인증 상태가 바뀔 때 shutdown → boot 패턴을 사용합니다.
// 로그인 완료
func onLoginSuccess(userId: String) {
IncentoService.shared.shutdown()
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY", userId: userId)
}
// 로그아웃 완료
func onLogout() {
IncentoService.shared.shutdown()
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY")
}shutdown() 후 재boot() 시 현재 화면이 위젯 미표시 화면이라면 visible: false로
설정하세요.
IncentoService.shared.boot(apiKey: "inc_pk_YOUR_KEY", userId: userId, visible: false)