이 문서는 Partner Android SDK(Kakao Partner SDK for Android)를 사용한 카카오 로그인 모듈 사용 방법을 안내합니다.

사용자에게 카카오톡 앱으로 로그인을 요청합니다.

자세한 안내와 예제는 카카오톡으로 로그인을 참고합니다.

사용자에게 카카오계정 정보 입력으로 로그인을 요청합니다.

자세한 안내와 예제는 카카오계정으로 로그인을 참고합니다.

사용자가 [카카오톡으로 로그인]과 [카카오계정으로 로그인] 둘 중 원하는 방식을 선택할 수 있는 로그인 선택 화면를 제공합니다. 개발자는 별도의 UI 구현 없이 간편하게 통합 로그인을 구현할 수 있습니다.

자세한 안내와 예제는 카카오 로그인 방법 선택을 참고합니다.

카카오 로그인 완료 시 발급받은 액세스 토큰으로 사용자 정보 조회를 요청해 회원 가입에 필요한 사용자 정보를 제공받을 수 있습니다. 일부 사용자 정보는 동의항목 설정 및 사용자 동의가 필요합니다.

카카오 로그인 시 사용할 수 있는 추가 기능을 안내합니다.

사용자가 첫 카카오 로그인 시 동의 화면에서 동의하지 않았지만, 서비스 이용 중 추가로 동의해야 하는 항목을 동적으로 동의 요청하는 기능입니다.

자세한 안내와 예제는 동의항목 추가 동의 요청을 참고합니다.

카카오싱크 서비스에서 동의하지 않은 약관을 선택해 사용자에게 동의 요청하는 기능입니다.

자세한 안내와 예제는 서비스 약관 선택해 동의 요청을 참고합니다.

카카오싱크 간편가입 화면에서 상황에 따라 카카오톡 채널을 선택해 노출하는 기능입니다.

자세한 안내와 예제는 채널 선택해 동의 요청을 참고합니다.

동의항목 추가 동의 요청 시, scope 파라미터에 openid 값을 추가 전달해야 합니다.

자세한 안내와 예제는 동의항목 추가 동의 요청을 참고합니다.

기존 로그인 여부와 상관없이 로그인은 서비스의 필요에 따라 사용자 인증을 다시 수행하고자 할 때 사용하는 추가 기능입니다.

자세한 안내와 예제는 기존 로그인 여부와 상관없이 로그인을 참고합니다.

카카오계정 로그인 화면의 ID란에 login_hint 파라미터 값을 자동 입력하는 기능입니다.

자세한 안내와 예제는 로그인 힌트를 참고합니다.

사용자에게 카카오계정 신규 가입 후 로그인하도록 하기 위해 사용하는 기능입니다.

자세한 안내와 예제는 카카오계정 가입 후 로그인을 참고합니다.

사용자에게 카카오계정 신규 가입 후 로그인하도록 하기 위해 사용하는 기능입니다.

자세한 안내와 예제는 카카오계정 간편로그인을 참고합니다.

SSO(Single Sign On)는 카카오톡에 이미 로그인된 세션을 활용하여, 별도의 앱 전환이나 UI 노출 없이 사용자를 서비스에 로그인시킬 수 있는 기능입니다.

사용 방법을 확인한 후, 아래와 같이 구현합니다.

1. SSO 가능 여부를 확인합니다.
2. SSO 인증을 요청합니다. 아래 두 가지 방법 중 하나를 선택할 수 있습니다.
   • 카카오톡 사용자 목록을 조회한 후, 사용자 ID를 지정해 SSO 인증을 요청합니다.
   • 카카오톡 활성화 계정으로 SSO 요청

SSO 기능은 카카오 통합서비스약관에 동의한 통합계정 사용자만 이용할 수 있습니다. 사용자가 통합서비스 약관에 동의하지 않았다면, SSO 토큰이 발급되지 않습니다.

따라서 통합서비스 약관을 사용하는 서비스는 SSO 토큰 발급 시 아래와 같이 처리해야 합니다.

• 사용자 ID를 지정해 SSO 요청 시, 카카오톡 사용자 조회 결과 중 isUnifiedTermsAgreed 프로퍼티를 확인해 통합계정 사용자인지 확인 후 처리해야 합니다.
• 카카오톡 활성화 계정으로 SSO를 요청 시, useUnifiedTerms 파라미터를 true로 설정해야 합니다. 선택된 계정이 통합 서비스 약관에 동의하지 않았다면 에러가 발생합니다.

사용자의 기기에서 SSO 기능을 사용할 수 있는지 확인합니다.

사용자의 카카오톡 로그인 여부와 AccountManager에 계정 등록 여부와 상관 없이, 사용자의 디바이스에 설치된 카카오톡이 SSO를 지원하는 버전이라면 true를 반환합니다.

AccountManager는 Android OS에서 여러 계정 정보를 통합 관리하기 위해 제공하는 시스템 서비스입니다. 동일한 기기 내 여러 앱에서 계정 데이터(SDK 토큰 등)를 공유할 수 있도록 지원합니다.

카카오 SSO는 AccountManager를 활용해 여러 앱 간에 로그인 세션을 공유합니다. AccountManager에 저장된 SSO 세션 토큰이 삭제돼도, 카카오톡이나 SSO 연동된 서비스 앱은 로그아웃되지 않습니다.

자세한 내용은 Android 공식 문서(AccountManager)를 참고합니다.

UserApiClient.instance.isSsoAvailable(context)

getTalkUsers()를 호출해 AccountManager에 저장된 카카오톡 계정 목록을 조회합니다. 계정 정보에는 사용자 ID, 이메일, 닉네임, 프로필 이미지, 통합 약관 동의 여부가 포함됩니다.

AccountManager에 등록된 계정이 없는 경우, 카카오톡에 로그인된 계정을 AccountManager에 등록한 뒤 반환합니다. 카카오톡에 로그인되어 있지 않은 경우 빈 리스트를 반환합니다.

서비스가 직접 구현한 SSO 로그인 화면을 사용할 경우 호출합니다. SSO 로그인 화면에서 사용자가 원하는 계정을 선택하고, 해당 계정으로 SSO 로그인을 완료하는 플로우에서 사용할 수 있습니다.

UserApiClient.instance.getTalkUsers(activity()) { users, error ->
    if (error != null) {
        Log.e(TAG, "카카오톡 사용자 조회 실패", error)
    } else if (users.isNullOrEmpty()) {
        Log.i(TAG, "SSO 가능한 카카오톡 사용자가 없습니다")
    } else {
        Log.i(TAG, "SSO 가능한 카카오톡 사용자 $users")
    }
}

사용자 ID를 지정해 SSO 인증을 하거나, 카카오톡 활성화 계정으로 SSO 인증할 수 있습니다.

성공 시, 지정한 사용자의 토큰이 반환됩니다.

서비스에서 직접 UI를 구현해 SSO 인증을 하려면, 사용자 ID를 지정해 요청해야 합니다. 카카오톡 사용자를 조회해 얻은 사용자 ID를 sso() 호출 시 함께 전달합니다.

// 사용자가 선택한 계정의 카카오톡 ID로 SSO 인증
UserApiClient.instance.sso(activity, user.id) { token, error ->
    if (error != null) {
        Log.e(TAG, "SSO 실패", error)
    } else if (token != null) {
        Log.i(TAG, "SSO 성공 ${token.accessToken}")
    }
}

현재 카카오톡에 로그인된 계정으로 SSO 인증을 진행합니다. sso() 호출 시, SsoLoginType을 active로 지정합니다.

// 현재 카카오톡에 로그인된 계정으로 SSO 인증
UserApiClient.instance.sso(
    activity = activity,
    type = SsoLoginType.ACTIVE,
) { token, error ->
    if (error != null) {
        Log.e(TAG, "SSO 실패", error)
    } else if (token != null) {
        Log.i(TAG, "SSO 성공 ${token.accessToken}")
    }
}

앱 실행 시 사용자가 앞서 로그인으로 발급받은 토큰이 있는지 확인합니다.

자세한 안내와 예제는 토큰 존재 여부 조회를 참고합니다.

Partner Android SDK에 저장된 토큰을 폐기하여 사용자를 로그아웃 처리합니다.

자세한 안내와 예제는 로그아웃을 참고합니다.

수동 연결은 자동 연결 설정을 비활성화한 앱에서 사용하는 기능으로, 회원가입 완료 시 수동으로 사용자와 앱의 연결 상태를 연결(Registered)로 변경하기 위해 호출합니다.

자동 연결을 비활성화한 앱에서 Partner Android SDK의 사용자 정보 조회 호출 시, 응답에 hasSignedUp 값을 반환합니다. 앱과 연결되어 있지 않은 사용자라면 hasSignedUp 값은 false입니다. hasSignedUp 값이 null인 경우, 자동 연결을 사용하는 앱이므로 수동 연결이 불필요합니다.

UserApiClient.instance.meForPartner { user, error ->
    if (error != null) {
        Log.e(TAG, "사용자 정보 요청 실패", error)
    } else {
        Log.i(TAG, "사용자 정보 요청 성공" +
                "\n회원번호: ${user.id}" +
                "\n연결여부: ${user.hasSignedUp}")
    }
}

사용자의 hasSignedUp 값이 false이고, 서비스에서의 가입 준비가 끝나 앱과 연결하려면 signupForPartner() 메서드를 호출합니다.

요청 성공 시 앱과 연결된 사용자의 회원번호가 반환됩니다. 자세한 응답 정보는 REST API를 참고합니다.

수동 연결 시 RequiredAgeVerification 에러가 발생하면 Partner Android SDK가 내부적으로 연령인증 페이지를 호출하기 위해 verifyAge() 메서드를 호출합니다. 이 외 연령인증이 필요한 경우, 연령인증 정보 조회 및 연령인증 페이지 호출을 참고해 연령인증 처리를 해야 합니다.

UserApiClient.instance.signupForPartner { error ->
    if (error != null) {
        Log.e(TAG, "연결 실패", error)
    } else {
        Log.i(TAG, "연결 성공")
    }
}

properties 파라미터를 사용해 수동 연결 시점에 서비스의 사용자 정보를 저장할 수 있습니다. properties에 저장한 정보는 연결 해제 시 삭제됩니다. 사용자 프로퍼티 및 사용자 프로퍼티 저장을 참고합니다.

앱과 사용자의 연결 상태를 해제합니다.

자세한 안내와 예제는 연결 해제를 참고합니다.

현재 Partner Android SDK에 저장 중인 액세스 토큰의 정보를 조회합니다.

자세한 안내와 예제는 액세스 토큰 정보 조회를 참고합니다.

사용자가 동의한 동의항목의 상세 정보 목록을 조회합니다.

자세한 안내와 예제는 동의항목 동의 내역 조회를 참고합니다.

사용자의 특정 동의항목에 대한 동의를 철회(Revoke)합니다.

자세한 안내와 예제는 동의항목 동의 철회를 참고합니다.

지정한 동의항목(Scope)을 사용자가 동의한 동의항목으로 추가합니다. 사용자로부터 동의를 받는 주체가 공동체이고 명시적인 제3자 제공 동의 화면을 제공하지 않을 경우, 동의항목 동의 처리 API가 아닌 동의항목 추가 동의 요청 API를 사용할 것을 권장합니다.

upgradeScopes() 메서드를 호출합니다. 추가할 동의항목의 ID를 scopes 파라미터의 값으로 전달해야 합니다. 동의항목 ID는 앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 확인할 수 있습니다. 14세 미만 보호자 동의가 필요한 서비스일 경우, guardianToken 값을 함께 전달해야 합니다.

성공 시 응답은 동의항목 추가 결과를 반영한 동의항목 상세 정보로 ScopeInfo 객체입니다. 자세한 응답 정보는 REST API를 참고합니다. 실패 시 에러 코드와 주의 사항을 참고합니다.

// 추가할 동의항목 ID 목록
val scopes = listOf("birthday")

UserApiClient.instance.upgradeScopes(scopes) { info, error ->
    if (error != null) {
        Log.e(TAG, "Upgrade Scopes 실패", error)
    } else {
        Log.i(TAG, info.toString())
        showSnackbar(info.toString())
    }
}

카카오싱크 서비스에서 사용자가 어떤 약관에 동의한 상태인지 조회합니다.

자세한 안내와 예제는 서비스 약관 동의 내역 조회를 참고합니다.

카카오싱크 서비스에서 사용자가 동의한 서비스 약관의 동의를 철회합니다.

자세한 안내와 예제는 서비스 약관 동의 철회를 참고합니다.

사용자의 연령인증 정보를 확인합니다. 연령인증의 내용을 숙지한 후 사용해야 합니다.

기준 제한 연령(age_limit), 계산 기준(age_criteria)을 지정하면 요청 시점의 제한 연령 만족 여부를 추가적으로 확인할 수 있습니다.

성공 시 응답은 사용자 ID와 연령인증 상세 정보를 포함합니다. 자세한 응답 정보는 REST API를 참고합니다.

UserApiClient.instance.ageAuthInfo(ageLimit = 30, ageCriteria = AgeCriteria.INTERNATIONAL, propertyKeys = null) { info, error ->
    if (error != null) {
        Log.e(TAG, "연령 인증 조회 실패", error)
    } else {
        Log.i(TAG, "연령 인증 조회 성공 ${info}")

    }
}

사용자 연령인증을 수행하기 위한 페이지를 호출합니다. 연령인증 페이지는 카카오계정에서 제공하는 기능이며, 공동체 서비스에서는 사용할 수 없습니다. 또한 이 메서드는 연령인증의 내용을 숙지한 후 사용해야 합니다.

연령인증 방식 중 'B. 필요 시 연령인증' 또는 'C. 앱 설정 없음'을 사용하는 경우, 수동 연결 API 요청 시 사용자의 연령인증 정보를 확인하지 않습니다. 이 경우, 서비스에서 직접 사용자가 서비스의 제한연령을 만족하는지 확인하기 위해 연령인증 정보 조회 후 연령인증 페이지 호출을 요청해야 합니다.

리다이렉션(Redirection)으로 연령인증 결과를 받습니다. 이를 위해, AndroidManifest.xml에 com.kakao.sdk.partner.user.AgeAuthActivity를 추가해야 합니다. <intent-filter> 내부에 data로 android:host와 android:scheme를 추가해 리다이렉트 URI를 설정합니다. android:scheme 속성의 값은 kakao${NATIVE_APP_KEY} 형식으로 입력합니다.

<activity android:name="com.kakao.sdk.partner.user.AgeAuthActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- 네이티브 앱 키가 123456789라면 kakao123456789 입력 -->
        <data android:host="ageauth" android:scheme="kakao${NATIVE_APP_KEY}" />

    </intent-filter>
</activity>

파라미터로 연령인증 레벨(authLevel), 제한 연령(ageLimit) 등을 지정할 수 있습니다. 자세한 파라미터 정보는 레퍼런스에서 확인할 수 있습니다.

UserApiClient.instance.verifyAge(
    context = context,
    ageLimit = 25,
    authLevel = AgeAuthLevel.AUTH_LEVEL1,
    skipTerms = false,
    adultsOnly = false,
    underAge = false,
) { error ->
    if (error != null) {
        Log.e(TAG, "연령 인증 실패", error)
    }
    else {
        Log.i(TAG, "연령 인증 성공")
    }
}