Class

`MomentSDK`

class MomentSDK {
	@JvmStatic
	fun getInstance(context: Context): MomentSDK

	// Lifecycle
	fun start(config: Config, callback: ResultCallback)
	fun stop(callback: ResultCallback)
	fun init(config: Config, callback: RestartResultCallback)
	fun isRunning(): Boolean

	// UI
	fun launchUI(config: Config, callback: ResultCallback)
	fun launchUI(config: Config, redirectTo: String, callback: ResultCallback)
	fun dismissUI(callback: ResultCallback)

	// User
	fun setUserId(userId: String, callback: ResultCallback)
	fun getUserId(): String
	fun setSendBubble(sendBubble: Boolean)

	// Consent
	fun getConsent(callback: CallbackWithResult<GetUserConsentResponse>)
	fun setConsent(request: SubmitUserConsentRequest, callback: CallbackWithResult<SubmitUserConsentResponse>)
	fun withdrawConsent(callback: ResultCallback)
	fun forgetUser(callback: ResultCallback)

	// Cashback
	fun listCashback(callback: ListCashbackResultCallback)
	fun goToCashback(businessId: String, callback: ResultCallback)

	// Project / API key
	fun setProjectId(projectId: String)
	fun setApiKey(apiKey: String)
	fun getProjectId(appContext: Context): String
	fun getApiKey(appContext: Context): String

	// Permission utils
	@JvmStatic
	fun isAppUsagePermissionGranted(context: Context): Boolean
	@JvmStatic
	fun isVpnPermissionGranted(context: Context): Boolean
	@JvmStatic
	fun isNotificationPermissionGranted(context: Context): Boolean
}

Full reference
```
@JvmStatic
fun getInstance(context: Context): MomentSDK
```
- Description
  - MomentSDK 싱글톤 인스턴스를 반환함. 최초 호출 시 인스턴스 생성, 이후 호출은 동일 인스턴스 재사용.
- Parameters
  - context
    - applicationContext 추출에 사용되는 Context.
- Returns
  - MomentSDK 싱글톤 인스턴스.
```
fun start(config: Config, callback: ResultCallback)
```
- Description
  - 서비스를 시작시키는 method로, 이 method가 성공적으로 완료된 후부터 사용자가 접속한 비즈니스를 인식할 수 있음.
- Parameters
  - config
    - 서비스를 시작할 때 필요한 설정값들.
  - callback
    - 서비스 시작 결과를 알려주는 callback.
- onFailure ErrorCode
  - ErrorCode.API_NOT_ACTIVATED - 현재 프로젝트에서 start가 deactivate된 경우
  - ErrorCode.APP_USAGE_PERMISSION_REQUIRED - x flavor에서 사용 통계 접근 권한이 없는 경우
  - ErrorCode.VPN_PERMISSION_REQUIRED - vpn flavor에서 VPN 권한이 없는 경우
  - ErrorCode.SERVICE_ALREADY_STARTING - start가 이미 진행 중이거나 서비스가 이미 실행 중인 경우
  - ErrorCode.EMPTY_USER_ID - standard campaign이 있는 프로젝트에서 userId가 설정되지 않은 경우
  - ErrorCode.INVALID_CONFIG - config의 필수 필드가 누락되었거나 잘못된 경우
  - ErrorCode.SERVICE_START_FAILED - foreground service 시작에 실패한 경우
  - ErrorCode.NETWORK_CONNECTION_REQUIRED - 인터넷 연결이 없는 경우
  - ErrorCode.AUTHENTICATION_FAILED - API 인증 실패 (HTTP 403)
  - ErrorCode.TOO_MANY_REQUESTS - API를 과도하게 호출한 경우 (HTTP 429)
  - ErrorCode.TEMPORARY_SERVER_ERROR - 페어리 서버에 일시적으로 문제가 생긴 경우
  - ErrorCode.ERROR_OCCURRED - 알 수 없는 에러가 발생한 경우
```
fun stop(callback: ResultCallback)
```
- Description
  - service를 중지시키는 method로, stop이 불린 후부터는 사용자가 접속한 비즈니스를 인식할 수 없음.
- Parameters
  - callback
    - 서비스 중지 결과를 알려주는 callback.
- onFailure ErrorCode
  - ErrorCode.SERVICE_STOP_FAILED - foreground service 중지에 실패한 경우
  - ErrorCode.ERROR_OCCURRED - 예상치 못한 에러
```
fun init(config: Config, callback: RestartResultCallback)
```
- Description
  - 이전에 start()를 호출한 적이 있으나 서비스가 꺼져 있는 경우 external 인식 서비스의 재시작을 시도함.
- Parameters
  - config
    - 서비스 재시작 시 사용할 설정값.
  - callback
    - 재시작 결과 callback.
- onSuccess RestartResultCode
  - RestartResultCode.SERVICE_SHOULD_NOT_BE_RUNNING - 서비스가 꺼져 있어야 하는 상태
  - RestartResultCode.SERVICE_ALREADY_RUNNING - service가 이미 실행 중
  - RestartResultCode.SERVICE_RESTARTED - service가 꺼져 있어서 start 시도 후 재시작 성공
- onFailure ErrorCode
  - ErrorCode.API_NOT_ACTIVATED - 현재 프로젝트에서 deactivate된 경우
  - MomentSDK.start에서 발생할 수 있는 모든 ErrorCode
```
fun isRunning(): Boolean
```
- Description
  - recognition service가 실행 중인지 확인. shouldDenyAll 킬스위치가 켜진 상태면 항상 false 반환.
- Returns
  - 서비스가 실행 중이면 true, 아니면 false.
```
fun launchUI(config: Config, callback: ResultCallback)
```
```
fun launchUI(config: Config, redirectTo: String, callback: ResultCallback)
```
- Description
  - SDK 내부에 구현된 Activity (FullWebViewActivity)를 실행하여 페어리 제공 웹뷰를 띄움.
  - 호출 시 config를 파일에 영속화 후 deviceConfig에서 받은 cashback main URL로 웹뷰 진입. redirectTo 가 주어지면 해당 path 로 redirect.
- Parameters
  - config
    - 서비스를 시작할 때 필요한 설정값.
  - redirectTo
    - 웹뷰 진입 후 redirect할 path. 비어 있으면 default page.
  - callback
    - 웹뷰 activity 실행 성공/실패 callback.
- onFailure ErrorCode
  - ErrorCode.API_NOT_ACTIVATED - 현재 프로젝트에서 deactivate된 경우
  - ErrorCode.EMPTY_USER_ID - userId가 설정되지 않은 경우
  - ErrorCode.INVALID_CONFIG - config의 필수 필드가 누락되었거나 잘못된 경우
  - ErrorCode.NETWORK_CONNECTION_REQUIRED - 인터넷 연결이 없는 경우
  - ErrorCode.AUTHENTICATION_FAILED - API 인증 실패
  - ErrorCode.TOO_MANY_REQUESTS - API를 과도하게 호출한 경우
  - ErrorCode.TEMPORARY_SERVER_ERROR - 페어리 서버에 일시적으로 문제가 생긴 경우
  - ErrorCode.ERROR_OCCURRED - 알 수 없는 에러
```
fun dismissUI(callback: ResultCallback)
```
- Description
  - 현재 활성 상태인 cashback 웹 UI(FullWebViewActivity)를 닫음.
- Parameters
  - callback
    - 닫기 결과 callback.
- onFailure ErrorCode
  - ErrorCode.ERROR_OCCURRED - 예상치 못한 에러로 UI 닫기 실패
```
fun setUserId(userId: String, callback: ResultCallback)
```
- Description
  - 사용자 식별에 사용되는 userId를 SDK 로컬에 설정함. MomentSDK.start 를 호출하기 전/후 모두 호출 가능.
  - userId를 빈 문자열로 입력하면 실패함.
- Parameters
  - userId
    - 사용자 식별에 사용되는 unique id. 빈 문자열 불가.
  - callback
    - 결과 callback.
- onFailure ErrorCode
  - ErrorCode.EMPTY_USER_ID - userId가 빈 문자열인 경우
  - ErrorCode.ERROR_OCCURRED - 예상치 못한 에러
```
fun getUserId(): String
```
- Description
  - setUserId 를 통해 저장된 userId를 반환.
- Returns
  - 저장된 userId. 없으면 빈 문자열.
```
fun setSendBubble(sendBubble: Boolean)
```
- Description
  - 버블 알림을 보낼지 일반 알림을 보낼지 설정함. 콜백 없는 fire-and-forget.
- Parameters
  - sendBubble
    - true면 버블 알림, false면 일반 알림.
```
fun listCashback(callback: ListCashbackResultCallback)
```
- Description
  - 현재 project에서 지원하는 cashback program 리스트를 callback으로 전달.
- Parameters
  - callback
    - cashback 리스트 또는 실패 사유를 받는 callback.
- onFailure ErrorCode
  - ErrorCode.API_NOT_ACTIVATED - 현재 프로젝트에서 listCashback이 deactivate된 경우
  - ErrorCode.NETWORK_CONNECTION_REQUIRED - 인터넷 연결이 없는 경우
  - ErrorCode.AUTHENTICATION_FAILED - API 인증 실패
  - ErrorCode.TOO_MANY_REQUESTS - API를 과도하게 호출한 경우
  - ErrorCode.TEMPORARY_SERVER_ERROR - 페어리 서버에 일시적으로 문제가 생긴 경우
  - ErrorCode.ERROR_OCCURRED - 알 수 없는 에러
```
fun goToCashback(businessId: String, callback: ResultCallback)
```
- Description
  - 사용자가 선택한 캐시백의 businessId를 받아 해당 캐시백을 받을 수 있는 웹사이트/앱을 FullWebViewActivity 로 띄움.
- Parameters
  - businessId
    - 사용자가 클릭한 캐시백의 business id.
  - callback
    - 실패/성공 결과 callback.
- onFailure ErrorCode
  - ErrorCode.API_NOT_ACTIVATED - 현재 프로젝트에서 deactivate된 경우
  - ErrorCode.EMPTY_CASHBACK_BUSINESS_ID - businessId가 빈 문자열인 경우
  - ErrorCode.EMPTY_USER_ID - userId가 설정되지 않은 경우
  - ErrorCode.NETWORK_CONNECTION_REQUIRED - 인터넷 연결이 없는 경우
  - ErrorCode.AUTHENTICATION_FAILED - API 인증 실패
  - ErrorCode.TOO_MANY_REQUESTS - API를 과도하게 호출한 경우
  - ErrorCode.TEMPORARY_SERVER_ERROR - 페어리 서버에 일시적으로 문제가 생긴 경우
  - ErrorCode.ERROR_OCCURRED - 알 수 없는 에러
```
fun setConsent(request: SubmitUserConsentRequest, callback: CallbackWithResult<SubmitUserConsentResponse>)
```
- Description
  - 현재 userId의 사용자 동의 상태를 생성하거나 업데이트하는 method (upsert).
  - request 에 명시된 모든 필드 값이 서버에 그대로 저장되므로 5개 필드 전부 를 지정해야 함.
  - 호출 성공 시 서버에 저장된 최종 동의 상태가 onSuccess callback으로 반환됨.
- Parameters
  - request
    - 저장할 동의 정보를 담은 SubmitUserConsentRequest 객체.
  - callback
    - 결과 callback.
- onFailure ErrorCode
  - ErrorCode.API_NOT_ACTIVATED - 현재 프로젝트에서 deactivate된 경우
  - ErrorCode.NETWORK_CONNECTION_REQUIRED - 인터넷 연결이 없는 경우
  - ErrorCode.AUTHENTICATION_FAILED - API 인증 실패
  - ErrorCode.TOO_MANY_REQUESTS - API를 과도하게 호출한 경우
  - ErrorCode.TEMPORARY_SERVER_ERROR - 페어리 서버에 일시적으로 문제가 생긴 경우
  - ErrorCode.ERROR_OCCURRED - 알 수 없는 에러
```
fun getConsent(callback: CallbackWithResult<GetUserConsentResponse>)
```
- Description
  - 현재 userId에 저장된 사용자 동의 상태를 서버에서 조회.
  - onSuccess callback의 result 로 GetUserConsentResponse 객체가 전달됨.
- Parameters
  - callback
    - 결과 callback. onSuccess(result: GetUserConsentResponse) 로 현재 동의 상태 전달.
- onFailure ErrorCode
  - ErrorCode.API_NOT_ACTIVATED - 현재 프로젝트에서 deactivate된 경우
  - ErrorCode.NETWORK_CONNECTION_REQUIRED - 인터넷 연결이 없는 경우
  - ErrorCode.AUTHENTICATION_FAILED - API 인증 실패
  - ErrorCode.TOO_MANY_REQUESTS - API를 과도하게 호출한 경우
  - ErrorCode.TEMPORARY_SERVER_ERROR - 페어리 서버에 일시적으로 문제가 생긴 경우
  - ErrorCode.ERROR_OCCURRED - 알 수 없는 에러
```
fun withdrawConsent(callback: ResultCallback)
```
- Description
  - 현재 userId의 모든 사용자 동의를 철회. 모든 동의 필드를 false 로 설정하는 것과 동일한 효과.
  - 약관 동의를 포함한 모든 필드가 철회되므로 부분 철회는 setConsent 를 대신 사용할 것.
- Parameters
  - callback
    - 결과 callback.
- onFailure ErrorCode
  - ErrorCode.API_NOT_ACTIVATED - 현재 프로젝트에서 deactivate된 경우
  - ErrorCode.NETWORK_CONNECTION_REQUIRED - 인터넷 연결이 없는 경우
  - ErrorCode.AUTHENTICATION_FAILED - API 인증 실패
  - ErrorCode.TOO_MANY_REQUESTS - API를 과도하게 호출한 경우
  - ErrorCode.TEMPORARY_SERVER_ERROR - 페어리 서버에 일시적으로 문제가 생긴 경우
  - ErrorCode.ERROR_OCCURRED - 알 수 없는 에러
```
fun forgetUser(callback: ResultCallback)
```
- Description
  - 호스트 앱 또는 웹페이지가 자체 backend로 탈퇴 처리한 후 device-local SDK 흔적을 제거하기 위한 post-withdrawal cleanup method. 탈퇴 자체는 수행하지 않음.
  - 순서: 1) 서비스 실행 중이면 stop (실패 시 fatal — callback 실패로 전달), 2) SharedPreferences clear, 3) in-memory state 초기화, 4) SDK 파일 wipe, 5) 성공 보고.
  - 호출 후 SDK 재사용 전 다시 setUserId + init 호출 필요.
- Parameters
  - callback
    - 결과 callback. stop 단계 실패 시에만 onFailure 호출 (나머지는 best-effort).
- onFailure ErrorCode
  - ErrorCode.SERVICE_STOP_FAILED - 서비스 중지에 실패한 경우 (cleanup 진행 안 됨)
  - ErrorCode.ERROR_OCCURRED - 알 수 없는 에러
```
fun setProjectId(projectId: String)
```
- Description
  - SDK의 project ID를 설정함.
- Parameters
  - projectId
    - 설정할 project ID 문자열.
```
fun setApiKey(apiKey: String)
```
- Description
  - SDK의 API key를 설정함.
- Parameters
  - apiKey
    - 설정할 API key 문자열.
```
fun getProjectId(appContext: Context): String
```
- Description
  - 현재 SDK에 설정된 project ID를 반환.
- Parameters
  - appContext
    - application context.
- Returns
  - 현재 project ID. 없으면 빈 문자열.
```
fun getApiKey(appContext: Context): String
```
- Description
  - 현재 SDK에 설정된 API key를 반환.
- Parameters
  - appContext
    - application context.
- Returns
  - 현재 API key. 없으면 빈 문자열.
```
@JvmStatic
fun isAppUsagePermissionGranted(context: Context): Boolean
```
- Description
  - 호스트 앱이 App Usage 권한(PACKAGE_USAGE_STATS)을 갖고 있는지 알려주는 util method.
- Parameters
  - context
    - 권한 확인에 사용되는 null이 아닌 context.
- Returns
  - 권한이 있으면 true, 아니면 false.
```
@JvmStatic
fun isVpnPermissionGranted(context: Context): Boolean
```
- Description
  - VPN 권한 상태를 확인하는 util method.
- Parameters
  - context
    - 권한 확인에 사용되는 null이 아닌 context.
- Returns
  - 권한이 있으면 true, 아니면 false.
```
@JvmStatic
fun isNotificationPermissionGranted(context: Context): Boolean
```
- Description
  - 앱에서 사용자에게 알림을 보낼 수 있는지를 알려주는 util method.
  - API level ≥ 33: notification permission이 있는지 / API level < 33: notification을 보낼 수 있는지.
- Parameters
  - context
    - 권한 확인에 사용되는 null이 아닌 context.
- Returns
  - 알림 표시 가능하면 true, 아니면 false.

`MomentSDK.Config`

class Config : Serializable {
	constructor()
	constructor(appContext: Context)

	// Notification config
	fun notificationChannelId(notificationChannelId: String): Config
	fun notificationId(notificationId: Int): Config
	fun notificationIconResId(notificationIconResId: Int): Config

	// Service notification config
	fun serviceNotificationChannelId(serviceNotificationChannelId: String): Config
	fun serviceNotificationId(serviceNotificationId: Int): Config
	fun serviceNotificationIconResId(serviceNotificationIconResId: Int): Config
	fun serviceNotificationIconColorInt(@ColorInt serviceNotificationIconColorInt: Int): Config
	fun serviceNotificationTitle(serviceNotificationTitle: String): Config
	fun serviceNotificationText(serviceNotificationText: String): Config
	fun serviceNotificationLinkUrl(serviceNotificationLinkUrl: String): Config

	// BETA
	fun hideServiceNotification(hideServiceNotification: Boolean): Config
}

Config 클래스는 builder pattern으로 인스턴스를 구성합니다. 각 setter 메서드는 Config 자기 자신을 반환하므로 chaining 가능합니다. <aside>
❗ notificationChannelId로 넘겨주는 알림 채널을 생성할 때, importance를 IMPORTANCE_HIGH 이상으로 설정해주셔야 합니다. (그래야 사용자에게 heads-up 알림으로 알림이 나가게 됩니다.) </aside>

`MomentException`

class MomentException(val errorCode: ErrorCode, errorMessage: String) : Exception(errorMessage) {
	constructor(errorCode: ErrorCode, context: Context)

	val errorCode: ErrorCode
	override val message: String
}

Enum

`ErrorCode`

enum class ErrorCode {
	API_NOT_ACTIVATED,
	APP_USAGE_PERMISSION_REQUIRED,
	VPN_PERMISSION_REQUIRED,
	NETWORK_CONNECTION_REQUIRED,
	SERVICE_START_FAILED,
	SERVICE_STOP_FAILED,
	SERVICE_ALREADY_STARTING,
	PROJECT_ID_REQUIRED,
	API_KEY_REQUIRED,
	GET_SIGNING_KEY_FAILED,
	AUTHENTICATION_FAILED,
	EMPTY_USER_ID,
	EMPTY_CASHBACK_BUSINESS_ID,
	INVALID_CONFIG,
	CASHBACK_NOT_FOUND,
	TOO_MANY_REQUESTS,
	TEMPORARY_SERVER_ERROR,
	ERROR_OCCURRED,
	EMPTY_DEVICE_TOKEN,
	PUSH_NOT_SUPPORTED,
}

Full reference
- API_NOT_ACTIVATED — 현재 프로젝트가 서버 kill-switch 또는 device 상태(rooted)에 의해 deactivate된 경우.
- APP_USAGE_PERMISSION_REQUIRED — x flavor에서 PACKAGE_USAGE_STATS 권한이 없는 경우.
- VPN_PERMISSION_REQUIRED — vpn flavor에서 VPN 권한이 없는 경우.
- NETWORK_CONNECTION_REQUIRED — 인터넷 연결 없음 또는 timeout.
- SERVICE_START_FAILED — foreground service 시작에 실패한 경우.
- SERVICE_STOP_FAILED — foreground service 중지에 실패한 경우.
- SERVICE_ALREADY_STARTING — start가 이미 진행 중이거나 서비스가 실행 중인 경우.
- PROJECT_ID_REQUIRED — projectId가 설정되지 않은 경우.
- API_KEY_REQUIRED — apiKey가 설정되지 않은 경우.
- GET_SIGNING_KEY_FAILED — signing key 조회에 실패한 경우.
- AUTHENTICATION_FAILED — API 인증 실패 (HTTP 403).
- EMPTY_USER_ID — userId가 설정되지 않거나 빈 문자열인 경우.
- EMPTY_CASHBACK_BUSINESS_ID — cashback businessId가 빈 문자열인 경우.
- INVALID_CONFIG — Config 의 필수 필드가 누락되었거나 잘못된 경우.
- CASHBACK_NOT_FOUND — 주어진 businessId의 cashback이 존재하지 않는 경우.
- TOO_MANY_REQUESTS — API를 과도하게 호출한 경우 (HTTP 429).
- TEMPORARY_SERVER_ERROR — 서버 일시 오류 (HTTP 502/503/504).
- ERROR_OCCURRED — 알 수 없는 / 분류되지 않은 에러.
- EMPTY_DEVICE_TOKEN — push device token이 비어 있는 경우.
- PUSH_NOT_SUPPORTED — push 미지원 빌드 또는 환경.

`MomentSDK.RestartResultCode`

enum class RestartResultCode {
	SERVICE_SHOULD_NOT_BE_RUNNING,
	SERVICE_ALREADY_RUNNING,
	SERVICE_RESTARTED,
}

Callback

`MomentSDK.CallbackWithResult<T>`

interface CallbackWithResult<T> {
	fun onSuccess(result: T)
	fun onFailure(exception: MomentException)
}

`MomentSDK.ResultCallback`

interface ResultCallback {
	fun onSuccess()
	fun onFailure(exception: MomentException)
}

`MomentSDK.RestartResultCallback`

interface RestartResultCallback {
	fun onSuccess(resultCode: RestartResultCode)
	fun onFailure(exception: MomentException)
}

`MomentSDK.ListCashbackResultCallback`

interface ListCashbackResultCallback {
	fun onSuccess(cashbackPrograms: List<CashbackProgram>)
	fun onFailure(exception: MomentException)
}

Data

`GetUserConsentResponse`

class GetUserConsentResponse {
	val agreeTermsOfService: Boolean
	val agreePersonalInfoUseAndSharing: Boolean
	val agreeMarketingInfoReceive: Boolean
	val agreeMarketingPersonalInfoUseAndSharing: Boolean
	val agreeNighttimeNotification: Boolean
}

getConsent 호출의 onSuccess callback으로 전달되는 동의 상태 응답 객체.

`SubmitUserConsentRequest`

class SubmitUserConsentRequest {
	val agreeTermsOfService: Boolean
	val agreePersonalInfoUseAndSharing: Boolean
	val agreeMarketingInfoReceive: Boolean
	val agreeMarketingPersonalInfoUseAndSharing: Boolean
	val agreeNighttimeNotification: Boolean
}

객체는 다음과 같이 builder를 통해 생성합니다.

val request = SubmitUserConsentRequest.newBuilder()
	.setAgreeTermsOfService(true)
	.setAgreePersonalInfoUseAndSharing(true)
	.setAgreeMarketingInfoReceive(false)
	.setAgreeMarketingPersonalInfoUseAndSharing(false)
	.setAgreeNighttimeNotification(true)
	.build()

`SubmitUserConsentResponse`

class SubmitUserConsentResponse {
	val agreeTermsOfService: Boolean
	val agreePersonalInfoUseAndSharing: Boolean
	val agreeMarketingInfoReceive: Boolean
	val agreeMarketingPersonalInfoUseAndSharing: Boolean
	val agreeNighttimeNotification: Boolean
}

`CashbackProgram`

class CashbackProgram {
	val businessId: String
	val businessName: String
	val businessImageUrl: String
	val url: String
	val programName: String
	val productsList: List<CashbackProduct>
}

​Class

​MomentSDK

​MomentSDK.Config

​MomentException

​Enum

​ErrorCode

​MomentSDK.RestartResultCode

​Callback

​MomentSDK.CallbackWithResult<T>

​MomentSDK.ResultCallback

​MomentSDK.RestartResultCallback

​MomentSDK.ListCashbackResultCallback

​Data

​GetUserConsentResponse

​SubmitUserConsentRequest

​SubmitUserConsentResponse

​CashbackProgram