이 문서는 동의한 약관 확인하기 API 사용 방법을 안내합니다.
카카오싱크 간편가입은 카카오 플랫폼에서 제공되는 UI(User Interface)를 통해 정보 제공 동의 및 이용약관 한 번에 동의받아 사용자를 가입시킬 수 있게 하는 기능입니다. 앱에 설정한 이용약관은 카카오 로그인 간편가입 화면을 통해 사용자 동의를 받을 수 있습니다.
카카오계정 사용자를 기존 회원 정보와 연동(Mapping)하려는 경우, 카카오계정 로그인 시 동의받은 항목과 자체 회원가입 시 동의받은 약관의 종류가 다를 수 있습니다. 이에 대처하기 위한 기능으로 서비스 약관 동의 여부를 조회하는 동의한 약관 확인하기 API가 제공됩니다.
동의한 약관 확인하기는 사용자가 어떤 약관들에 동의한 상태인지 파악할 수 있게 해주는 기능입니다. 이 기능은 특정 사용자가 어떤 약관들에 동의하고 로그인했는지 알려줍니다. 애플리케이션(이하 앱) 설정에 등록된 약관들은 각각 태그(tag)를 가지고 있는데, 동의한 약관 확인하기 기능을 써서 사용자가 동의한 약관 태그를 알 수 있습니다.
동의한 약관 확인하기의 사용자별 응답과 전체 이용약관을 비교해 추가로 동의받을 항목이 있는지 확인합니다. 필요시 서비스에서 자체적으로 약관 동의 절차를 거치도록 구현합니다.
이 기능은 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.
사전 설정 | 카카오 로그인 |
---|---|
플랫폼 등록 카카오 로그인 활성화 동의 항목 약관 |
필요 |
액세스 토큰(Access Token)을 헤더에 담아 GET
으로 요청합니다. 앱에 설정된 약관 전체 목록을 함께 조회하려면 extra
파라미터의 값을 "app_service_terms"로 지정하여 전달합니다.
관리자가 특정 사용자의 서비스 약관 동의 내역을 확인하려면 서버에서 어드민 키(Admin key)로 요청할 수 있습니다. 어드민 키는 앱의 꼭 서버에서 호출할 때만 사용해야 합니다. 어드민 키를 사용해 요청할 경우 target_id
파라미터로 사용자 회원번호를 전달해 조회 대상을 지정하고, target_id_type
파라미터 값을 "user_id"로 지정하여 함께 전달해야 합니다.
응답은 사용자 ID와 약관 태그, 각 약관에 마지막으로 동의한 시간 정보를 포함합니다. 사용자가 서비스를 탈퇴하고 앱과의 연결을 끊은 뒤 로그인하면 다시 간편가입 화면을 통한 동의 절차를 거칩니다. 이에 따라 약관에 동의한 시간 정보가 갱신됩니다.
GET /v1/user/service/terms HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Name | Type | Description | Required |
---|---|---|---|
extra | String |
앱에 사용 설정된 서비스 약관 목록을 함께 요청하려면 "extra=app_service_terms"로 지정하여 요청 시 포함 |
X |
GET /v1/user/service/terms HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Name | Type | Description | Required |
---|---|---|---|
target_id_type | String |
사용자 ID 타입, user_id 로 고정 |
O |
target_id | Long |
사용자 ID | O |
extra | String |
앱에 사용 설정된 서비스 약관 목록을 함께 요청하려면 "extra=app_service_terms"로 지정하여 요청 시 포함 |
X |
Name | Type | Description | Required |
---|---|---|---|
user_id | Long |
회원번호 | O |
allowed_service_terms | AllowedServiceTerms[] |
사용자가 동의한 서비스 약관 항목 목록 | X |
app_service_terms | AppServiceTerms[] |
앱에 사용 설정된 서비스 약관 목록 | X |
Name | Type | Description | Required |
---|---|---|---|
tag | String |
서비스 약관에 설정된 태그(tag) | O |
agreed_at | Datetime |
사용자가 해당 약관에 마지막으로 동의한 시간 (RFC3339 internet date/time format) |
O |
Name | Type | Description | Required |
---|---|---|---|
tag | String |
서비스 약관에 설정된 태그(tag) | O |
created_at | Datetime |
서비스 약관이 등록된 시간 (RFC3339 internet date/time format) |
O |
updated_at | Datetime |
서비스 약관이 수정된 시간 (RFC3339 internet date/time format) |
O |
curl -v -X GET "https://kapi.kakao.com/v1/user/service/terms" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
curl -v -G GET "https://kapi.kakao.com/v1/user/service/terms" \
-H 'Authorization: Bearer ${ACCESS_TOKEN}' \
-d "extra=app_service_terms"
curl -v -G GET "https://kapi.kakao.com/v1/user/service/terms" \
-H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
-d "target_id_type=user_id" \
-d "target_id=${USER_ID}"
{
"user_id": 111111,
"allowed_service_terms": [
{
"tag": "service_20190101",
"agreed_at": "2019-05-10T10:33:26Z"
},
{
"tag": "privacy_20190102",
"agreed_at": "2019-05-10T10:33:26Z"
}
]
}
{
"user_id": 111111,
"allowed_service_terms": [
{
"tag": "age",
"agreed_at": "2020-06-18T05:58:35Z"
},
{
"tag": "additional_requirement_202002",
"agreed_at": "2020-06-18T05:58:35Z"
},
{
"tag": "service_20190326",
"agreed_at": "2020-06-18T05:58:35Z"
},
{
"tag": "privacy_20190326",
"agreed_at": "2020-06-18T05:58:35Z"
}
],
"app_service_terms": [
{
"tag": "additional_requirement_202002",
"created_at": "2020-02-14T06:10:36Z",
"updated_at": "2020-02-14T07:59:07Z"
},
{
"tag": "age",
"created_at": "2020-03-24T01:12:46Z",
"updated_at": "2020-03-24T01:12:46Z"
},
{
"tag": "option1",
"created_at": "2019-10-29T01:37:11Z",
"updated_at": "2019-10-29T01:37:11Z"
},
{
"tag": "privacy_20190326",
"created_at": "2019-03-26T11:36:29Z",
"updated_at": "2019-03-26T11:36:29Z"
},
{
"tag": "required_111",
"created_at": "2020-06-18T05:59:38Z",
"updated_at": "2020-06-18T05:59:38Z"
},
{
"tag": "service2_20190527",
"created_at": "2019-05-27T02:49:06Z",
"updated_at": "2019-10-16T05:24:58Z"
},
{
"tag": "service_20190326",
"created_at": "2019-03-26T11:36:29Z",
"updated_at": "2019-03-26T11:36:29Z"
}
]
}
동의한 약관 조회하기 API는 카카오 로그인 모듈의 UserApiClient
가 제공합니다. 필요한 모듈 설정하기를 참고하여 build.gradle(Module) 파일에 카카오 로그인 모듈인 v2-user
를 추가합니다.
사전 설정 | 카카오 로그인 | 레퍼런스 |
---|---|---|
플랫폼 등록 카카오 로그인 활성화 동의 항목 약관 |
필요 | 공통UserServiceTerms Android SDK serviceTerms() Reactive Android SDK serviceTerms() |
UserApiClient
의 serviceTerms()
API를 호출합니다.
// 동의한 약관 확인하기
UserApiClient.instance.serviceTerms { userServiceTerms, error ->
if (error != null) {
Log.e(TAG, "동의한 약관 확인하기 실패", error)
}
else if (userServiceTerms != null) {
Log.i(TAG, "동의한 약관 확인하기 성공" +
"\n회원번호: ${userServiceTerms.userId}" +
"\n동의한 약관: \n${userServiceTerms.allowedServiceTerms?.joinToString("\n")}")
}
}
var disposables = CompositeDisposable()
// 동의한 약관 확인하기
UserApiClient.rx.serviceTerms()
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ userServiceTerms ->
Log.i(TAG, "동의한 약관 확인하기 성공" +
"\n회원번호: ${userServiceTerms.userId}" +
"\n동의한 약관: \n${userServiceTerms.allowedServiceTerms?.joinToString("\n")}")
}, { error ->
Log.e(TAG, "동의한 약관 확인하기 실패", error)
})
.addTo(disposables)
요청 성공 시 응답은 UserServiceTerms
객체로 받습니다. UserServiceTerms
는 사용자 회원번호와 동의한 약관 목록인 allowedServiceTerms
를 포함합니다. allowedServiceTerms
는 각 약관의 사용자 동의 시간과 태그(Tag) 정보를 제공하는 ServiceTerms
객체의 리스트(List)입니다.
ServiceTerms
의 구성 요소 및 자료형은 Web의 응답 및 레퍼런스를 참고합니다.
이 기능을 사용하려면 다음 두 가지 의존성 설정이 필요하고, 사용자가 카카오계정으로 로그인한 상태여야 합니다.
subprojects {
repositories {
google()
jcenter()
maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/' }
}
}
dependencies {
// 카카오 로그인
implementation 'com.kakao.sdk:usermgmt:1.17.0'
}
사용자가 동의한 약관 정보는 UserManagement.serviceTerms
메서드로 요청합니다. 이 메서드를 사용하려면 응답을 처리할 ApiResponseCallback
을 구현해야 합니다.
응답은 Web과 동일합니다.
UserManagement.getInstance().serviceTerms(new
ApiResponseCallback<ServiceTermsResponse>() {
@Override
public void onSessionClosed(ErrorResult errorResult) {
// 로그인이 필요함
}
@Override
public void onFailure(ErrorResult errorResult) {
// 기타 에러
}
@Override
public void onSuccess(ServiceTermsResponse result) {
// 성공 콜백
}
});
동의한 약관 확인하기 API는 사용자 관리 모듈인 KakaoSDKUser
및 RxKakaoSDKUser
가 제공합니다. 동의한 약관 확인하기 API를 사용하려면 카카오 로그인, 사용자 관리 모듈을 모두 설치해야 합니다. 모듈 설치 방법은 설치하기를 참고합니다.
모듈 설치 후 카카오 로그인과 동의한 약관 확인하기 API를 사용하려면 다음과 같이 import
합니다.
import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKAuth
import RxKakaoSDKAuth
import KakaoSDKUser
import RxKakaoSDKUser
사전 설정 | 카카오 로그인 | 레퍼런스 |
---|---|---|
플랫폼 등록 카카오 로그인 활성화 동의 항목 약관 |
필요 | 공통UserServiceTerms iOS SDK serviceTerms() ReactiveX iOS SDK serviceTerms() |
동의한 약관 확인하기 API는 카카오 로그인 후 발급되는 토큰이 필요한 API이므로 카카오 로그인이 완료된 후 호출해야 합니다. UserApi
의 serviceTerms()
API를 호출합니다.
UserApi.shared.serviceTerms {(serviceTerms, error) in
if let error = error {
print(error)
}
else {
print("serviceTerms() success.")
//do something
_ = serviceTerms
}
}
// Class member property
let disposeBag = DisposeBag()
UserApi.shared.rx.serviceTerms()
.subscribe(onSuccess:{ (serviceTerms) in
print("serviceTerms() success.")
//do something
_ = serviceTerms
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
요청 성공 시 응답은 UserServiceTerms
객체로 받습니다. UserServiceTerms
는 사용자 회원번호와 동의한 약관 목록인 allowedServiceTerms
를 포함합니다. allowedServiceTerms
는 각 약관의 사용자 동의 시간과 태그(Tag) 정보를 제공하는 ServiceTerms
객체의 리스트(List)입니다.
ServiceTerms
의 구성 요소 및 자료형은 Web의 응답 및 레퍼런스를 참고합니다.
사용자가 동의한 약관을 확인하려면 로그인 상태에서 아래와 같이 호출합니다. 응답은 Web과 동일합니다.
KOSessionTask.serviceTermsTask(completionHandler: { (serviceTerms, error) in
if let error = error as NSError? {
print(error)
}
else {
if let serviceTerms = serviceTerms {
if let allowedTerms = serviceTerms.allowedTerms as [KOServiceTerms]? {
for (index, terms) in allowedTerms.enumerated() {
print("[\(index)] tag:\(String(describing: terms.tag)) agreedAt:\(String(describing: terms.agreedAt))")
}
}
}
}
})
동의한 약관 확인하기를 사용하려면 설치하기를 참고하여 pubspec.yaml 파일에 Flutter SDK 전체 또는 카카오 로그인 패키지에 대한 의존성을 추가해야 합니다.
사전 설정 | 카카오 로그인 | 레퍼런스 |
---|---|---|
플랫폼 등록 카카오 로그인 활성화 동의 항목 약관 |
필요 | serviceTerms() UserServiceTerms |
현재 로그인한 사용자가 동의한 약관 목록을 가져옵니다. UserApi
의 serviceTerms()
를 호출합니다.
try {
UserServiceTerms userServiceTerms =
await UserApi.instance.serviceTerms();
print('동의한 약관 확인하기 성공'
'\n회원정보: ${userServiceTerms.userId}'
'\n동의한 약관: \n${userServiceTerms.allowedServiceTerms?.join('\n')}');
} catch (error) {
print('동의한 약관 확인하기 실패 $error');
}
요청 성공 시, 사용자 회원번호와 동의한 약관의 태그 목록을 담은 UserServiceTerms
객체가 반환됩니다. 사용자가 동의한 약관은 UserServiceTerms
하위의 allowedServiceTerms
에 태그 값으로 포함됩니다.