사용자 관리

사용자 관리는 카카오 플랫폼 서비스에서 제공하는 핵심 기능 중 하나입니다. 사용자 관리는 쉽고 빠른 방법으로 사용자의 계정을 카카오 플랫폼과 연결해줍니다. 해당 기능을 통하여 안전하고 보다 더 강력한 참여형 사용환경의 앱을 만들 수 있습니다.

  • 시작하기 전에
    사용자 관리 기능을 연동하기 전에 필요한 앱 설정 항목과 특징을 설명합니다.

사용자 관리의 상세 기능은 다음과 같습니다.

  • 로그인
    카카오계정을 통한 빠르고 간편한 로그인 기능을 지원합니다.
  • 로그아웃
    로그인된 사용자의 세션 연결을 해제합니다.
  • 상태변경 이벤트 관리
    로그인/로그아웃 등의 세션 상태 변경을 감지합니다.
  • 앱 연결
    로그인한 사용자와 앱을 카카오 플랫폼에 연결합니다. 사용자가 앱 가입/등록 요청을 하는 경우와 비슷합니다.
  • 앱 연결 해제
    카카오 플랫폼에 연결된 사용자와 앱의 연결을 영구 해제합니다. 사용자가 앱 탈퇴 요청을 하는 경우와 비슷합니다.
  • 사용자 정보 요청
    사용자에 대한 정보를 얻어 올 수 있습니다. 해당 기능을 사용하기 위해서는 로그인 및 앱 연결이 되어 있어야 합니다.
  • 사용자 정보 저장
    사용자에 대한 특정 정보를 저장할 수 있습니다. 해당 기능을 사용하기 위해서는 로그인 및 앱 연결이 되어 있어야 합니다.
  • 토큰 정보 얻기
    사용자 토큰의 정보를 얻고, 해당 토큰의 유효성을 검증합니다.
  • 토큰 주기적 갱신
    사용자 토큰을 자동으로 주기적 갱신을 지원합니다. API호출 없이 로그인만을 사용할 경우 유용하게 사용할 수 있습니다.
  • 토큰 암호화 저장
    사용자 토큰을 암호화하여 보다 안전하게 저장하는 기능입니다.

시작하기 전에

Kakao iOS SDK를 설치하고 초기화해야 합니다. 자세한 내용은 시작하기를 참고해 주세요.

사용자 관리 기능을 사용하기 위해서 설정 > 사용자 관리에서 추가 설정이 필요합니다.

dev_021.png

  • 첫째, 사용ON 해야합니다

  • 둘째, 앱 연동 > 자동 가입 을 선택할 수 있습니다.

    카카오 플랫폼 서비스는 편의를 위해 자동 앱 연결 기능을 제공합니다. 해당 설정이 활성화되어 있을 경우 최초 로그인시 자동으로 앱 연결이 호출되므로 별도의 앱 연결 과정을 수행할 필요는 없습니다.

    사용자가 서비스에 최초 로그인하여 토큰을 얻는 순간과 실제 서비스 가입 시점이 동일하지 않는 경우(예를 들어, 서비스 내에 가입절차가 별도로 있거나 서비스약관동의 등의 절차가 별도로 있는 경우) 반드시 자동 가입 옵션을 끄셔야 합니다. 자동 가입 옵션을 끈 경우 사용자 최초 로그인 후에 명시적으로 가입API를 호출해야 사용자 가입이 완료됩니다.

    실제 서비스 가입하는 순간이 다름에도 불구 하고 자동 가입 옵션을 켜서 사용하는 경우는 사용자에게 혼란을 줄 수 있습니다. 예를 들어, 서비스 가입 과정 중에 이탈한 경우 카카오 로그인이 완료된 상태라면 연결된 앱관리에 해당 앱이 나타나게 됩니다. 이런 과정은 서비스를 탈퇴하고 난 후 탈퇴가 잘 되었는 지 확인차 로그인을 해보는 과정에서 자주 겪게 됩니다.

    사용자는 카카오계정으로 연결된 앱의 정보를 카카오톡이나 카카오스토리 내에 존재하는 카카오계정의 연결된 앱관리 페이지에서 확인할 수 있습니다.

  • 셋째, 앱 연동 > 카카오 계정 연동 을 선택할 수 있습니다.

    기본으로 제공되는 사용자 정보로 카카오톡 서비스 정보를 사용할지, 카카오스토리 서비스 정보를 사용할지, 두 서비스 모두 사용하는 사용자의 경우는 어느 서비스 정보에 우선순위를 둘지를 결정합니다. 기본으로 추가되어 있는 사용자 프로퍼티로는 nickname, profile_image, thumbnail_image가 있습니다.

    앱 연결 과정에서 최초 한번만 카카오톡 또는 카카오스토리 서비스와 동기화 연동을 하게 됩니다. 사용자가 해당 정보를 카카오톡 또는 카카오스토리에서 변경하였어도 추후 변경된 데이타는 반영되지 않습니다.

    카카오톡 또는 카카오스토리와의 동기화 연동 기능을 사용하지 않도록 설정되어 있을 경우, 해당 부가정보는 빈값으로 채워져 있습니다. 이 기본 부가정보는 사용자 정보 저장 기능을 통해 다른 데이타로 언제든 교체가 가능합니다.

  • 넷째, 가입시 추가하고 싶은 사용자 정보를 사용자 목록 및 프로퍼티 관리 메뉴를 통해 추가할 수 있습니다.

    커스텀 사용자 정보 컬럼은 5개 이하로 제한 하고, 각 커스텀 사용자 정보 값은 160자 이내로 권장합니다. 실제로 사용자의 프로퍼티는 앱 연결 시에 추가 가능합니다. 또한 사용자 정보 저장 기능을 통해서도 추가 가능합니다.

  • 다섯째, 서비스에서 사용할 API에서 요구하는 동의항목을 선택하고, 해당 API를 호출하는 목적, 즉 해당 정보의 수집 목적을 설정해야 합니다.

    입력한 수집목적의 내용과 실제 서비스에서 해당 개인 정보를 사용하는 목적이 다를 경우 API서비스의 거부 사유가 될 수 있습니다. 카카오계정 이메일을 사용하기 위해서는 여기에서 이메일 사용을 설정해야 합니다.

  • 여섯째, 서비스를 운영하는 곳이 국외라면 개인정보 국외이전 에서 개인정보가 저장되는 국가의 정보를 입력해야 합니다.

  • 일곱째, 플러스친구를 운영하신다면, 플러스친구 를 설정할 수 있습니다. 설정한 플러스친구는 가입 시 또는 서비스 이용 중 제3자 이용 제공 동의 창에 노출되어, 이용자가 해당 플러스친구를 추가할 수 있도록 유도합니다. 플러스친구를 개설하지 않았다면 플러스친구 개설 후 설정 가능합니다.

    플러스친구는?

    하나, 국가/성별/연령 등의 타겟팅 기능으로 원하는 사람에게 효과적으로 카카오톡 메시지를 보낼 수 있습니다.
    둘, 스마트 채팅을 통해 사용자가 직접 필요한 정보를 찾아볼 수 있고 일대일 채팅으로 쉽고 빠른 소통이 가능합니다.
    셋, 포스트나 메시지에 대한 사용자의 반응을 통계로 확인할 수 있어 이용패턴과 트렌드를 쉽게 파악할 수 있습니다.

    플러스친구 활용사례가 궁금하다면, '@플러스친구'와 친구를 맺고, 채팅에 "성공사례"를 입력해 보세요!

  • 여덟째, 사용자가 해당 서비스 외부에서 카카오계정과 해당 서비스와의 연결해제를 수행하는 경우 후처리가 필요하다면, 연결끊기 에서 콜백 API를 설정해야 합니다.
    예를 들어, 카카오계정으로만 로그인이 가능한 서비스의 경우, 카카오계정과의 연결해제는 서비스 탈퇴와 동일합니다. 따라서 사용자의 개인정보를 저장하고 있었다면, 콜백을 받아 모두 삭제해야 합니다. 또한, 카카오계정 이외의 방법으로도 로그인이 가능한 서비스의 경우, 카카오계정과의 연결해제시점에 카카오계정으로 부터 받은 개인정보를 저장하고 있었다면, 콜백을 받아 모두 삭제해야 합니다.

    서비스 외부에서 연결해제가 가능한 시나리오는 아래 세 가지가 있습니다.

    하나, 카카오계정 탈퇴로 인한 모든 서비스 탈퇴 시 해당 서비스가 포함된 경우 (ACCOUNT_DELETE)
    둘, 사용자가 카카오계정에 '연결된 서비스 관리'에서 개별 서비스 연결해제 요청한 경우 (UNLINK_FROM_APPS)
    셋, 고객센터로 해당 서비스 연결해제를 사용자가 요청한 경우 (UNLINK_FROM_ADMIN)

    콜백 API 호출시 아래와 같은 정보가 포함됩니다.

    헤더 : Authorization: KakaoAK {해당 서비스의 admin_key}
    파라미터 1: user_id (String) : 연결해제를 요청한 사용자 id (사용자 id가 넘어가기 때문에 https만 지원)
    파라미터 2: referrer_type (String) : 연결해제를 요청한 경로 (ACCOUNT_DELETE/UNLINK_FROM_ADMIN/UNLINK_FROM_APPS)

    예를 들어, 도메인은 "https://api.example.com", API Path는 "/v1/user/deregister", http method는 "GET"으로 등록한 서비스는, user_id가 1234인 사용자가 카카오계정에 연결된 서비스 목록에서 해당 서비스 연결해제 요청한 경우에, 아래와 같은 콜백을 받게 됩니다.

    curl -v -X GET https://api.example.com/v1/user/deregister?user_id=1234&referrer_type=UNLINK_FROM_APPS \
      -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

    콜백을 받아 아래와 같이 처리해야 합니다.

    하나, 헤더로 들어온 앱키가 해당서비스의 어드민 키임을 확인 하고, user_id에 해당하는 사용자의 개인정보가 남아 있으면 삭제 작업을 수행해야 합니다. referrer_type는 연결해제 경로 정보로 참고하시면 됩니다.
    둘, 삭제 작업이 완료되면 응답을 http status "200 OK" 로 보내시면 됩니다. response body 정보는 보지 않고, http status만 보고 성공 여부를 확인하게 되니 body 정보는 포함하지 않아도 됩니다.
    셋, 서버 이슈로 사용자 정보 삭제를 실패한 경우를 제외하고는, "200 OK" 응답이 3초 내에 보장되어야 합니다.
    예를 들어, 어떠한 이유로 해당 사용자가 현재 가입자가 아니더라도 실패 응답이 아닌 성공 응답을 보내야 합니다. 즉, 해당 사용자의 지워질 정보가 있어서 삭제를 해야 하는데 실패한 경우를 제외한 모든 경우에는 성공 응답을 주어야 합니다.
    실패 응답이나 응답 지연 현상이 지속되는 경우, 사용자가 연결해제를 계속 실패하는 경험을 하게 되므로 콜백 설정이 임의로 삭제될 수 있습니다.

    등록한 설정이 제대로 동작하는지는 '카카오톡, 카카오스토리 앱 > 더보기 > 프로필 관리 > 카카오계정' 또는 '카카오계정 웹사이트'에서 카카오계정 탈퇴, 연결해제를 수행하여 콜백이 잘 호출되는 지 확인하시면 됩니다.

로그인

카카오계정을 이용하여 빠르고 간편하게 로그인을 할 수 있습니다.

kakao_account_login_browser.png

일반적으로 사용자는 카카오계정으로 로그인 버튼을 클릭함으로서 카카오계정 기반의 로그인을 수행합니다. 간편한 로그인을 위해 Kakao SDK는 사용자의 카카오톡 앱과 연결된 카카오계정을 활용합니다. 로그인 과정은 사용자 기기의 환경에 따라 다음과 같이 나뉩니다.

  • 카카오톡 앱이 설치되어 있고 카카오계정이 연결되어 있는 경우: 카카오톡의 카카오계정을 이용합니다.
  • 카카오톡 앱이 설치되어 있으나 카카오계정 연결이 되어 있지 않은 경우: 사파리(Safari) 웹브라우저를 통해 카카오계정 연결을 수행하게 됩니다.
  • 카카오톡 앱이 설치되어 있지 않은 경우: SDK의 내부 웹뷰를 통해 카카오계정 연결을 수행하게 됩니다.

해당 로그인 기능은 OAuth 2.0을 지원합니다. 다음은 카카오 플랫폼 서비스에서 제공하는 가장 일반적인 OAuth 인증의 과정입니다.

  1. 사용자는 카카오계정으로 로그인 버튼을 클릭합니다.
  2. 카카오톡 앱에 연결된 카카오계정의 자격정보(Credentials)를 통해 사용자를 인식합니다.
  3. 자격정보가 올바르다면 사용자(Resource Owner)로부터 접근 자원에 대한 동의/허가를 얻습니다.
  4. 위 3까지 성공적으로 수행되었다면 인증 코드(Authorization Code)가 발급됩니다. 해당 인증 코드는 Redirection URI를 기반으로 Third 앱에 전달됩니다.
  5. Third 앱에서는 전달받은 인증 코드를 기반으로 사용자 토큰(Access Token, Refresh Token)을 요청하고 얻게 됩니다.

    사용자 토큰은 카카오 플랫폼 서비스에서 제공하는 로그인 기반의 기능을 사용하는데 있어 중요한 키로 사용됩니다. OAuth 2.0의 보다 자세한 내용은 여기를 참고하세요.

위의 복잡한 과정들은 Kakao SDK가 많은 부분 담당하고 있으며, 이를 어떻게 사용하는지에 대해 다음에서 설명합니다.

로그인 버튼 추가

로그인을 위해 버튼을 추가합니다. UIButton 을 상속한 KOLoginButton 을 이용하여 로그인 버튼을 손쉽게 생성할 수 있습니다.

// button position
int xMargin = 30;
int marginBottom = 25;
CGFloat btnWidth = self.view.frame.size.width - xMargin * 2;
int btnHeight = 42;

UIButton* kakaoLoginButton
    = [[KOLoginButton alloc] initWithFrame:CGRectMake(xMargin, self.view.frame.size.height-btnHeight-marginBottom, btnWidth, btnHeight)];
kakaoLoginButton.autoresizingMask = UIViewAutoresizingFlexibleTopMargin | UIViewAutoresizingFlexibleWidth;

[self.view addSubview:kakaoLoginButton];

위에서 생성한 버튼에 로그인 호출을 담당할 method(여기서는 invokeLoginWithTarget method)를 연결합니다.

[kakaoLoginButton addTarget:self
                     action:@selector(invokeLoginWithTarget:)
           forControlEvents:UIControlEventTouchUpInside];

아래는 invokeLoginWithTarget method 내부입니다. 이로서 사용자가 '카카오계정으로 로그인' 버튼을 클릭하여 로그인 과정을 시작할 수 있게 합니다.

// ensure old session was closed
[[KOSession sharedSession] close];

[[KOSession sharedSession] openWithCompletionHandler:^(NSError *error) {
    if ([[KOSession sharedSession] isOpen]) {
        // login success
        NSLog(@"login succeeded.");
    } else {
        // failed
        NSLog(@"login failed.");
    }
}];

로그인시 기본적으로 앱의 상황에 맞게 카카오톡, 카카오스토리, 다른 카카오계정으로 로그인의 다중 인증 선택창이 나타납니다. 인증 타입의 종류를 직접 컨트롤하고 싶을 경우, 원하는 인증방식의 KOAuthType을 파라미터로 넘길 수 있습니다. 다음은 오직 카카오톡으로 간편로그인만을 원하는 경우의 예제입니다.

[[KOSession sharedSession] openWithCompletionHandler:^(NSError *error) {
    ...
} authType:(KOAuthType)KOAuthTypeTalk, nil]];

미리 정의한 Redirection URI을 통해, 인증 과정이 올바로 진행되도록 AppDelegate에 아래와 같은 코드를 추가합니다. 해당 코드를 추가함으로서 Kakao SDK는 사용자 토큰을 취득하게 됩니다.

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
                                       sourceApplication:(NSString *)sourceApplication
                                              annotation:(id)annotation {
    ...
    if ([KOSession isKakaoAccountLoginCallback:url]) {
        return [KOSession handleOpenURL:url];
    }
    ...
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
                                                 options:(NSDictionary<NSString *,id> *)options {
    ...
    if ([KOSession isKakaoAccountLoginCallback:url]) {
        return [KOSession handleOpenURL:url];
    }
    ...    
}

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    [KOSession handleDidBecomeActive];
}

로그인 성공시 Access Token, Refresh Token을 참조 할 수도 있습니다.

[KOSession sharedSession].accessToken

카카오 로그인에서는 보안 수준을 강화하기 위하여 OAuth 클라이언트 시크릿을 제공합니다.

클라이언트 시크릿은 개발자 웹사이트의 내 애플리케이션 설정 > 일반 > Client Secret 메뉴를 통해 발급 및 활성화를 수행할 수 있습니다.

클라이언트 시크릿을 사용하려면 AppDelegate의 application:didFinishLaunchingWithOptions: 메소드 내에서 다음과 같이 클라이언트 시크릿을 설정해야 합니다.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [KOSession sharedSession].clientSecret = @"<your client secret>";
    return YES;
}

결과 예시

다음은 이해를 돕기위한 로그인 과정의 결과 예시입니다.

login_button.png

카카오톡 앱이 설치되어 있다면, 카카오톡으로 간편로그인을 할지 다른 계정을 직접 입력해서 로그인할지 선택할 수 있는 창이 뜨게 됩니다.

카카오스토리로 간편로그인의 경우 카카오스토리 2.9.0이상의 버젼이 필요합니다.

choose_account_dialog.png

1. 카카오톡으로 간편로그인을 선택한 경우
1-1. 카카오계정이 연결되어 있는 경우, 접근 자원에 대한 동의/허가를 위한 화면이 나타납니다.

sample_app_approval_on_talk.png

1-2. 카카오계정 연결이 되어 있지 않은 경우, 사파리(Safari) 웹브라우저를 통해 아이디와 비밀번호를 요구하는 화면이 나타납니다. 자격 정보(Credentials)에 대한 검증이 통과하면 접근 자원에 대한 동의/허가를 위한 화면이 나타납니다.

kakao_account_login_browser.png sample_app_approval.png

2. 다른 계정으로 로그인을 선택한 경우 카카오톡 앱이 설치되어 있지 않은 경우, 웹뷰를 통해 아이디와 비밀번호를 요구하는 화면이 나타납니다. 자격 정보(Credentials)에 대한 검증이 통과하면 접근 자원에 대한 동의/허가를 위한 화면이 나타납니다.

kakao_account_login_webview.png sample_app_approval_on_talk.png

로그아웃

사용자의 기기에서 앱과 카카오계정과의 세션 연결을 해제하는 기능입니다.

로그인 기능은 멀티디바이스를 지원합니다. 만약 사용자가 여러 기기에서 하나의 같은 카카오계정으로 로그인 후 로그아웃을 수행한다면, 해당 로그아웃을 수행한 기기에서만 세션 연결이 해제됩니다.

다음은 로그아웃을 수행하는 예제 코드입니다.

[[KOSession sharedSession] logoutAndCloseWithCompletionHandler:^(BOOL success, NSError *error) {
    if (success) {
        // logout success.
    } else {
        // failed
        NSLog(@"failed to logout.");
    }
}];

로그아웃의 경우 아래의 원인들로 실패할 수 있습니다.

상태변경 이벤트 관리

카카오계정의 세션 연결 상태는 로그인, 로그아웃 등의 과정을 통해 동적으로 변할 수 있습니다. 해당 상태변경시 발생하는 이벤트(Notification)는 다음 예제 코드를 통해 다룰 수 있습니다.

이벤트를 처리할 메소드를 정의합니다.

- (void)kakaoSessionDidChangeWithNotification:(NSNotification *)notification
{
    if ( ! [[KOSession sharedSession] isOpen] ) {
        // do something for unauthenticated user
    }
}

위에서 정의한 메소드를 NSNotificationCenter에 Observer로 등록합니다.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    // 카카오계정의 세션 연결 상태가 변했을 시,
    // Notification을 kakaoSessionDidChangeWithNotification 메소드에 전달하도록 설정
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(kakaoSessionDidChangeWithNotification:)
                                                 name:KOSessionDidChangeNotification
                                               object:nil];
    ...
}

앱 연결

앱 연결은 로그인한 사용자와 앱을 카카오 플랫폼에 연결함으로서 일반적으로 사용자가 앱 가입/등록 요청을 하는 경우와 비슷합니다. 카카오 플랫폼 서비스를 올바로 사용하기 위해서는 로그인 후 반드시 앱 연결이 선행되어야 하며, 최초 한번만 수행가능합니다. 앱 연결이 올바로 수행되면 해당 사용자에 대한 고유한 아이디(ID)가 부여됩니다.

다음은 앱 연결을 수행하는 예제 코드입니다.

[KOSessionTask signupTaskWithProperties:nil
                      completionHandler:^(BOOL success, NSError *error) {
    if (success) {
        // success
    } else {
        // failed
        if( error.code == KOServerErrorAlreadyRegisteredUser ){
            // do something for already registered user.
        }
    }
}];

앱연결의 경우 아래의 원인들로 실패할 수 있습니다.

앱 연결 해제

앱 연결 해제는 카카오 플랫폼에 연결된 사용자와 앱의 연결을 영구 해제함으로서 일반적으로 사용자가 앱 탈퇴 요청을 하는 경우와 비슷합니다. 앱 연결 해제가 수행된 사용자는 영구적으로 복구가 불가능하며 카카오 플랫폼 서비스를 더이상 사용할 수 없습니다. 단, 다시 앱 연결을 통해 새로운 데이타로 카카오 플랫폼 서비스를 이용할 수는 있습니다.

앱 연결 해제를 수행할 경우 카카오 플랫폼에서 관리하는 해당 사용자의 데이타는 모두 지워집니다. 단, Third앱에서 저장하는 데이타의 경우 카카오 플랫폼 서비스에서는 책임을 질 수 없습니다. 이는 Third앱에서 지워야 할 의무를 가집니다(보다 자세한 내용은 정책 및 약관을 참고하세요). 이것이 흔히 말하는 앱 탈퇴와 앱 연결 해제와의 차이점입니다.

다음은 앱 연결 해제를 수행하는 예제 코드입니다.

[KOSessionTask unlinkTaskWithCompletionHandler:^(BOOL success, NSError *error) {
    if (success) {
        // success
    } else {
        // failed
    }
}];

앱연결 해제의 경우 아래의 원인들로 실패할 수 있습니다.

사용자 정보 요청

v2 API로 업데이트 되었습니다. 기존 v1 API를 사용했다면 v1 사용자 정보 요청과 달라진 점를 확인하시고 업데이트 해주세요.

사용자 정보 요청은 사용자에 대한 아이디(ID) 와 카카오계정 이메일(email) 및 개별 상세 정보를 얻어 올 수 있는 기능입니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 또한 앱 연결이 전제가 되어 있어야 합니다.

사용자 아이디(ID)의 경우 앱 연결 과정에서 발급하는 앱별 사용자의 고유 아이디입니다. 해당 아이디를 통해 사용자를 앱에서 식별 가능하며, 앱 연결 해제를 같은 값으로 계속 유지됩니다.

카카오계정 이메일을 수집하여 사용할때 다음 내용을 주의하세요.

  • 사용자의 카카오계정 이메일이 없을 수 있습니다.

모든 사용자에 대해 이메일이 필요한 서비스라면, 이메일 소유여부를 확인하세요. 카카오계정 이메일이 없는 경우에는, 서비스에서 사용자에게 카카오계정 이메일이 없음을 안내하고 사용자로부터 직접 이메일을 입력받는 방법을 권장합니다. (예. 카카오계정에 이메일이 존재하지 않습니다. 이메일주소 입력이 필요합니다.)

  • 사용자의 카카오계정 이메일은 인증 받지 않은 이메일일 수 있습니다.

인증받은 이메일만 사용하는 서비스라면, 이메일 인증여부를 확인하세요. 인증받지 않은 카카오계정 이메일을 사용하는 사용자의 경우에는, 서비스에서 사용자에게 카카오계정 이메일이 인증받지 않았음을 안내하고 사용자로부터 직접 이메일을 입력받는 방법을 권장합니다.(예. 인증받지 않은 카카오계정을 사용중입니다. 이메일주소 입력이 필요합니다.)

  • 카카오계정의 이메일은 사용자의 요청으로 인해 변경 될 수 있습니다. 서비스에서는 이메일을 활용하는 시점에 이메일의 변경 유무를 확인할 것을 권장합니다.

카카오 플랫폼 서비스에서는 편의를 위해 카카오톡 또는 카카오스토리 서비스와 연동하여 사용자별 다음과 같은 기본 부가정보를 제공합니다.

  • nickname: 카카오톡 또는 카카오스토리의 닉네임 정보
  • profile_image: 카카오톡 또는 카카오스토리의 프로필 이미지 URL
  • thumbnail_image: 프로필 이미지의 썸네일 URL

해당 부가정보는 설정에 의해, 필요시 앱 연결 과정에서 최초 한번만 카카오톡 또는 카카오스토리 서비스와 동기화 연동을 하게 됩니다. 사용자가 해당 정보를 카카오톡 또는 카카오스토리에서 변경하였어도 추후 변경된 데이타는 반영되지 않습니다.

카카오톡 또는 카카오스토리와의 동기화 연동 기능을 사용하지 않도록 설정되어 있을 경우, 해당 부가정보는 빈값으로 채워져 있습니다. 이 기본 부가정보는 사용자 정보 저장 기능을 통해 다른 데이타로 언제든 교체가 가능합니다. 카카오 플랫폼 서비스에서 제공하는 카카오톡 또는 카카오스토리 API를 통해 사용자 정보 저장 기능을 이용하여 직접 동기화를 할 수도 있습니다.

기본 사용법

iOS SDK에서는 KOUserMe 클래스를 이용하여 사용자 정보를 제공하고 있습니다. 제공되는 사용자 정보는 크게 앱별 기본정보, 카카오계정 정보, 부가정보 등으로 구성되어 있습니다.

구성 해당속성 설명
앱 기본 정보 ID
hasSignedUp
사용자 식별자 등 모든 앱에 공통으로 사용되는 정보
카카오계정 정보 account 로그인한 카카오계정에 등록된 사용자 개인 정보. ex) 이메일
부가 정보 properties 앱 별로 제공되는 사용자 정보 데이터베이스. ex) 닉네임, 썸네일
제휴 전용 forPartner 제휴를 통해 권한이 부여된 특정 앱에만 제공되는 정보

다음은 사용자 전체 정보를 얻어오는 예제 코드입니다.

[KOSessionTask userMeTaskWithCompletion:^(NSError *error, KOUserMe *me) {
    if (error) {
        // fail

    } else {
        // success

        NSLog(@"사용자 아이디: %@", me.ID);
        NSLog(@"사용자 닉네임: %@", me.nickname);
    }
}];

이메일 가져오기

이메일을 가져오기 위하여 먼저 아래 항목들을 확인합니다.

하나, 설정 > 사용자 관리 > 동의항목 에서 '개인정보 보호항목'에 이메일이 보이는지 확인합니다.
보이지 않는다면, 수집목적을 작성하고 이메일 항목을 설정합니다.

둘, 응답에 hasEmail 값으로 해당값을 소유 여부를 확인합니다.
hasEmail 값이 False이면 해당 사용자는 카카오계정에 해당값을 소유하지 않은 것은 것으로 판단합니다.
hasEmail 값이 True인데, 이메일 값이 없다면, 사용자가 해당 항목에 대해 개인정보 제3자 제공 동의를 하지 않는 경우 입니다.
이메일 동의항목을 전달하여 동적동의를 받은 후, 사용자 정보 요청을 다시 합니다.
(위 과정을 손쉽게 확인하기 위하여 needsScopeAccountEmail 메소드가 제공되고 있습니다.)

아래는 이메일을 가져오는 간단한 예제코드입니다.

[KOSessionTask userMeTaskWithCompletion:^(NSError *error, KOUserMe *me) {
    if (error) {
        // fail

    } else {
        // success

        if (me.account.email) {
            // 이메일 가져오기 성공

        } else if ([me.account needsScopeAccountEmail]) {
            // 이메일 제공에 대한 사용자 동의가 필요한 상황 (이메일 동의창 요청이 가능한 상황)

            [[KOSession sharedSession] updateScopes:@[@"account_email"]
                                  completionHandler:^(NSError *error) {
                                      if (error) {
                                          if (error.code == KOErrorCancelled) {
                                              // 동의 안함

                                          } else {
                                              // 기타 에러
                                          }
                                      } else {
                                          // 동의함
                                          // *** userMe를 다시 요청하면 이메일 획득 가능 ***

                                      }
                                  }];
        } else {
            // 이메일 가져오기 실패

        }
    }
}];
연령대/생일/성별 가져오기

기본적인 획득 방법은 이메일 가져오기와 동일합니다. 개발자사이트 사용자 관리 설정에서 해당하는 정보 동의항목에 수집 목적을 입력하고 사용하도록 설정해야 합니다. 사용되는 프로퍼티와 동의항목(scope) ID는 다음과 같습니다.

정보 프로퍼티 scope ID
연령대 ageRange age_range KOUserAgeRangeType15 - 15세 ~ 19세
KOUserAgeRangeType20 - 20세 ~ 29세
...
KOUserAgeRangeType90 - 90세 이상
생일 birthday birthday 'MMDD' 형식 문자열
성별 gender gender KOUserGenderMale - 남자
KOUserGenderFemale - 여자
자동연결 기능을 사용하지 않을 경우

자동연결을 사용하지 않는 앱에서는 hasSignedUp 값을 확인하여 사용자 아이디 및 부가 정보를 획득해야 합니다.

  • 사용자 아이디(ID)는 앱 연결 시점에 발급되는 값이며 자동연결 기능을 비활성화 한 경우 명시적인 signup 호출 이전에는 값이 반환되지 않습니다. 자동연결 기능을 비활성화 한 경우 hasSignedUp 값으로 앱 연결 여부를 확인하고 사용해야 합니다.

  • 닉네임과 프로필 이미지 등의 부가정보 또한 앱 연결 시점에 연동되며 hasSignedUp이 False일 경우 값이 반환되지 않습니다.

  • 이메일 등 카카오계정의 개인 정보 속성들도 앱 연결 이전에는 값을 가져올 수 없으며 hasXXX를 이용하여 값의 유무 확인만 가능합니다.

[KOSessionTask userMeTaskWithCompletion:^(NSError *error, KOUserMe *me) {
    if (error) {
        // fail

    } else {
        // success

        if (me.hasSignedUp == KOOptionalBooleanFalse) {
            // 앱 연결(signup) 되어있지 않음

            if (me.account.hasEmail == KOOptionalBooleanTrue) {
                // 사용자가 이메일을 보유하고 있음

            }
        } else {

            NSLog(@"사용자 아이디: %@", me.ID);
            NSLog(@"사용자 닉네임: %@", me.nickname);
        }
    }
}];
원하는 값만 요청하고 싶은 경우

사용자 정보 요청에서 제공하는 정보 전체가 아닌 일부만 받고 싶은 경우 해당하는 정보의 키를 지정하여 일부만 받아볼 수 있습니다. 부가정보 하위 정보일 경우 "properties.XXX", 계정정보 하위 정보일 경우 "kakao_account.XXX" 형식으로 해당 키를 전달해야 합니다.

아래는 기본적으로 요청할 수 있는 키 리스트입니다.

설정 > 사용자 관리 > 사용자 목록 및 프로퍼티 관리 에서 추가로 등록한 프로퍼티도 사용할 수 있습니다.

Name Description
properties.nickname 카카오톡 또는 카카오스토리의 닉네임 정보
properties.profile_image 640px * 640px 크기의 프로필 이미지 URL (2017/08/22 이전 가입자에 대해서는 480px * 480px ~ 1024px * 1024px 크기를 가질 수 있음)
properties.thumbnail_image 110px * 110px 크기의 썸네일 프로필 이미지 URL (2017/08/22 이전 가입자에 대해서는 160px * 213px 크기를 가질 수 있음)
kakao_account.email 사용자 카카오계정의 이메일 소유여부, 이메일 값, 이메일 인증여부, 이메일 유효여부
kakao_account.age_range 사용자 카카오계정의 연령대 소유여부, 연령대 값
kakao_account.birthday 사용자 카카오계정의 생일 소유여부, 생일 값
kakao_account.gender 사용자 카카오계정의 성별 소유여부, 성별 값

아래는 이메일닉네임을 요청하는 예제 코드입니다.

[KOSessionTask userMeTaskWithPropertyKeys:@[@"kakao_account.email",
                                            @"properties.nickname"]
                               completion:^(NSError *error, KOUserMe *me) {
                           if (error) {
                               // fail

                           } else {
                               // success

                               NSLog(@"사용자 아이디: %@", me.ID);
                               NSLog(@"사용자 이메일: %@", me.account.email);
                               NSLog(@"사용자 닉네임: %@", me.nickname);
                           }
                        }];

v1 사용자 정보 요청과 달라진 점
  • 자동가입이 off일때 토큰발급만 받고, 명시적으로 앱 연결은 호출 안한 상태에서 v1 사용자 정보 요청시 NotRegisteredException발생했지만, v2 사용자 정보 요청시에는 발생하지 않습니다.
  • response의 키 중 kaccount prefix를 가진 키(이메일)는 account 하위로 계층이 생겼습니다.
  • 연령대, 생일, 성별 값이 추가 되었습니다.
  • 추가 동의가 필요한 카카오계정 개인정보(이메일, 연령대, 생일, 성별)의 경우 hasXXX 속성이 추가 되었습니다.
  • response의 값이 존재하지 않으면, 키도 내려가지 않습니다.
  • 서버가 불안정한 경우, account 하위의 값을 가지고 오지 못하더라도 에러를 발생시키지 않습니다. 꼭 필요한 경우는 재요청을 하셔야 합니다.

리턴될 수 있는 에러는 아래와 같습니다.

동적동의

사용자 정보 요청을 제외한 KOSessionTask 하위의 모든 API는 제3자 제공 동의가 필요한 모든 시점에 자동으로 동적동의를 노출하고 사용자의 동의를 받습니다. 사용자가 동의하지 않을 경우 해당 API 메소드의 콜백으로 KOErrorCancelled 에러가 전달됩니다.

사용자 정보 요청 API 처럼 상황에 따라 임의의 사용자의 동의가 필요한 경우 (가입 시 유저가 동의하지 않았거나, 앱설정에 이용중 선택으로 설정한 경우) 직접 유저에게 해당 정보 제공 동의를 받아야 합니다. 아래는 유저에게 이메일과 생일에 대한 동의를 받는 예제 코드입니다.

[[KOSession sharedSession] updateScopes:@[@"account_email",
                                          @"birthday"]
                      completionHandler:^(NSError *error) {
                          if (error) {
                              switch (error.code) {
                              case KOErrorCancelled:
                                  // 동의 안함

                                  break;
                              defalut:
                                  // 기타 에러

                                  break;
                              }
                          } else {
                              // 사용자가 동의함

                          }
                      }];

사용자 정보 저장

사용자 정보 저장은 개별 사용자에 대한 특정 부가정보를 저장할 수 있는 기능입니다. 카카오 플랫폼 서비스에서 제공하는 기본 부가정보 외에도, 개발자 웹사이트를 통해 앱별 커스텀한 정보를 선언하여 유저별 데이타를 저장할 수 있습니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 또한 앱 연결이 전제가 되어 있어야 합니다.

사용자 정보 저장 기능으로 수정할 수 없는 사용자의 정보도 존재합니다. 예를 들어 사용자의 아이디(ID)는 수정될 수 없습니다.

다음은 사용자 정보에 기본 부가정보 중 nickname과 커스텀 정보 age을 저장하는 예제 코드입니다. 커스텀 정보 age 항목은 대쉬보드의 설정 > 사용자 관리 메뉴에 미리 선언되어 있어야 합니다.

NSDictionary *properties = @{
    @"nickname":@"vincent",
    @"age":@"20"
};

[KOSessionTask profileUpdateTaskWithProperties:properties
                             completionHandler:^(BOOL success, NSError *error) {

   if (success) {
       NSLog(@"succeeded to set my properties.");
   } else {
       NSLog(@"failed to set my properties.");
   }
}];

리턴될 수 있는 에러는 아래와 같습니다.

토큰 정보 얻기

로그인을 통해 얻은 사용자 토큰의 정보를 얻는 기능입니다. 호출에 성공할 경우 토큰 정보(사용자 ID, 토큰유효시간)를 받을 수 있으며, refreshToken이 만료되어 갱신이 불가능하거나 기타 오류 발생 시 해당 오류를 받을 수 있습니다.

accessToken만 만료되고 refreshToken이 유효할 경우는 내부적으로 자동 갱신(KOSessionTask의 모든 API 공통) 처리되므로 기존에 로그인 되어있던 토큰이 아닌 새롭게 갱신된 토큰 정보를 받게 됩니다.

다음은 사용자 토큰의 정보를 얻는 예제 코드입니다.

[KOSessionTask accessTokenInfoTaskWithCompletionHandler:^(KOAccessTokenInfo *accessTokenInfo, NSError *error) {
    if (error) {
        switch (error.code) {
            case KOErrorDeactivatedSession:
                // 세션이 만료된(access_token, refresh_token이 모두 만료된 경우) 상태
                ...
                break;
            default:
                // 예기치 못한 에러. 서버 에러
                ...
                break;
        }
    } else {
        // 성공 (토큰이 유효함)
        NSLog(@"남은 유효시간: %@ (단위: ms)", accessTokenInfo.expiresInMillis);
        ...
    }
}];

토큰 주기적 갱신

로그인을 통해 얻은 사용자 토큰을 자동으로 주기적 갱신하는 기능입니다. 다른 API 사용 없이 오직 로그인만을 사용하는 앱일 경우, 사용자 토큰의 만료에 대한 걱정없이 SDK 내부적으로 해당 토큰을 자동 주기적으로 갱신합니다.

해당 기능과 관련없이 SDK에서는 API호출시 자동으로 사용자 토큰을 갱신하는 기능이 내장되어 있습니다.

해당 기능을 사용하기 위해서는 아래와 같이 두가지를 추가로 적용합니다. 먼저 AppDelegate의 didFinishLaunchingWithOptions에서 automaticPeriodicRefresh 옵션 사용을 활성화합니다.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    [KOSession sharedSession].automaticPeriodicRefresh = YES;
}

AppDelegate의 applicationDidEnterBackground부분에 아래를 추가합니다.

- (void)applicationDidEnterBackground:(UIApplication *)application {
    ...
    [KOSession handleDidEnterBackground];
}

토큰 암호화 저장

로그인을 통해 얻은 사용자 토큰은 SDK를 통해 디바이스에 저장되게 됩니다. 이때 저장 보안 방식을 앱의 plist(예를들어 프로젝트의 Info 설정, info.plist파일)의 옵션으로 선택할 수 있습니다. 다음은 토큰 암호화 저장 기능을 활성화 할때의 예입니다. 디폴트 값은 false입니다.

<key>KAKAO_SECURE_MODE</key>
<true/>

Last Modified : 2018-09-19