카카오 (`kakao`) - 레퍼런스

🚀 추가된 버전 : v1.5.0 v1.5.0 v1.5.0
🔔 최신화 일자: 2025-07-16

연동을 마치셨나요?

SDK 메서드를 사용하기 위해선 필수 선행 작업으로 연동하기를 마쳐야합니다.

개요

kakao 네임스페이스는 카카오 네이티브 로그인 및 카카오톡 공유 기능을 제공합니다.

이 네임스페이스를 통해 로그인, 사용자 정보 조회, 로그아웃, 연결 해제(unlink) 를 수행하거나,
커스텀 템플릿 / URL 스크랩 기반 카카오톡 공유 기능을 구현할 수 있습니다.

타입 정의

`KakaoResult`

since : v1.5.0

카카오 API 요청 결과를 나타내는 타입입니다.

export declare type KakaoSuccessResult = {
  status: 'success';
  statusCode: number;
};

export declare type KakaoErrorResult = {
  status: 'error';
  statusCode: number;
  message: string;
};

export declare type KakaoResult = KakaoSuccessResult | KakaoErrorResult;

필드	타입	설명
`status`	`'error' \| 'success'`	요청 성공 또는 실패 상태
`statusCode`	`number`	요청 결과 코드 (성공 시 200)
`message`	`string` (optional)	오류 메시지 (실패 시 반환)

since : v1.5.0

카카오 로그인 결과 데이터입니다.

필드	타입	설명
`accessToken`	`string`	액세스 토큰 (optional)
`accessTokenExpiresAt`	`Date`	액세스 토큰 만료일 (optional)
`refreshToken`	`string`	리프레시 토큰 (optional)
`refreshTokenExpiresAt`	`Date`	리프레시 토큰 만료일 (optional)
`idToken`	`string`	ID 토큰 (optional)

`KakaoUserData`

since : v1.5.0

카카오 사용자 정보 데이터입니다.

필드	타입	설명
`id`	`number`	카카오 사용자 고유 ID
`email`	`string`	대표 이메일 (optional)
`name`	`string`	이름 (optional)
`profile`	`string`	프로필 정보 (optional)
기타 필드	`unknown`	추가 사용자 속성 (optional)

전체 보기

필드	타입	설명
`id`	`number`	카카오 사용자 고유 ID
`connectedAt`	`Date`	연결 시각 (optional)
`profileNeedsAgreement`	`boolean`	프로필 제공 동의 필요 여부 (optional)
`profileNicknameNeedsAgreement`	`boolean`	닉네임 제공 동의 필요 여부 (optional)
`profileImageNeedsAgreement`	`boolean`	프로필 이미지 제공 동의 필요 여부 (optional)
`profile`	`string`	프로필 정보 (optional)
`nameNeedsAgreement`	`boolean`	이름 제공 동의 필요 여부 (optional)
`name`	`string`	이름 (optional)
`emailNeedsAgreement`	`boolean`	이메일 제공 동의 필요 여부 (optional)
`isEmailValid`	`boolean`	이메일 유효성 여부 (optional)
`isEmailVerified`	`boolean`	이메일 인증 여부 (optional)
`email`	`string`	대표 이메일 (optional)
`ageRangeNeedsAgreement`	`boolean`	연령대 제공 동의 필요 여부 (optional)
`ageRange`	`unknown`	연령대 (optional)
`birthyearNeedsAgreement`	`boolean`	출생 연도 제공 동의 필요 여부 (optional)
`birthyear`	`string`	출생 연도 (`YYYY`) (optional)
`birthdayNeedsAgreement`	`boolean`	생일 제공 동의 필요 여부 (optional)
`birthday`	`string`	생일 (`MMDD`) (optional)
`birthdayType`	`unknown`	생일 타입 (optional)
`genderNeedsAgreement`	`boolean`	성별 제공 동의 필요 여부 (optional)
`gender`	`string`	성별 (optional)
`legalName`	`string`	법적 이름 (optional)
`legalGenderNeedsAgreement`	`boolean`	법적 성별 제공 동의 필요 여부 (optional)
`legalGender`	`string`	법적 성별 (optional)
`legalBirthDateNeedsAgreement`	`boolean`	법적 생년월일 제공 동의 필요 여부 (optional)
`legalBirthDate`	`string`	법적 생년월일 (`yyyyMMdd`) (optional)
`phoneNumberNeedsAgreement`	`boolean`	전화번호 제공 동의 필요 여부 (optional)
`phoneNumber`	`string`	전화번호 (optional)
`isKoreanNeedsAgreement`	`boolean`	한국인 여부 제공 동의 필요 여부 (optional)
`isKorean`	`boolean`	한국인 여부 (optional)

since : v1.5.0

카카오톡 공유 유형을 나타내는 타입(type)입입니다.

type KakaoShareType = 'custom' | 'scrap';

값	설명
`custom`	미리 등록된 커스텀 템플릿을 사용하여 카카오톡 공유
`scrap`	URL을 기반으로 카카오톡 스크랩 공유

since : v1.5.0

카카오톡 커스텀 템플릿 공유 시 사용할 데이터 타입입니다.

declare type KakaoShareCustom = {
  templateId: number;
  templateArgs?: {
    [key: string]: string;
  };
  serverCallbackArgs?: {
    [key: string]: string;
  };
};

필드	타입	설명
`templateId`	`number`	카카오 개발자 센터에서 등록한 템플릿 ID
`templateArgs`	`{ [key: string]: string }` (optional)	템플릿에 전달할 가변적인 값
`serverCallbackArgs`	`{ [key: string]: string }` (optional)	공유 결과를 서버에서 처리할 경우 함께 전달할 값

since : v1.5.0

카카오톡 URL 스크랩 공유 시 사용할 데이터 타입입니다.

declare type KakaoShareScrap = {
  requestUrl: string;
  templateId?: number;
  templateArgs?: {
    [key: string]: string;
  };
  serverCallbackArgs?: {
    [key: string]: string;
  };
};

필드	타입	설명
`requestUrl`	`string`	스크랩할 대상 URL
`templateId`	`number` (optional)	카카오 개발자 센터에서 등록한 템플릿 ID
`templateArgs`	`{ [key: string]: string }` (optional)	템플릿에 전달할 가변적인 값
`serverCallbackArgs`	`{ [key: string]: string }` (optional)	공유 결과를 서버에서 처리할 경우 함께 전달할 값

since : v1.5.0

카카오 공유 요청의 상태 코드 목록입니다.

const KAKAO_SHARE_STATUS_CODES = {
  ERROR_JSON_FAILED: 102,
  ERROR_JSON_FAILED_TO_MODEL: 103,
  ERROR_JSON_FAILED_TO_KAKAO_MODEL: 104,
  ERROR_JSON_WRONG_SHARE_TYPE: 105,
  ERROR_JSON_EMPTY_REQUEST_URL: 106,
  ERROR_JSON_EMPTY_TEMPLATE_ID: 108,
  ERROR_KAKAO_FAILED: 199,
  SUCCESS_KAKAO: 200,
  SUCCESS_SAFARI: 201,
} as const;

값	설명
`102`	JSON 변환 실패
`103`	JSON을 모델로 변환하는 과정에서 오류 발생
`104`	JSON을 카카오 모델로 변환하는 과정에서 오류 발생
`105`	잘못된 공유 타입 지정 (`custom` 또는 `scrap`이 아님)
`106`	`scrap` 공유 타입에서 `requestUrl`이 비어 있음
`108`	`custom` 공유 타입에서 `templateId`가 비어 있음
`199`	카카오 공유 요청 실패
`200`	성공 (카카오톡 공유 성공)
`201`	성공 (외부 브라우저를 통한 공유 성공)

since : v1.5.0

카카오 공유 요청의 상태 코드 타입(type)입니다.

type KakaoShareStatusCode = 102 | 103 | 104 | 105 | 106 | 108 | 199 | 200 | 201;

메서드 목록

메서드	설명	추가된 버전
`login(callback)`	카카오 네이티브 로그인	v1.5.0
`isLoggedIn(callback)`	로그인 상태 확인	v1.5.0
`getUserData(callback)`	사용자 데이터 요청	v1.5.0
`logout(callback)`	카카오 네이티브 로그아웃	v1.5.0
`unlink(callback)`	앱과 카카오 계정 연결 해제	v1.5.0
`share(type, data, callback?)`	카카오톡 커스텀 템플릿/스크랩 공유 기능	v1.5.0

메서드 상세

since : v1.5.0

주의

연동하기가 완료되어야 사용할 수 있습니다.

카카오 네이티브 로그인을 수행합니다.
성공 시 loginData를 콜백을 통해 반환합니다.

이름	타입	필수 여부	설명
`callback`	`(result: KakaoResult, loginData?: KakaoLoginData) => void`	✅	로그인 결과를 반환하는 함수

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

Nachocode.kakao.login((result, loginData) => {
  if (result.status === 'success') {
    console.log('카카오 로그인 성공', loginData);
  } else {
    console.error('카카오 로그인 실패', result.message);
  }
});

`isLoggedIn(callback: (result: KakaoResult, isLoggedIn: boolean, loginData?: KakaoLoginData) => void): void`

since : v1.5.0

주의

연동하기가 완료되어야 사용할 수 있습니다.

설명

현재 사용자의 카카오 로그인 상태를 확인합니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(result: KakaoResult, isLoggedIn: boolean,loginData?: KakaoLoginData) => void`	✅	로그인 상태를 반환하는 함수

반환 값

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

사용 예제

Nachocode.kakao.isLoggedIn((result, isLoggedIn, loginData) => {
  if (isLoggedIn) {
    console.log('카카오 로그인 상태', loginData);
  } else {
    console.log('카카오 로그인되어 있지 않음');
  }
});

`getUserData(callback: (result: KakaoResult, userData?: KakaoUserData) => void): void`

since : v1.5.0

주의

연동하기가 완료되어야 사용할 수 있습니다.

설명

로그인된 사용자의 카카오 정보를 가져옵니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(result: KakaoResult, userData?: KakaoUserData) => void`	✅	사용자 데이터를 반환하는 함수

반환 값

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

사용 예제

Nachocode.kakao.getUserData((result, userData) => {
  if (result.status === 'success') {
    console.log('카카오 사용자 정보', userData);
  } else {
    console.error('사용자 정보 가져오기 실패', result.message);
  }
});

`logout(callback: (result: KakaoResult) => void): void`

since : v1.5.0

주의

연동하기가 완료되어야 사용할 수 있습니다.

설명

카카오 네이티브 로그인 세션을 로그아웃합니다.

다시 로그인 시도 시 자동으로 이전에 연결된 카카오 계정으로 다시 인가 과정을 수행합니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(result: KakaoResult) => void`	✅	로그아웃 결과 콜백

반환 값

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

사용 예제

Nachocode.kakao.logout(result => {
  if (result.status === 'success') {
    console.log('카카오 로그아웃 성공');
  } else {
    console.error('카카오 로그아웃 실패', result.message);
  }
});

`unlink(callback: (result: KakaoResult) => void): void`

since : v1.5.0

주의

연동하기가 완료되어야 사용할 수 있습니다.

설명

앱과 카카오 계정 간의 연결을 해제(unlink)합니다.

다시 로그인 시도 시 카카오에서 처음부터 다시 인가 과정을 수행합니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(result: KakaoResult) => void`	✅	로그아웃 결과 콜백

반환 값

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

사용 예제

Nachocode.kakao.unlink(result => {
  if (result.status === 'success') {
    console.log('카카오 연결 해제 성공');
  } else {
    console.error('카카오 연결 해제 실패', result.message);
  }
});

since : v1.5.0

주의

연동하기가 완료되어야 사용할 수 있습니다.

카카오톡 공유 기능을 수행합니다.
커스텀 템플릿(custom) 또는 URL 스크랩(scrap) 방식을 사용하여 공유할 수 있습니다.
공유 결과는 선택적으로 callback 함수를 통해 전달받을 수 있습니다.

카카오 공식 문서

Kakao Developers - 메시지 템플릿 이해하기

이름	타입	필수 여부	설명
`type`	`KakaoShareType`	✅	`custom` 또는 `scrap` 공유 방식 선택
`data`	`KakaoShareCustom` \| `KakaoShareScrap`	✅	공유할 데이터 (템플릿 ID 또는 URL 필요)
`callback`	`(result: KakaoResult) => void` (optional)	❌	공유 결과를 처리할 콜백 함수

// 커스텀 템플릿을 활용한 카카오톡 공유
Nachocode.kakao.share(
  'custom',
  {
    templateId: 12345,
    templateArgs: { name: 'Nachocode' },
  },
  result => {
    if (result.status === 'success') {
      console.log('카카오톡 공유 성공');
    } else {
      console.error('카카오톡 공유 실패', result.message);
    }
  }
);

// URL을 활용한 카카오톡 공유
Nachocode.kakao.share(
  'scrap',
  {
    requestUrl: 'https://nachocode.io',
  },
  result => {
    if (result.status === 'success') {
      console.log('카카오톡 공유 성공');
    } else {
      console.error('카카오톡 공유 실패', result.message);
    }
  }
);

추가 정보

카카오 공유를 위해서는 카카오 개발자 센터에서 앱 키 설정이 선행되어야 합니다.
custom 공유 방식의 경우, 카카오 개발자 센터에서 사전 등록된 템플릿 ID가 필요합니다.
scrap 방식은 카카오 서버가 스크랩 API를 통해 대상 URL의 메타데이터를 가져와 미리보기를 생성합니다.
실패할 경우, KakaoResult의 status 값이 'error'로 설정되며 message 필드에 오류 원인이 포함됩니다.
카카오 설정 시 어려움이 있으시면 언제든지 support@nachocode.io로 문의해 주세요.

개요​

타입 정의​

KakaoResult​

KakaoLoginData​

KakaoUserData​

KakaoShareType​

KakaoShareCustom​

KakaoShareScrap​

KAKAO_SHARE_STATUS_CODES​

KakaoShareStatusCode​

메서드 목록​

메서드 상세​

login(callback: (result: KakaoResult, loginData?: KakaoLoginData) => void): void​

설명​

매개변수​

반환 값​

사용 예제​

isLoggedIn(callback: (result: KakaoResult, isLoggedIn: boolean, loginData?: KakaoLoginData) => void): void​

설명​

매개변수​

반환 값​

사용 예제​

getUserData(callback: (result: KakaoResult, userData?: KakaoUserData) => void): void​

설명​

매개변수​

반환 값​

사용 예제​

logout(callback: (result: KakaoResult) => void): void​

설명​

매개변수​

반환 값​

사용 예제​

unlink(callback: (result: KakaoResult) => void): void​

설명​

매개변수​

반환 값​

사용 예제​

share(type: KakaoShareType, data: KakaoShareCustom | KakaoShareScrap, callback?: (result: KakaoShareResult) => void): void​

설명​

매개변수​

사용 예제 (커스텀 템플릿)​

사용 예제 (URL 스크랩)​

개요

타입 정의

`KakaoResult`

`KakaoLoginData`

`KakaoUserData`

`KakaoShareType`

`KakaoShareCustom`

`KakaoShareScrap`

`KAKAO_SHARE_STATUS_CODES`

`KakaoShareStatusCode`

메서드 목록

메서드 상세

`login(callback: (result: KakaoResult, loginData?: KakaoLoginData) => void): void`

설명

매개변수

반환 값

사용 예제

`isLoggedIn(callback: (result: KakaoResult, isLoggedIn: boolean, loginData?: KakaoLoginData) => void): void`

설명

매개변수

반환 값

사용 예제

`getUserData(callback: (result: KakaoResult, userData?: KakaoUserData) => void): void`

설명

매개변수

반환 값

사용 예제

`logout(callback: (result: KakaoResult) => void): void`

설명

매개변수

반환 값

사용 예제

`unlink(callback: (result: KakaoResult) => void): void`

설명

매개변수

반환 값

사용 예제

`share(type: KakaoShareType, data: KakaoShareCustom | KakaoShareScrap, callback?: (result: KakaoShareResult) => void): void`

설명

매개변수

사용 예제 (커스텀 템플릿)

사용 예제 (URL 스크랩)