카카오 (kakao)

🔔 최신화 일자: 2025-06-20

개요

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

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

---

필수 선행 작업

nachocode SDK로 카카오 네이티브 기능을 사용하기 위해서는 아래 사항이 먼저 완료되어야 합니다.

1. nachocode 대시보드의 [ 앱 설정 > 개발자 설정 > 안드로이드 네이티브 설정 ]에서 해시키 확인

2. Kakao Developers에서 애플리케이션 생성 및 네이티브 앱 키 발급

• 여기서 확인한 네이티브 앱 키는 5. 대시보드 설정 시 필요합니다.

3. 플랫폼 등록 (Android, iOS)

• Android 및 iOS 플랫폼을 등록합니다.
• 패키지명 및 번들 ID는 나쵸코드 대시보드에 등록된 것과 반드시 일치해야 합니다.
• 대시보드에서 확인한 키 해시를 Android 플랫폼에 등록합니다.

4-1. (선택사항) 공유하기 사용 시, 사이트 도메인 등록

• 스크랩 공유하기 기능을 이용하기 위해서는 사이트 도메인을 미리 등록해야 합니다.
• 운영 서버, 개발 서버 등의 도메인을 미리 등록해야 스크랩 공유하기 기능을 원활히 테스트 및 구현 가능합니다.

4-2. (선택사항) 공유하기 사용 시, 메시지 템플릿 등록 [ 도구 > 메시지 템플릿 ]

• 커스텀 템플릿 공유하기 기능을 이용하기 위해서는 카카오톡의 메시지 템플릿 빌더를 활용해 미리 메시지 템플릿을 만들어 저장해둬야 합니다.
• 이 때 발급 받은 템플릿 ID를 활용하여 nachocode SDK를 통해 템플릿 메시지 전송이 가능해집니다.

5. nachocode 대시보드의 [ 앱 설정 > 개발자 설정 > 카카오 네이티브 설정 ]에서 [ 카카오 네이티브 활성화 ] 토글 활성화 후 Kakao Developers에서 발급한 네이티브 앱 키를 등록하여 앱 설정 완료

6. nachocode 대시보드의 [ 앱 빌드 > 안드로이드, iOS 앱 빌드 ]에서 [ 새 버전 만들기 ] 버튼을 클릭하여 빌드

• 카카오 관련 네이티브 기능은 새로 빌드 된 버전의 앱부터 적용됩니다.

---

타입 정의

KakaoResult

• since ver.1.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)	오류 메시지 (실패 시 반환)

---

KakaoLoginData

• since ver.1.5.0

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

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

---

KakaoUserData

• since ver.1.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)

---

KakaoShareType

• since ver.1.2.0
• lastupdated ver.1.5.0

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

type KakaoShareType = 'custom' | 'scrap';

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

---

KakaoShareCustom

• since ver.1.2.0
• lastupdated ver.1.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)	공유 결과를 서버에서 처리할 경우 함께 전달할 값

---

KakaoShareScrap

• since ver.1.2.0
• lastupdated ver.1.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)	공유 결과를 서버에서 처리할 경우 함께 전달할 값

---

KAKAO_SHARE_STATUS_CODES

• since ver.1.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	성공 (외부 브라우저를 통한 공유 성공)

---

KakaoShareStatusCode

• since ver.1.5.0

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

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

---

메서드 목록

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

---

메서드 상세

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

• since ver.1.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 ver.1.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 ver.1.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 ver.1.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 ver.1.5.0

주의

필수 선행 작업이 완료되어야 사용할 수 있습니다.

설명

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

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

매개변수

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

반환 값

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

사용 예제

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

---

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

• since ver.1.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 스크랩)

// 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로 문의해 주세요.