User management

User management is core functionality provided by kakao platform service. User management connects user's account with kakao platform easily. You can now make secure and user interactive app easily.

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

Details on functionality of user management follows .

  • Login: Support easy and fast login through kakao account.
  • Logout: Disconnect user login session.
  • Managing state changing events: Check on state of Login/Logout session.
  • Connecting App: Connect logged in user and app to kakao platform. This is similar procedure to user registering app.
  • Disconnecting App: Disconnect connection of user and app to kakao platform permanently. This is similar to request for unregistering user.
  • User information retrieval: Possible to retrieve user information. In order to use such functionality, login and app must be connected.
  • Saving user information: Possible to save specific user information.In order to use such functionality, login and app must be connected.
  • 토큰 정보 얻기
    사용자 토큰의 정보를 얻고, 해당 토큰의 유효성을 검증합니다.
  • 토큰 주기적 갱신
    사용자 토큰을 자동으로 주기적 갱신을 지원합니다. API호출 없이 로그인만을 사용할 경우 유용하게 사용할 수 있습니다.
  • 토큰 암호화 저장
    사용자 토큰을 암호화하여 보다 안전하게 저장하는 기능입니다.

Getting started

Kakao iOS SDK must be installed and initialized. For details, follow getting started.

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

dev_021.png

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Login

You can login with kakao account.

kakao_account_login_browser.png

Generally speaking, user uses kakao account login button to login to kakao account based logins. To make this experience simpler, Kakao SDK uses kakao account linked to kakaotalk. Login procedures will depend on followings.

  • In case where kakaotalk app is installed and is linked with kakao account: Uses kakao account in kakaotalk.
  • In case where kakaotalk app is installed but is not linked to kakao account : Use browser(Safari) account login to connect account.
  • In case where kakaotalk is not installed : Use SDK's internal webview to login through kakao account.

Such login functionality support OAuth 2.0. Following is the most common way Kakao platform service provides to authenticate through OAuth.

  1. User clicks on login button using kakao account.
  2. Use kakao account credentials in kakaotalk for identifying users.
  3. If ownership info is correct, resource must be granted from agreement of resource owner.
  4. If up to procedure 3 finish successfully, Authorization Code will be issued. Such code will be sent to third app through Redirection URI.
  5. Using authentication code received from third party app, Access Token, Refresh Token will be requested and received.

    User token in kakao platform service is provided as important key for login based services. For details on OAuth 2.0 please refer here.

Many of the complicated procedures are dealt by Kakao SDK for you, and following explains how to use them correctly.

Adding login button

Add button for login. Using KOLoginButton which inherits UIButton, you can create login button easily.

// 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];

Connect method(here, invokeLoginWithTarget method will be used) for dealing with login call with the button create above.

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

This is the content of invokeLoginWithTarget method. Following makes user use 'Login with kakao account' button to follow login procedures.

// 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.");
    }
}];

During login, depending on app status, authentication window with multiple authentication(Kakao talk, kakaostory, other kakao account) method will appear. If you like to control authentication method, you can do so by passing KOAuthType parameter. This is an example of using only kakaotalk login.

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

Using pre-defined Redirection URI, add code below in AppDelegate to complete authentication procedures correctly. Using such code, Kakao SDK can retrieve user token.

- (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];
}

After logging in successfully, Access Token and Refresh Token can be referred.

[KOSession sharedSession].accessToken

Kakao Login API provides OAuth client secret. You can make enhanced security using this.

You can generate and activate it through My Application > Settings > General > Client Secret menu.

Following is an example code for using client secret.

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

Result example

Following is an example to help you understand login procedures.

login_button.png

If kakaotalk app is installed, whether to use kakaotalk simple login or to login with different kakaotalk account in a new window.

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

choose_account_dialog.png

1. If simple login is chosen using kakaotalk
1-1. In a case where kakao account exists, window for asking access permission will appear.

sample_app_approval_on_talk.png

1-2. In case where kakao account is not connected, using Safari web browser, window will pop up, asking for userid and password for login. After credentials have been comfirmed, screen on approval and permission screen will appear.

kakao_account_login_browser.png sample_app_approval.png

2. In case where you have chosen to login through different account In case where Kakaotalk app is not installed, screen asking for id and password will appear through webview. After Credentials information has been comfirmed screen for permission and approval will appear.

kakao_account_login_webview.png sample_app_approval_on_talk.png

Logout

Disconnecting session between app and kakao account in user's app.

Logging in to multiple device is supported. If user login in to multiple devices and log out from one of them, only the device that logged out will be affected(Session disconnected). Logging in to multiple device is supported.

Following is example code for logging out .

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

Logout could fail due to following reasons.

Managing state changing event

Kakao account's session status can change dynamically through login and logout procedures. If such status change occurs, occuring Notification can be effected through example code below .

Define method for dealing with events.

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

Register as Observer in NSNotification of method defined above.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    // When kakao account session connection state changed
    // Set to send Notification to kakaoSessionDidChangeWithNotification method
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(kakaoSessionDidChangeWithNotification:)
                                                 name:KOSessionDidChangeNotification
                                               object:nil];
    ...
}

Connecting App

App connection connects logged in user and app with kakao platform which is simillar to user making registration request to your app. In order to use kakao platform correctly app connection must be accomplished first, and it will only be asked initially. If app connection works as it should have, unique ID will be assigned.

Following is an example code for app connection.

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

Reasons for failure for connecting app follows.

Unregister App connection

By unregistering from app, this permanently disconnect app and user registered in kakao platform which is similar to deleting account from app. After unregistration has been completed, recovering account is not possible and can not use kakao platform service any longer. However, user can register with new connection with new data.

When doing unregistering from app, all of user data managed by kakao platform will be deleted. But third party app saved data is not guaranteed to be so by kakao platform service. This must be deleted in third party app(For details, refer to policies and agreement). This is the main difference between deleting account from app and disconnecting account from app.

Following is a code for unregistering from app.

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

For disconnecting connected app, can arouse to failure as reasons below.

Requesting user information

This is a functionality for requesting user information, such as user ID and personal details. In order to use such functionality, user token is needed which can be retrieved after successful login.This is also based on the fact that app is connected.

User ID is user's unique ID by app, issued when connecting with app. Using such id, you can identify user in you app. This value will maintain as long as user does not disconnect app from account.

카카오계정 이메일을 사용하기 위해서는 서비스에서 이메일을 사용하도록 설정해야 하고 사용자의 동의도 필요합니다.

개발자 웹사이트에서 제공하는 대쉬보드의 설정 > 사용자 관리 > 동의항목 관리 에서 이메일 항목을 필수로 설정하고 이메일을 수집하는 목적을 정확하게 입력해야 합니다. 입력한 수집목적의 내용과 실제 서비스에서 해당 개인 정보를 사용하는 목적이 다를 경우 API서비스의 거부 사유가 될 수 있습니다. dev_016.png

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

  • 서비스에 제공되는 사용자의 카카오계정 이메일은 인증 받지 않은 이메일도 포합됩니다. 사용자 정보 요청시 이메일과 이메일 인증여부도 포함되어 있으니, 서비스에서는 이메일을 활용하기 전에 이메일 인증여부를 항상 확인해야 합니다.

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

  • 사용자가 카카오계정의 이메일 제공을 거부한 경우 사용자의 이메일은 제공되지 않습니다. 서비스 가입시 사용자의 이메일 정보가 필요하다면, 사용자로부터 직접 이메일을 입력받는 방법을 권장합니다.

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

Additional user information as stated below is provided by using kakao talk and kakaostory service through kakao platform service.

  • nickname: Kakaotalk or kakaostory nickname information
  • profile_image: Kakaotalk or kakaostory profile image URL
  • thumbnail_image: Thumbnail profile image URL

If needed, when connecting with app, specified additional information will be synced with Kakaotalk or KakaoStory service. Even if user has changed user information afterward in Kakaotalk or Kakaostory, such changes won't be affected.

If synchronization with kakaotalk or kakaostory is disabled, additional information will be blanked. Such additional information is interchangeable with different data anytime through User information settings. Manual synchronization with user information is also possible using Kakao platform service provided Kakao Talk or 카카오스토리 API. Setting for providing user's additional information by app can be found at Dashboard setting > user management > Setting for connecting app > linking with kakao account menu in developer website. dev_008.png

Following is an example code for retrieving user information. User id and additional information will be returned as KOUser object. 이메일을 수집하도록 설정한 경우 이메일 수집에 동의한 사용자에 한해서 이메일 정보가 반환됩니다.

[KOSessionTask meTaskWithCompletionHandler:^(KOUser* result, NSError *error) {
    if (result) {
        // success
        NSLog(@"userId=%@", result.ID);
        NSLog(@"nickName=%@", [result propertyForKey:KOUserNicknamePropertyKey]);

        if (result.email) {
            NSLog(@"email=%@", result.email);
        } else {
            // disagreed
        }
    } else {
        // failed
    }
}];

위와 같이 실행할 경우 해당 사용자의 (조회 가능한) 전체 정보가 반환됩니다. 얻고 싶은 정보만 지정하기 위해서는 meTaskWithPropertyKeys:completionHandler: 또는 meTaskWithSecureResource:propertyKeys:completionHandler: 메소드를 사용합니다. 이메일과 기본 부가정보 외에 내 애플리케이션 설정의 프로퍼티 관리에 추가된 프로퍼티 이름을 지정할 수 있습니다. 이메일과 기본 부가정보의 경우 다음과 같이 미리 정의된 키가 제공됩니다. KOUser.h 파일에 정의되어 있습니다.

설명
KOUserEmailPropertyKey 사용자 카카오계정의 이메일
KOUserIsVerifiedEmailPropertyKey 인증받은 카카오계정 이메일인지 여부
KOUserNicknamePropertyKey 카카오톡 또는 카카오스토리의 닉네임 정보
KOUserProfileImagePropertyKey 카카오톡 또는 카카오스토리의 프로필 이미지 URL
KOUserThumbnailImagePropertyKey 프로필 이미지의 썸네일 URL

다음은 사용자 정보 중 닉네임썸네일URL 및 개발자가 별도로 추가한 “age” 프로퍼티를 얻어오는 예제 코드입니다.

[KOSessionTask meTaskWithPropertyKeys:@[KOUserNicknamePropertyKey,
                                        KOUserThumbnailImagePropertyKey,
                                        @"age"]
                    completionHandler:^(KOUser* result, NSError *error) {
    if (result) {
        // success
        NSLog(@"nickName=%@", [result propertyForKey:KOUserNicknamePropertyKey]);
        NSLog(@"thumbnailURL=%@", [result propertyForKey:KOUserThumbnailImagePropertyKey]);
        NSLog(@"age=%@", [result propertyForKey:@"age"]);
    } else {
        // failed
    }
}];

로그인 또는 신규 가입 절차에 의해서 이메일 수집 동의를 받기 전에도 propertyKeys 지정을 통해 이메일을 수집할 수 있습니다. 이메일을 수집하도록 설정되어 있다면 다음과 같이 이메일을 지정할 경우 동의를 받지 않은 사용자에 한해서 동의창이 노출되고 이메일 수집 동의를 받을 수 있습니다.(동의 받은 사용자일 경우에는 동의창이 노출되지 않습니다.) 사용자가 이메일 수집에 동의하지 않은 경우 KOErrorCancelled 에러가 반환됩니다.

[KOSessionTask meTaskWithPropertyKeys:@[KOUserEmailPropertyKey]
                    completionHandler:^(KOUser* result, NSError *error) {
    if (result) {
        // success
        NSLog(@"email=%@", result.email);
    } else {
        switch (error.code) {
            case KOErrorCancelled:
                // disagreed or cancelled
                break;
            default:
                // failed
                break;
        }
    }
}];

Returnable error follows.

Saving user information

Saving user information is a feature to save particular information about user. Beside additional information kakao platform service provide, user data can be saved from custom information set in developer site. In order to use such functionality, user token is needed which can be retrieved after successful login.

There are user informations that can not be modified by saving user information method. Such as user id can not be modified.

This is an example code for retrieving user information, nickname and custom information, age. Custom information age category must be defined at dashboard setting > user management menu. Following example code is a code for saving nickname and custom information, 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.");
   }
}];

Returnable error is as below.

토큰 정보 얻기

로그인을 통해 얻은 사용자 토큰의 정보를 얻는 기능입니다. 호출에 성공할 경우 토큰 정보(사용자 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 : 2017-08-03