incento 개발자센터Android 연동
Kotlin 네이티브 Android 앱에서 인센토 위젯을 연동하는 가이드입니다.
이 가이드는 Kotlin으로 작성된 네이티브 Android 앱 기준입니다.
요구사항: Android API 28+, Kotlin 1.7+. 연동 전 필요한 조건은 SDK > 사전 준비에서 확인하세요.
실제 동작 예제는 github.com/OpenFormatKorea/incento-sdk-sample-apps를 참고해주세요.
연동 절차
파일 추가하기
IncentoService.kt 파일을 프로젝트의 패키지 경로에 추가합니다. 파일 상단의 package 선언을
프로젝트에 맞게 수정하세요. 외부 라이브러리 의존성은 없습니다.
AndroidManifest.xml에 인터넷 권한을 추가합니다 (이미 있다면 생략).
<uses-permission android:name="android.permission.INTERNET" />설치하기 — 이벤트 훅 등록
앱 실행 시 한 번만 boot()를 호출합니다. Application 클래스 또는 메인 Activity의
onCreate에서 이벤트 훅을 등록합니다.
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
IncentoService.on("loginRequired") {
// 로그인 화면으로 이동
// startActivity(Intent(this, LoginActivity::class.java))
}
}
}boot — SDK 초기화
// 비로그인 상태
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY")
// 로그인 상태
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY", userId = "회원_고유_ID")
// 기존 회원 — 회원 DB의 원래 가입 일시를 userCreatedAt로 함께 전달 (ISO 8601)
IncentoService.boot(
activity = this,
apiKey = "inc_pk_YOUR_KEY",
userId = "회원_고유_ID",
userCreatedAt = "2023-03-15T09:30:00+09:00",
)SDK 설치 이전부터 존재하던 기존 회원은 userCreatedAt를 함께 전달하세요. 자세한 내용은
boot 파라미터 레퍼런스 — userCreatedAt을 참고하세요.
boot 파라미터
boot 개념과 동작 순서는 boot 파라미터 레퍼런스를 참고하세요. Android는 아래 파라미터를 받습니다.
Prop
Type
커스텀 런처
기본 런처의 크기·위치·모양은 인센토 대시보드에서 설정한 값이 자동으로 반영됩니다. 이 스타일을 그대로 사용한다면 별도 작업이 필요 없습니다.
대시보드 스타일 대신 앱 내 임의의 버튼으로 위젯을 열고 싶을 때 커스텀 런처를 사용하세요.
핵심 패턴은 boot() 시 visible = false로 런처를 숨기고, 커스텀 런처에서 open()을
호출하는 것입니다.
open()·close()의 상세 동작과 사용 시점은 위젯 열기/닫기 레퍼런스를 참고하세요.
// boot 시 런처 숨기기
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY", userId = userId, visible = false)binding.benefitButton.setOnClickListener {
IncentoService.open()
}Button(onClick = { IncentoService.open() }) {
Text("혜택 받기")
}로그인·로그아웃 등으로 shutdown → boot를 재호출할 때도 반드시 visible = false를
유지하세요. 빠뜨리면 런처가 다시 나타납니다.
fun onLoginSuccess(userId: String) {
IncentoService.shutdown()
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY", userId = userId, visible = false)
}
fun onLogout() {
IncentoService.shutdown()
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY", visible = false)
}로그인 후 위젯 자동 오픈
위젯 내 로그인 버튼을 눌렀을 때(loginRequired), 로그인 완료 후 위젯이 자동으로 열리게 하려면
autoOpen = true를 사용합니다.
// loginRequired 핸들러에서 플래그 저장 후 로그인 화면 이동
IncentoService.on("loginRequired") {
getSharedPreferences("incento", Context.MODE_PRIVATE)
.edit().putBoolean("pendingOpen", true).apply()
startActivity(Intent(this, LoginActivity::class.java))
}
// 로그인 완료 후
fun onLoginSuccess(userId: String) {
val prefs = getSharedPreferences("incento", Context.MODE_PRIVATE)
val shouldOpen = prefs.getBoolean("pendingOpen", false)
prefs.edit().remove("pendingOpen").apply()
IncentoService.shutdown()
IncentoService.boot(
activity = this,
apiKey = "inc_pk_YOUR_KEY",
userId = userId,
visible = false,
autoOpen = shouldOpen,
debug = true,
)
}show / hide — 화면별 위젯 노출 제어
특정 화면에서만 위젯을 표시하고 싶을 때 사용합니다.
IncentoService.show() // 런처 표시
IncentoService.hide() // 런처 숨김 + 위젯이 열려있으면 닫음Activity 또는 Fragment 생명주기와 연결합니다.
// 마이페이지에서만 위젯 표시 예시
class MyPageFragment : Fragment() {
override fun onResume() {
super.onResume()
IncentoService.show()
}
override fun onPause() {
super.onPause()
IncentoService.hide()
}
}경로 추적 — setPath
화면이 바뀔 때마다 setPath(...)로 현재 화면 경로를 알려주면, 대시보드의 '경로별 리퍼럴 시도
횟수' 차트에서 어느 화면에서 공유가 일어났는지 집계됩니다. 초기 화면 경로는 boot의
pagePath로 지정합니다.
// boot 시 초기 화면 경로 지정
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY", userId = userId, pagePath = "/home")
// 화면 진입 시 경로 갱신 (onResume 등)
class MyPageFragment : Fragment() {
override fun onResume() {
super.onResume()
IncentoService.setPath("/mypage")
}
}웹과 같은 차트에 함께 집계되므로 웹 스타일(/screen-name)의 정규화된 저카디널리티(low cardinality) 경로를
넘기세요. 동적 id(/products/123)를 그대로 넣으면 경로가 폭발하므로 /products처럼
정규화합니다. 자세한 내용은 경로별 리퍼럴 시도 추적을
참고하세요.
이벤트 훅
이벤트 목록과 공통 규칙은 이벤트 훅 레퍼런스에 정리되어 있습니다. Android에서는 앱 초기화 시 한 번만 등록합니다.
// loginRequired — 미등록 시 위젯 내 로그인 버튼이 동작하지 않습니다
IncentoService.on("loginRequired") {
runOnUiThread {
startActivity(Intent(this, LoginActivity::class.java))
}
}
IncentoService.on("widgetOpen") {
Log.d("Incento", "위젯 열림")
}
IncentoService.on("widgetClose") {
Log.d("Incento", "위젯 닫힘")
}shutdown — SDK 종료 및 인증 상태 변경
로그인·로그아웃 등 인증 상태가 바뀔 때 shutdown → boot 패턴을 사용합니다.
// 로그인 완료
fun onLoginSuccess(userId: String) {
IncentoService.shutdown()
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY", userId = userId)
}
// 로그아웃 완료
fun onLogout() {
IncentoService.shutdown()
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY")
}shutdown() 후 재boot() 시 현재 화면이 위젯 미표시 화면이라면 visible = false로
설정하세요.
IncentoService.boot(activity = this, apiKey = "inc_pk_YOUR_KEY", userId = userId, visible = false)