페이지 이동경로
  • 문서>
  • 카카오 로그인>
  • Flutter

카카오 로그인

Flutter

이 문서는 Kakao SDK for Flutter(이하 Flutter SDK)를 사용한 카카오 로그인 구현 방법을 안내합니다.

카카오 로그인 구현에 필요한 로그인 버튼 이미지는 [도구] > [리소스 다운로드]에서 제공합니다. 해당 로그인 버튼은 디자인 가이드를 참고하여 서비스 UI에 적합한 크기로 수정하여 사용할 수 있습니다.

시작하기 전에

구현 방식 선택

Flutter SDK는 다양한 사용자 환경에 대응할 수 있도록 두 가지 카카오 로그인 구현 방식을 제공합니다.

구현 방식 권장 환경 설명
기본 네이티브 앱 서비스 클라이언트에서 인가 코드 및 토큰 발급 모두 처리
Redirect 방식 웹 서비스 서비스 클라이언트에서 카카오 로그인 요청 시, 인가 코드가 발급되어 서비스 서버의 Redirect URI로 전달됨
서비스 서버에서 인가 코드로 토큰 발급을 요청해야 함
웹 브라우저 또는 웹뷰에서 카카오계정 로그인 팝업이 정상 출력되지 않을 수 있으며, Redirect 방식으로 구현 시 팝업 없이 서비스 페이지에서 카카오계정 로그인 페이지로 이동 가능

구현 방식별로 사용자의 카카오계정을 인증하는 방식에 따라 카카오톡으로 로그인, 카카오계정으로 로그인 두 가지 메서드를 제공합니다.

구현 방법 메서드 설명
카카오톡으로 로그인(권장) loginWithKakaoTalk()
loginWithKakaoAccount()
카카오톡에 연결된 카카오계정 및 인증 정보를 사용
사용자가 카카오계정 정보를 직접 입력하지 않아도 간편하게 로그인 가능
카카오계정으로 로그인 authorizeWithTalk()
authorize()
기본 웹 브라우저(Default Browser)를 통해 카카오계정 정보를 입력하고 로그인
사용자가 카카오계정 정보를 직접 입력하는 단계를 거침
사용자가 여러 개의 카카오계정을 사용하는 서비스, 카카오톡 미설치 또는 미지원 디바이스에서 사용

카카오톡 실행이 가능한 환경이라면 카카오톡으로 로그인 메서드인 loginWithKakaoTalk() 또는 authorizeWithTalk() 사용을 권장합니다. isKakaoTalkInstalled()로 카카오톡 실행 가능 여부를 확인할 수 있습니다. 해당 메서드 호출 결과의 의미는 다음과 같습니다.

  • true
    • 모바일 기기의 네이티브 앱에서 요청했고, 카카오톡이 설치돼 있는 경우
    • 모바일 기기의 웹 브라우저(웹뷰)에서 요청한 경우
  • false
    • 모바일 기기의 네이티브 앱에서 요청했고, 카카오톡이 설치돼 있지 않은 경우
    • 모바일 기기가 아닌 경우

각 인증 방법의 특징과 서비스의 사용자 로그인 동선을 고려하여 어느 인증 방법이 적합한지 판단합니다. 두 가지 인증 방법을 함께 사용할 수도 있습니다. 인증 방법에 따라 필요한 설정이나 예외 처리에 차이가 있으므로, 각 개발 가이드를 참고합니다.

패키지 설정

카카오 로그인 API를 사용하려면 설치를 참고하여 pubspec.yaml 파일에 Flutter SDK 전체 또는 카카오 로그인 패키지에 대한 의존성을 추가해야 합니다.

프로젝트 설정: Android

Android 디바이스에서 카카오 로그인을 사용하려면 ${Project} > android > app > src > AndroidManifest.xml 파일에 카카오 로그인 Redirect URI 설정이 필요합니다. 해당 파일의 application 하위에 새로운 activity를 아래 예제와 같이 추가합니다.

<activity 
    android:name="com.kakao.sdk.flutter.AuthCodeCustomTabsActivity"
    android:exported="true">
    <intent-filter android:label="flutter_web_auth">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- Redirect URI, "kakao${YOUR_NATIVE_APP_KEY}://oauth" 형식 -->
        <data android:scheme="kakao${YOUR_NATIVE_APP_KEY}" android:host="oauth"/>
    </intent-filter>
</activity>

카카오 로그인 Redirect URI는 해당 activityintent-filter 하위에 정의합니다. host 요소는 "oauth", scheme 요소는 "kakao${YOUR_NATIVE_APP_KEY}" 형식으로 입력합니다. ${YOUR_NATIVE_APP_KEY}부분에는 [내 애플리케이션] > [앱 키]에서 확인한 네이티브 앱 키를 입력합니다.

프로젝트 설정: iOS

iOS 디바이스에서 카카오 로그인을 사용하려면 다음 두 가지 설정이 모두 필요합니다.

  • 앱 실행 허용 목록 설정
    • ${Project} > ios 폴더를 우클릭하여 Xcode에서 프로젝트를 열고 설정
    • 설정 경로: [TARGET] > [Info] > [Custom iOS Target Properties]
    • 파일을 직접 수정하여 설정 시, Info.plist 파일 경로: ${Project} > ios > Runner > Info.plist
  • URL Schemes 설정
    • ${Project} > ios 폴더를 우클릭하여 Xcode에서 프로젝트를 열고 설정
    • 설정 경로: [TARGET] > [Info] > [URL Types] > [URL Schemes]

카카오 로그인 과정: Redirect 방식

Redirect 방식으로 카카오 로그인 구현 시, 서비스 서버에서 REST API 요청을 통해 토큰을 발급받아야 합니다. 아래는 Redirect 방식의 카카오톡으로 로그인 과정을 나타낸 시퀀스 다이어그램(Sequence diagram)입니다.

Redirect 방식 카카오 로그인 과정 Step 1. 인가 코드 받기
  1. isKakaoTalkInstalled() 메서드로 카카오톡 실행 가능 여부를 확인합니다.
    • 카카오톡 앱이 설치돼 있거나 설치 가능한 환경이라면 true를 반환합니다.
    • false 반환 시, 카카오계정으로 로그인하도록 분기 처리합니다.
  2. authorizeWithTalk() 호출 시 카카오톡이 실행됩니다.
    • 카카오톡이 설치돼 있지 않은 경우, 설치 페이지로 이동합니다.
  3. 카카오톡이 카카오 인증 서버에 동의 화면을 요청합니다.
  4. 카카오 인증 서버가 사용자에게 동의 화면을 출력하여 인가를 위한 사용자 동의를 요청합니다.
    • 동의 화면은 서비스 애플리케이션(이하 앱)의 동의 항목 설정에 따라 구성됩니다.
  5. 사용자가 필수 동의 항목, 이 외 원하는 동의 항목에 동의한 뒤 [동의하고 계속하기] 버튼을 누릅니다.
  6. 카카오 인증 서버는 간편 로그인 요청 시 지정된 Redirect URI로 인가 코드를 전달합니다.
Step 2. 토큰 받기
  1. 서비스 서버가 Redirect URI로 전달받은 인가 코드로 토큰 받기를 요청합니다.
  2. 카카오 인증 서버가 토큰을 발급해 서비스 서버에 전달합니다.
Step 3. 사용자 로그인 처리
주의

서비스의 사용자 로그인 처리는 서비스에서 자체 구현해야 합니다. 이 문서는 사용자 로그인 처리 구현 시 참고할 수 있는 정보를 제공합니다.

  • 서비스 서버가 발급받은 액세스 토큰으로 사용자 정보 가져오기를 요청해 사용자의 회원번호 및 정보를 조회하여 서비스 회원인지 확인합니다.
  • 서비스 회원 정보 확인 결과에 따라 서비스 로그인 또는 회원 가입 과정을 진행합니다.
  • 이 외 서비스에서 필요한 로그인 절차를 수행한 후, 카카오 로그인한 사용자의 서비스 로그인 처리를 완료합니다.

카카오 로그인

카카오톡으로 로그인

기본 정보
사전 설정 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
Redirect URI 등록(Web 플랫폼 사용 시 필수)
동의 항목
OpenID Connect 활성화(선택)
필요:
필수 동의 항목
isKakaoTalkInstalled()
loginWithKakaoTalk()
KakaoException

사용자에게 카카오톡 앱을 통한 로그인을 요청합니다. UserApiloginWithKakaoTalk()을 호출합니다. await 키워드를 사용하여 사용자의 로그인 과정이 완료되기를 기다린 다음 서비스 로직을 수행하도록 할 수 있습니다.

loginWithKakaoTalk()이 호출되면 Flutter SDK가 카카오톡을 실행하고 사용자에게 앱 이용 관련 동의를 구하는 동의 화면을 출력합니다. 동의 화면에서 사용자가 모든 필수 항목에 동의하고 [동의하고 계속하기]를 선택하면 인가 코드가 발급되고, Flutter SDK가 인가 코드로 토큰을 발급받아 로그인을 완료합니다. OpenID Connect를 사용하는 앱인 경우, ID 토큰을 함께 발급받습니다. 발급된 토큰은 Flutter SDK가 TokenManager를 통해 내부적으로 관리하며, 로그인이 필요한 카카오 API 호출 시 사용합니다.

사용자가 동의 화면에서 로그인을 취소하거나, 다른 에러가 발생한 경우에는 레퍼런스를 참고하여 각각 예외 처리합니다. 카카오 로그인 구현 예제를 참고합니다.

try {
  OAuthToken token = await UserApi.instance.loginWithKakaoTalk();
  print('카카오톡으로 로그인 성공 ${token.accessToken}');
} catch (error) {
  print('카카오톡으로 로그인 실패 $error');
}

카카오계정으로 로그인

기본 정보
사전 설정 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
Redirect URI 등록(Web 플랫폼 사용 시 필수)
동의 항목
OpenID Connect 활성화(선택)
필요:
필수 동의 항목
loginWithKakaoAccount()
KakaoException

사용자에게 카카오계정 정보 입력을 통한 로그인을 요청합니다. UserApiloginWithKakaoAccount()를 호출합니다.

loginWithKakaoAccount()가 호출되면 Flutter SDK가 기본 브라우저를 사용해 카카오계정 로그인 페이지를 엽니다. 해당 페이지에서 사용자가 ID와 비밀번호를 입력해 카카오계정으로 로그인하면 앱 이용 관련 동의를 구하는 동의 화면이 출력됩니다. 동의 화면에서 사용자가 모든 필수 항목에 동의하고 [동의하고 계속하기]를 선택하면 인가 코드가 발급되고, Flutter SDK가 인가 코드로 토큰을 발급받아 로그인을 완료합니다. OpenID Connect를 사용하는 앱인 경우, ID 토큰을 함께 발급받습니다. 발급된 토큰은 Flutter SDK가 TokenManager를 통해 내부적으로 관리하며, 로그인이 필요한 카카오 API 호출 시 사용합니다.

사용자가 동의 화면에서 로그인을 취소하거나, 다른 에러가 발생한 경우에는 레퍼런스를 참고하여 각각 예외 처리합니다. 카카오 로그인 구현 예제를 참고합니다.

try {
  OAuthToken token = await UserApi.instance.loginWithKakaoAccount();
  print('카카오계정으로 로그인 성공 ${token.accessToken}');
} catch (error) {
  print('카카오계정으로 로그인 실패 $error');
}

카카오톡으로 로그인: Redirect 방식

기본 정보
사전 설정 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
Redirect URI 등록
동의 항목
OpenID Connect 활성화(선택)
필요:
필수 동의 항목
isKakaoTalkInstalled()
authorizeWithTalk()
KakaoException

카카오톡으로 로그인Redirect 방식으로 요청합니다. AuthCodeClientauthorizeWithTalk()을 호출합니다.

authorizeWithTalk()이 호출되면 Flutter SDK가 카카오톡을 실행하고 사용자에게 앱 이용 관련 동의를 구하는 동의 화면을 출력합니다. 동의 화면에서 사용자가 모든 필수 항목에 동의하고 [동의하고 계속하기]를 선택하면 Redirect URI로 인가 코드가 전달됩니다. 발급받은 인가 코드로 서비스 서버에서 토큰 받기를 요청해야 카카오 로그인을 완료할 수 있습니다. 카카오 로그인 과정을 참고합니다.

try {
  await AuthCodeClient.instance.authorizeWithTalk(
    redirectUri: '${REDIRECT_URI}',
  );
} catch (error) {
  print('카카오톡으로 로그인 실패 $error');
}

카카오계정으로 로그인: Redirect 방식

기본 정보
사전 설정 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
Redirect URI 등록
동의 항목
OpenID Connect 활성화(선택)
필요:
필수 동의 항목
authorize()
KakaoException

카카오계정으로 로그인Redirect 방식으로 요청합니다. AuthCodeClientauthorize()를 호출합니다.

authorize()가 호출되면 Flutter SDK가 기본 브라우저를 사용해 카카오계정 로그인 페이지를 엽니다. 해당 페이지에서 사용자가 ID와 비밀번호를 입력해 카카오계정으로 로그인하면 앱 이용 관련 동의를 구하는 동의 화면이 출력됩니다. 동의 화면에서 사용자가 모든 필수 항목에 동의하고 [동의하고 계속하기]를 선택하면 Redirect URI로 인가 코드가 전달됩니다. 발급받은 인가 코드로 서비스 서버에서 토큰 받기를 요청해야 카카오 로그인을 완료할 수 있습니다. 카카오 로그인 과정을 참고합니다.

try {
  await AuthCodeClient.instance.authorize(
    redirectUri: '${REDIRECT_URI}',
  );
} catch (error) {
  print('카카오계정으로 로그인 실패 $error');
}

토큰 받기

Redirect 방식authorizeWithTalk() 또는 authorize() 메서드로 카카오 로그인 요청 시, 서비스 서버에서 인가 코드를 사용해 REST API로 토큰 받기를 요청하여 토큰을 발급받아야 합니다. OpenID Connect를 사용하는 앱인 경우, 토큰 받기를 통해 ID 토큰을 함께 발급받을 수 있습니다.

  • 토큰은 액세스 토큰(Access token), 리프레시 토큰(Refresh token), ID 토큰(ID token) 세 종류입니다.

서비스 서버에서 토큰을 발급받은 후, 서비스 서버에서 액세스 토큰으로 사용자 정보 가져오기를 호출해 회원 가입 및 로그인에 필요한 사용자 정보를 요청할 수 있습니다. 액세스 토큰을 서비스 클라이언트로 전달해 토큰 할당하면, 서비스 클라이언트에서도 Flutter SDK를 통한 카카오 API 요청에 사용할 수 있습니다.

주의: 앱 키

서비스 서버에서 REST API로 토큰 받기사용자 정보 가져오기 등 API를 요청할 때는 REST API 키를 사용해야 합니다.

토큰 할당하기

기본 정보
레퍼런스
setToken()
OAuthToken

클라이언트에서도 Flutter SDK를 통해 카카오 API를 호출할 수 있도록 서비스 서버로부터 전달받은 토큰을 토큰매니저에 할당합니다. 토큰 할당은 Redirect 방식인 authorizeWithTalk() 또는 authorize() 메서드로 카카오 로그인을 요청한 경우에만 필요합니다. TokenManagerProvidersetToken() 메서드를 호출합니다. 아래 예제를 참고합니다.

// 서비스 서버가 전달한 response 데이터에서 토큰 획득 후 Flutter SDK에서 사용하는 타입으로 변환
var tokenResponse = AccessTokenResponse.fromJson(response);
var token = OAuthToken.fromResponse(tokenResponse);

// 토큰 저장
TokenManagerProvider.instance.manager.setToken(token);

카카오 로그인 구현 예제

Flutter SDK로 카카오 로그인 구현 시, 카카오 로그인 과정을 참고해 다음 두 가지 조건을 확인하는 로직을 포함할 것을 권장합니다.

  1. 기존 로그인을 통해 발급받은 토큰이 있는지 확인
    • 이미 로그인하여 유효한 토큰을 갖고 있는 사용자는 다시 로그인하지 않도록 함
    • 기존 토큰이 있는 경우에도 만료되었을 수 있으므로 유효성 확인 필요
  2. isKakaoTalkInstalled() 메서드로 카카오톡 실행 가능 여부 확인
    • 카카오톡 실행 가능 환경에서는 ID, 비밀번호 입력 없이 간편하게 로그인할 수 있도록 함
    • 카카오톡에 연결(로그인)된 카카오계정이 없는 경우, 카카오계정으로 로그인 가능하도록 함

아래는 카카오 로그인 구현 예제입니다.

// 카카오 로그인 구현 예제

// 카카오톡 실행 가능 여부 확인
// 카카오톡 실행이 가능하면 카카오톡으로 로그인, 아니면 카카오계정으로 로그인
if (await isKakaoTalkInstalled()) {
  try {
      await UserApi.instance.loginWithKakaoTalk();
      print('카카오톡으로 로그인 성공');
  } catch (error) {
    print('카카오톡으로 로그인 실패 $error');

    // 사용자가 카카오톡 설치 후 디바이스 권한 요청 화면에서 로그인을 취소한 경우,
    // 의도적인 로그인 취소로 보고 카카오계정으로 로그인 시도 없이 로그인 취소로 처리 (예: 뒤로 가기)
    if (error is PlatformException && error.code == 'CANCELED') {
        return;
    }
    // 카카오톡에 연결된 카카오계정이 없는 경우, 카카오계정으로 로그인
    try {
        await UserApi.instance.loginWithKakaoAccount();
        print('카카오계정으로 로그인 성공');
    } catch (error) {
        print('카카오계정으로 로그인 실패 $error');
    }
  }
} else {
  try {
    await UserApi.instance.loginWithKakaoAccount();
    print('카카오계정으로 로그인 성공');
  } catch (error) {
    print('카카오계정으로 로그인 실패 $error');
  }
}

추가 기능

카카오 로그인 요청 시 사용할 수 있는 추가 기능은 다음과 같습니다.

추가 항목 동의 받기
자동 추가 동의 요청

Flutter SDK는 API 요청 시 사용자 동의가 필요한 경우, 자동으로 필요한 동의 항목의 동의 화면을 호출해 사용자에게 동의 요청합니다. 단, 자동으로 동의 화면을 호출하거나 토큰을 갱신할 수 없는 웹 환경이거나, API 호출 전 추가 동의를 받으려면 직접 추가 항목 동의 받기를 요청해야 합니다.

추가 항목 동의 받기는 사용자가 동의하지 않은 동의 항목에 대한 추가 동의를 요청할 때 사용하는 추가 기능입니다. 카카오 로그인 구현 방식에 따라 다음 메서드 중 하나를 사용합니다.

  • 기본 구현 방식 사용 시: UserApiloginWithNewScopes() 호출
  • Redirect 방식 사용 시: AuthCodeClientauthorizeWithNewScopes() 호출

필수 파라미터로 사용자에게 동의를 요청할 동의 항목의 키를 문자열 리스트(List<String>)에 담아 전달해야 합니다. authorizeWithNewScopes() 사용 시, 토큰 받기를 요청해 카카오 로그인을 재완료해야 합니다. 아래 예제를 참고합니다.

loginWithNewScopes()
authorizeWithNewScopes()
User user;
  try {
    user = await UserApi.instance.me();
  } catch (error) {
    print('사용자 정보 요청 실패 $error');
    return;
  }

  // 사용자의 추가 동의가 필요한 사용자 정보 동의 항목 확인
  List<String> scopes = [];

  if (user.kakaoAccount?.emailNeedsAgreement == true) {
    scopes.add('account_email');
  }
  if (user.kakaoAccount?.birthdayNeedsAgreement == true) {
    scopes.add("birthday");
  }
  if (user.kakaoAccount?.birthyearNeedsAgreement == true) {
    scopes.add("birthyear");
  }
  if (user.kakaoAccount?.ciNeedsAgreement == true) {
    scopes.add("account_ci");
  }
  if (user.kakaoAccount?.phoneNumberNeedsAgreement == true) {
    scopes.add("phone_number");
  }
  if (user.kakaoAccount?.profileNeedsAgreement == true) {
    scopes.add("profile");
  }
  if (user.kakaoAccount?.ageRangeNeedsAgreement == true) {
    scopes.add("age_range");
  }

  if (scopes.length > 0) {
    print('사용자에게 추가 동의 받아야 하는 항목이 있습니다');

    // OpenID Connect 사용 시
    // scope 목록에 "openid" 문자열을 추가하고 요청해야 함
    // 해당 문자열을 포함하지 않은 경우, ID 토큰이 재발급되지 않음
    // scopes.add("openid")

    // scope 목록을 전달하여 추가 항목 동의 받기 요청
    // 지정된 동의 항목에 대한 동의 화면을 거쳐 다시 카카오 로그인 수행
    OAuthToken token;
    try {
      token = await UserApi.instance.loginWithNewScopes(scopes);
      print('현재 사용자가 동의한 동의 항목: ${token.scopes}');
    } catch (error) {
      print('추가 동의 요청 실패 $error');
      return;
    }

    // 사용자 정보 재요청
    try {
      User user = await UserApi.instance.me();
      print('사용자 정보 요청 성공'
          '\n회원번호: ${user.id}'
          '\n닉네임: ${user.kakaoAccount?.profile?.nickname}'
          '\n이메일: ${user.kakaoAccount?.email}');
    } catch (error) {
      print('사용자 정보 요청 실패 $error');
    }
  }
// 이메일, 성별 추가 항목 동의 받기
try {
  await AuthCodeClient.instance.authorizeWithNewScopes(
    scopes: [account_email, gender],
    redirectUri: '${REDIRECT_URI}',
  );
} catch (error) {
  print('추가 항목 동의 받기 실패 $error');
}
주의: OpenID Connect

OpenID Connect를 사용하는 앱의 경우, 추가 항목 동의 받기 요청 시 동의 항목 키를 전달하는 scope 파라미터 값에 openid를 반드시 포함해야 합니다. 해당 파라미터 값을 포함하지 않을 경우, ID 토큰이 재발급되지 않습니다. (참고: scope 파라미터)


약관 선택해 동의 받기
카카오싱크 전용

카카오싱크를 도입한 서비스만 사용할 수 있는 기능입니다.

약관 선택해 동의 받기는 카카오 로그인 동의 화면에 포함할 서비스 약관을 지정하는 추가 기능입니다. 사용자의 서비스 가입 시나리오에 따라 앱에 등록된 서비스 약관 중 특정 서비스 약관을 지정해 동의받고자 할 때 사용합니다. 인가 코드 받기 요청 시 serviceTerms 파라미터로 동의 화면에 포함할 서비스 약관 태그 목록을 지정합니다.

// 동의받을 약관 태그 목록
List<String> serviceTerms = ['${SERVICE_TERM_TAG_1}','${SERVICE_TERM_TAG_2}'];

try {
  OAuthToken token = await UserApi.instance
      .loginWithKakaoTalk(serviceTerms: serviceTerms);
  print('로그인 성공 ${token.accessToken}');
} catch (error) {
  print('로그인 실패 $error');
}

OpenID Connect ID 토큰 발급하기

OpenID Connect 사용 서비스인 경우, OpenID Connect 활성화 설정이 되어 있다면 별도 파라미터 없이도 ID 토큰을 함께 발급받을 수 있습니다. OpenID Connect 사용 시 ID 토큰 재생 공격을 방지하기 위해 nonce 파라미터 사용을 권장합니다. 단, 추가 항목 동의 받기 요청 시에는 scope 파라미터에 openid를 포함해야 ID 토큰 재발급이 가능합니다. (참고: scope 파라미터)

기존 로그인 여부와 상관없이 로그인하기

보안을 위해 기존의 로그인 여부와 상관없이 사용자에게 재인증을 요청할 수 있습니다. prompts[Prompt.login]으로 지정하여 카카오계정으로 로그인을 요청합니다. 이 요청은 사용자가 해당 디바이스의 동일한 웹 브라우저에서 이미 카카오계정으로 로그인한 상태라도 로그인 페이지를 출력합니다.

try {
  OAuthToken token = await UserApi.instance
      .loginWithKakaoAccount(prompts: [Prompt.login]);
  print('로그인 성공 ${token.accessToken}');
} catch (error) {
  print('로그인 실패 $error');
}

토큰 존재 여부 확인하기

기본 정보

사전 설정 카카오 로그인 레퍼런스
플랫폼 등록
카카오 로그인 활성화
필요 hasToken()

Flutter SDK에 기존에 발급받아 저장된 토큰이 있는지 확인합니다. AuthApihasToken()을 호출합니다.

hasToken()을 통해 앱 실행, 또는 카카오 로그인이 필요한 API를 호출하기 전 기존 토큰 존재 여부를 확인할 수 있습니다. 호출 결과가 true라면 기존에 발급받은 액세스 토큰 또는 리프레시 토큰이 존재하는 상태이고, false라면 토큰이 없는 상태입니다.

if (await AuthApi.instance.hasToken()) {
  try {
    AccessTokenInfo tokenInfo =
        await UserApi.instance.accessTokenInfo();
    print('토큰 유효성 체크 성공 ${tokenInfo.id} ${tokenInfo.expiresIn}');
  } catch (error) {
    if (error is KakaoException && error.isInvalidTokenError()) {
      print('토큰 만료 $error');
    } else {
      print('토큰 정보 조회 실패 $error');
    }

    try {
      // 카카오 계정으로 로그인
      OAuthToken token = await UserApi.instance.loginWithKakaoAccount();
      print('로그인 성공 ${token.accessToken}');
    } catch (error) {
      print('로그인 실패 $error');
    }
  }
} else {
  print('발급된 토큰 없음');
  try {
    OAuthToken token = await UserApi.instance.loginWithKakaoAccount();
    print('로그인 성공 ${token.accessToken}');
  } catch (error) {
    print('로그인 실패 $error');
  }
}

결과가 true인 경우에도 토큰 정보 보기를 호출해 토큰이 유효한지 확인해야 합니다. 토큰이 유효하지 않다면 다시 카카오 로그인을 통해 새로운 토큰을 발급받아야 합니다.

  • 요청 성공, 액세스 토큰 정보 반환
    • 액세스 토큰이 유효한 상태이므로 사용자 로그인 불필요
    • 해당 액세스 토큰으로 카카오 API 호출 가능
  • 에러 발생
    • 액세스 토큰 및 리프레시 토큰이 유효하지 않아 사용자 로그인 필요
    • 각 에러에 맞는 처리 필요, 문제 해결 및 레퍼런스 참고

토큰 정보 보기

기본 정보

사전 설정 카카오 로그인 레퍼런스
플랫폼 등록
카카오 로그인 활성화
필요 accessTokenInfo()
AccessTokenInfo

현재 Flutter SDK에 저장 중인 액세스 토큰의 정보를 조회합니다. UserApiaccessTokenInfo()를 호출합니다.

요청 성공 시, 앱 ID, 회원번호, 남은 유효시간(단위: 초) 정보를 담은 AccessTokenInfo 객체가 반환됩니다. 액세스 토큰이 만료되었거나 존재하지 않는 경우에는 에러를 반환하므로, 기존 액세스 토큰의 만료 여부를 확인하는 용도로도 사용할 수 있습니다.

try {
  AccessTokenInfo tokenInfo = await UserApi.instance.accessTokenInfo();
  print('토큰 정보 보기 성공'
        '\n회원정보: ${tokenInfo.id}'
        '\n만료시간: ${tokenInfo.expiresIn} 초');
} catch (error) {
  print('토큰 정보 보기 실패 $error');
}

로그아웃

기본 정보

사전 설정 카카오 로그인 레퍼런스
플랫폼 등록
카카오 로그인 활성화
필요 logout()

Flutter SDK에 저장된 토큰을 삭제하여 사용자를 로그아웃 처리합니다. UserApilogout()을 호출합니다.

요청 성공 시, 로그아웃 처리된 사용자의 회원번호를 받습니다. 로그아웃은 성공 여부와 관계없이 Flutter SDK에 저장된 토큰을 삭제하는 점에 유의합니다. 토큰 삭제 시, 더 이상 해당 토큰 값을 사용해 카카오 API를 호출할 수 없습니다.

try {
  await UserApi.instance.logout();
  print('로그아웃 성공, SDK에서 토큰 삭제');
} catch (error) {
  print('로그아웃 실패, SDK에서 토큰 삭제 $error');
}

연결 끊기

기본 정보

사전 설정 카카오 로그인 레퍼런스
플랫폼 등록
카카오 로그인 활성화
필요 unlink()
UserIdResponse

앱과 사용자의 연결 상태를 해제합니다. UserApiunlink()를 호출합니다.

요청 성공 시, 앱과 연결이 해제된 사용자의 회원번호를 포함한 UserIdResponse 객체가 반환됩니다. 또한 로그아웃 처리가 함께 이뤄져 Flutter SDK에 저장된 토큰이 삭제됩니다.

try {
  await UserApi.instance.unlink();
  print('연결 끊기 성공, SDK에서 토큰 삭제');
} catch (error) {
  print('연결 끊기 실패 $error');
}

연결 끊기를 직접 호출한 경우가 아닌, 사용자가 서비스와의 연결을 직접 끊었을 때 알림을 받으려면 연결 끊기 알림 받기 기능을 사용합니다. 자세한 구현 방법 및 콜백 요청 정보는 연결 끊기 알림을 참고합니다.

사용자 정보 가져오기

기본 정보

사전 설정 카카오 로그인 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
사용자 정보를 요청할 모든 동의 항목
me()
User

현재 로그인한 사용자의 정보를 불러옵니다. UserApime()를 호출합니다.

요청 성공 시, 사용자 정보가 담긴 User 객체가 반환됩니다. 사용자 정보에서 제공 가능한 사용자 정보의 종류를 확인할 수 있습니다. 다음과 같은 경우에는 사용자 정보의 값이 존재하지 않을 수 있으므로 유의합니다.

  • 동의 항목 미설정
  • 사용자 미동의
  • 사용자가 카카오에 제공하지 않은 정보
try {
  User user = await UserApi.instance.me();
  print('사용자 정보 요청 성공'
        '\n회원번호: ${user.id}'
        '\n닉네임: ${user.kakaoAccount?.profile?.nickname}'
        '\n이메일: ${user.kakaoAccount?.email}');
} catch (error) {
  print('사용자 정보 요청 실패 $error');
}

사용자 정보 저장하기

기본 정보

사전 설정 카카오 로그인 레퍼런스
플랫폼 등록
카카오 로그인 활성화
사용자 프로퍼티
필요 updateProfile()
User.properties

사용자 프로퍼티 값을 저장합니다. UserApiupdateProfile()을 호출합니다.

요청 시 저장할 사용자 프로퍼티의 키와 값을 Map 형식으로 전달해야 합니다. 요청 성공 시 반환 값은 없으며, 사용자 정보 가져오기를 통해 properties에 저장된 사용자 프로퍼티를 확인할 수 있습니다.

try {
  // 저장할 사용자 프로퍼티
  Map<String, String> properties = {'${CUSTOM_PROPERTY_KEY}': '${CUSTOM_PROPERTY_VALUE}'};
  await UserApi.instance.updateProfile(properties);
  print('사용자 정보 저장 성공');
} catch (error) {
  print('사용자 정보 저장 실패 $error');
}

배송지 가져오기

사전 설정 카카오 로그인 사용자 동의 레퍼런스
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
배송지 정보(shipping_address)
shippingAddresses()
UserShippingAddresses

현재 로그인한 사용자의 배송지 정보를 가져옵니다. UserApishippingAddresses()를 호출합니다. 필요에 따라 다음 파라미터를 사용할 수 있습니다.

Name Type Description Required
fromUpdatedAt DateTime 여러 페이지에 걸쳐 응답이 제공될 때, 기준이 되는 배송지 updated_at 시각
해당 시각(미포함) 이전에 수정된 배송지부터 조회
이전 페이지의 마지막 배송지의 updated_at을 다음 페이지 입력 값으로 사용
값을 0으로 전달하면 처음부터 조회
X
pageSize int 2 이상, 한 페이지에 포함할 배송지 개수
기본 값 10
X

아래는 배송지 가져오기 예제로, 사용자가 [배송지 정보] 동의 항목에 동의하지 않았다면 동의 요청 후 다시 배송지 정보를 가져오는 과정을 포함합니다.

// 배송지 가져오기
UserShippingAddresses userShippingAddress;
try {
  userShippingAddress = await UserApi.instance.shippingAddresses();
} catch (error) {
  print('배송지 조회 실패 $error');
  return;
}

// 사용자의 배송지 정보 동의 항목 동의 여부에 따라 응답 처리
if (userShippingAddress.shippingAddresses != null) {
  print('배송지 조회 성공'
        '\n회원번호: ${userShippingAddress.userId}'
        '\n배송지: \n${userShippingAddress.shippingAddresses?.join('\n')}');
} else if (!userShippingAddress.needsAgreement) {
  print('사용자 카카오계정에 배송지 정보 없음'
        '배송지 정보가 꼭 필요하다면 동의 항목 설정에서 수집 후 제공 기능을 활성화 해 보세요.');
} else if (userShippingAddress.needsAgreement) {
  print('사용자에게 배송지 제공 동의를 받아야 합니다');

  // 배송지 동의 항목의 ID
  List<String> scopes = ['shipping_address'];

  // 사용자에게 배송지 정보 제공을 위한 동의 요청
  OAuthToken token;
  try {
    token = await UserApi.instance.loginWithNewScopes(scopes);
    print('사용자가 동의한 동의 항목: ${token.scopes}');
  } catch (error) {
    print('배송지 정보 동의 요청 실패 $error');
  }

  // 사용자 동의 후 다시 배송지 정보 가져오기
  try {
    UserShippingAddresses userShippingAddresses =
        await UserApi.instance.shippingAddresses();
    print('배송지 조회 성공'
          '\n회원번호: ${userShippingAddresses.userId}'
          '\n${userShippingAddresses.shippingAddresses?.join('\n')}');
  } catch (error) {
    print('배송지 조회 실패 $error');
  }
}

요청 성공 시 사용자 회원번호와 배송지 정보를 담은 UserShippingAddresses 객체를 받습니다. UserShippingAddresses는 각각의 배송지 정보를 담은 ShippingAddress 객체의 리스트(List)를 포함합니다.

응답에 ShippingAddress 값이 없다면 needsAgreement 값을 참고해 사용자로부터 동의받아야 하는지 판단합니다. 해당 값이 true라면 사용자의 동의를 거쳐 배송지 정보를 받을 수 있으므로, 추가 항목 동의 받기 기능을 사용해 동의 및 배송지 정보를 받습니다. false라면 사용자의 동의 여부와 관계없이 배송지 정보를 받을 수 없는 상태이므로, 자체적으로 사용자로부터 배송지 정보를 수집해야 합니다. (참고: 사용자 동의 시 정보 제공 가능 여부)

동의 내역 확인하기

기본 정보

사전 설정 카카오 로그인 레퍼런스
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 scopes()
ScopeInfo

사용자가 동의한 동의 항목의 상세 정보 목록을 조회합니다. UserApiscopes()를 호출합니다.

요청 성공 시 [내 애플리케이션] > [카카오 로그인] > [동의 항목]에 설정된 동의 항목의 목록, 사용자가 동의한 동의 항목의 상세 정보가 담긴 ScopeInfo 객체가 반환됩니다. 사용자가 기존에 동의했던 동의 항목이라면 현재 앱에 사용하도록 설정돼 있지 않아도 응답에 포함됩니다.

try {
  ScopeInfo scopeInfo = await UserApi.instance.scopes();
  print('동의 정보 확인 성공'
        '\n현재 사용자가 동의한 항목: ${scopeInfo.scopes}');
} catch (error) {
  print('동의 내역 확인 실패 $error');
}

특정 동의 항목의 사용자 동의 여부를 확인하려면 scopes() 호출 시 scope 파라미터에 해당 동의 항목의 키를 포함한 문자열 리스트(List<String>)를 전달합니다. 아래 예제를 참고합니다.

List<String> scopes = ['account_email', 'friends'];
try {
  ScopeInfo scopeInfo = await UserApi.instance.scopes(scopes: scopes);
  print('동의 정보 확인 성공'
        '\n현재 사용자가 동의한 항목: ${scopeInfo.scopes}');
} catch (error) {
  print('동의 내역 확인 실패 $error');
}

동의 철회하기

기본 정보

사전 설정 카카오 로그인 레퍼런스
플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 revokeScopes()
ScopeInfo

사용자가 동의한 항목에 대해 동의를 철회합니다. 동의 내역 확인하기를 통해 조회한 동의 항목 정보 중 동의 철회 가능 여부(revocable) 값이 true인 동의 항목만 철회 가능합니다. 동의 철회가 불가능한 동의 항목을 대상으로 요청한 경우 에러 응답을 받습니다.

UserApirevokeScopes()를 호출합니다. 요청 시 scopes 파라미터로 동의를 철회할 동의 항목의 키를 문자열 리스트(List<String>)를 전달해야 합니다.

요청 성공 시 [내 애플리케이션] > [카카오 로그인] > [동의 항목]에 설정된 동의 항목의 목록, 동의 철회 반영 후 사용자가 동의한 동의 항목의 상세 정보가 담긴 ScopeInfo 객체가 반환됩니다.

List<String> scopes = ['account_email', 'friends'];
try {
  ScopeInfo scopeInfo =
      await UserApi.instance.revokeScopes(scopes: scopes);
  print('동의 철회 성공'
        '\n현재 사용자가 동의한 항목 ${scopeInfo.scopes}');
} catch (error) {
  print('동의 철회 실패 $error');
}

동의한 약관 확인하기

카카오싱크 전용

카카오싱크를 도입한 서비스만 사용할 수 있는 기능입니다.

기본 정보
사전 설정 카카오 로그인 레퍼런스
플랫폼 등록
카카오 로그인 활성화
동의 항목
약관
필요 serviceTerms()
UserServiceTerms

현재 로그인한 사용자가 동의한 약관 목록을 가져옵니다. UserApiserviceTerms()를 호출합니다.

try {
  UserServiceTerms userServiceTerms =
      await UserApi.instance.serviceTerms();
  print('동의한 약관 확인하기 성공'
        '\n회원정보: ${userServiceTerms.userId}'
        '\n동의한 약관: \n${userServiceTerms.allowedServiceTerms?.join('\n')}');
} catch (error) {
  print('동의한 약관 확인하기 실패 $error');
}

요청 성공 시, 사용자 회원번호와 동의한 약관의 태그 목록을 담은 UserServiceTerms 객체가 반환됩니다. 사용자가 동의한 약관은 UserServiceTerms 하위의 allowedServiceTerms태그 값으로 포함됩니다.

고급: 연결하기

기본 정보

사전 설정 카카오 로그인 권한 레퍼런스
플랫폼 등록
카카오 로그인 활성화
필요 필요:
수동 연결 설정 권한
signup()

주의: 자동 연결 사용 여부 확인

연결하기는 자동 연결을 사용하지 않는 앱에서만 사용하는 API입니다. 사용 전 REST API 개발 가이드를 통해 사용 여부와 주의사항을 확인해야 합니다.

자동 연결을 [사용 안함]으로 설정한 앱에서 앱과 사용자를 수동으로 연결할 때 사용합니다. UserApisignup()을 호출합니다.

현재 로그인한 사용자가 연결하기 API를 통해 앱과 연결되어야 하는지 확인하려면 사용자 정보 가져오기 응답의 hasSignedUp 값을 확인하여 다음과 같이 처리합니다.

  • true: 이미 사용자와 앱이 연결되어 있으므로 다시 연결하기를 호출하지 않습니다.
  • false: 사용자와 앱이 연결되지 않은 상태이므로 signup()을 호출해 사용자와 앱을 연결해야 합니다.
  • null: 자동 연결을 사용 중인 앱이므로 연결하기가 불필요합니다.

요청 성공 시, 앱과 사용자 카카오계정의 연결 상태가 연결 대기에서 연결로 변경됩니다. 반환되는 값은 없습니다.

try {
  await UserApi.instance.signup();
  print('연결 성공');
} catch (error) {
  print('연결 실패 $error');
}

더보기