카카오 로그인

로그인하기

카카오 로그인으로 회원가입, 로그인, 추가 동의 받기, 약관 동의 받기 등을 할 수 있습니다.

사용법

login() 함수를 호출하면 바로 로그인을 시작합니다.

Android와 iOS에서 사용자가 로그인 방식을 직접 선택하게 하려면 로그인 방식 선택 화면을 사용합니다.

import { login } from '@react-native-kakao/user';

...

login()

인자

모든 인자는 선택 사항입니다.

• serviceTerms: 카카오 로그인 동의 화면에 포함할 서비스 약관을 지정하는 추가 기능입니다. 사용자의 서비스 가입 시나리오에 따라 앱에 등록된 서비스 약관 중 특정 약관을 지정해 동의받을 때 사용합니다. 카카오 로그인 요청 시 serviceTerms 파라미터로 동의 화면에 포함할 서비스 약관 태그 목록을 지정합니다. 요청 시 [필수 동의]로 설정된 서비스 약관을 하나 이상 포함해야 동의 화면을 출력하고 사용자에게 동의받을 수 있습니다.

정보

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

• prompts: 플래그를 전달해 로그인 과정을 제어할 수 있습니다.

Login, Create, Cert, SelectAccount를 string[]으로 전달할 수 있습니다.

각 값의 자세한 의미는 공식 문서를 참고하세요.

정보

카카오톡 대신 카카오 계정으로 로그인을 시도할 때 전달됩니다.

• scopes: 사용자에게 추가 동의를 받을 때 사용합니다. 동의가 필요한 항목을 전달합니다.

자세한 내용은 공식 문서 를 참고하세요.

me() 함수의 xxxNeedsAgreement 속성을 확인해 추가 동의가 필요한 항목을 찾을 수 있습니다.

scopes를 전달하면 항상 카카오 계정으로 로그인을 실행합니다.

• useKakaoAccountLogin: 항상 카카오톡이 아닌 카카오 계정으로 로그인을 시도합니다.

• android.requestCode: Android SDK에 전달할 카카오톡 로그인 요청 코드예요. -2147483648부터 2147483647까지의 32비트 정수를 받아요. 생략하면 카카오 SDK의 기본 코드를 사용해요. 현재 Android SDK 2.25.1은 이 값을 진단 로그에만 사용하며, 결과 콜백을 구분하지 않아요. 카카오계정 로그인과 추가 동의에는 적용하지 않으며, iOS와 웹에서도 사용하지 않아요.

await login({ android: { requestCode: 20001 } });

• ios.launchMethod: iOS에서 카카오톡으로 전환할 방식을 UniversalLink 또는 CustomScheme으로 지정합니다. 기본값은 UniversalLink입니다. 카카오톡을 사용할 수 없거나 카카오계정 로그인을 요청한 경우에는 적용하지 않으며, Android와 웹에서도 사용하지 않습니다.

await login({ ios: { launchMethod: 'CustomScheme' } });

이 옵션은 카카오톡을 여는 방식입니다. 앱으로 돌아오는 콜백 URL을 바꾸려면 SDK 초기화의 customScheme을 설정합니다.

• channelPublicIds: 로그인 동의 화면에 보여줄 카카오톡 채널 프로필 ID를 string[]으로 지정합니다. Android·iOS·웹에서 같은 옵션을 사용하며, 생략하거나 빈 배열을 전달하면 기본 로그인으로 동작합니다.

카카오와 사용 협의를 마친 제휴 앱에서만 사용할 수 있습니다. 앱에 연결된 비즈니스 채널을 지정해야 하며, 전달한 순서대로 최대 2개를 표시합니다. 이미 앱에 연결하고 가입한 사용자에게 채널 추가 동의를 다시 요청하는 용도로는 사용할 수 없습니다. 자세한 조건은 채널 선택해 동의 요청을 참고하세요.

['_Abcdef', '_Ghijkl']처럼 ID 목록을 전달합니다. 웹에서는 SDK의 channelPublicId 문자열로 변환하므로, 앱에서 쉼표로 합칠 필요가 없습니다. 웹 로그인에는 web.redirectUri도 필요합니다.

• loginHint: 카카오계정 로그인 화면의 ID 입력란에 미리 채울 이메일, 전화번호 또는 카카오메일 ID입니다. Android, iOS, 웹에서 사용할 수 있습니다. 카카오톡으로 바로 로그인하거나 브라우저에 로그인한 상태라면 ID 입력 화면이 생략될 수 있습니다.

ID 입력 화면을 표시하려면 다음과 같이 카카오계정 로그인을 요청합니다. 이 값은 입력란만 채우며, 해당 계정이 존재하는지는 확인하지 않습니다.

login({
  useKakaoAccountLogin: true,
  prompts: ['Login'],
  loginHint: 'user@example.com',
});

웹에서는 웹 로그인에 따라 web.redirectUri도 전달합니다. loginHint와 web.loginHint를 함께 전달하면 loginHint를 우선합니다.

• nonce: ID 토큰 재생 공격을 방지하기 위한 검증 값입니다. 전달한 값이 발급되는 ID 토큰의 nonce claim에 포함되어 반환됩니다.

자세한 내용은 공식 문서를 참고하세요.

정보

OpenID Connect를 활성화한 앱에서만 의미가 있습니다.

경고

다음 조건에서는 에러를 던집니다.

• useKakaoAccountLogin이 존재하지 않거나 false라면 prompts와 scopes를 전달할 수 없습니다.

Native SDK의 카카오톡 로그인에는 prompts와 scopes를 전달할 수 없습니다.

• scopes가 전달된다면 serviceTerms, prompts, channelPublicIds를 전달할 수 없습니다.

Native SDK에서 추가 동의를 받을 때는 serviceTerms와 prompts를 함께 전달할 수 없습니다.

• Android와 iOS에서는 loginHint를 scopes, serviceTerms, channelPublicIds와 함께 전달할 수 없습니다. iOS SDK가 이 조합을 제공하지 않으므로 네이티브 플랫폼에서는 호출 전에 에러를 던집니다. 웹의 로그인 힌트는 이 제한을 적용하지 않습니다.

응답

Promise로 토큰과 관련된 정보가 반환됩니다.

응답은 다음과 같습니다.

KakaoLoginToken

{
  accessToken: string;
  refreshToken: string;
  tokenType?: string;
  idToken?: string;
  accessTokenExpiresAt: number; // unix
  refreshTokenExpiresAt: number; // unix
  accessTokenExpiresIn: number; // seconds
  refreshTokenExpiresIn: number; // seconds
  scopes: string[];
};

로그아웃하기

logout()으로 로그아웃할 수 있습니다. 성공하면 반환값 없이 Promise<void>가 완료됩니다.

계정 연동 해제하기

unlink()로 계정 연동을 해제할 수 있습니다. 성공하면 반환값 없이 Promise<void>가 완료됩니다.

현재 로그인 상태인지 확인하기

isLogined()로 확인할 수 있습니다. 반환값은 Promise<boolean>입니다.

카카오톡이 사용 가능한지 확인하기

isKakaoTalkLoginAvailable()로 확인할 수 있습니다. 반환값은 Promise<boolean>입니다.

수동 연결 앱에서 가입 완료하기

로그인 시 앱 자동 연결을 비활성화했다면, 서비스 가입 절차를 마친 뒤 signup()을 호출해 사용자를 앱에 연결합니다. 자동 연결을 사용하는 일반 앱에서는 호출하지 않습니다.