kakao developers

애플리케이션

이 문서는 애플리케이션(이하 앱)에 대해 안내합니다.

카카오디벨로퍼스(Kakao Developers, 이하 개발자 웹사이트)는 카카오 개발자 웹사이트입니다. 카카오 API는 개발자 웹사이트에 등록된 각각의 애플리케이션 정보 기반으로 동작하므로, 카카오 API를 사용하려면 개발자 웹사이트에 앱을 등록해야 합니다.

앱 등록

카카오 API 사용을 위해 개발자 웹사이트에서 앱을 만들고, 해당 앱에 서비스 이름과 회사명, 아이콘 등 정보를 등록할 수 있습니다. 앱 정보는 서비스 이름, 제3자 정보제공동의 등 법적인 사항과도 관련이 있으므로 실제 서비스와 같은 내용으로 구성되어야 합니다.

개발자 웹사이트에서 로그인한 후, [내 애플리케이션] > [애플리케이션 추가하기]를 눌러 앱을 생성할 수 있습니다.

내 애플리케이션outlink

🅐 앱 아이콘: 서비스 로고 또는 앱 아이콘으로 등록, 128*128 이하 크기 권장, 250KB 미만인 파일만 등록 가능

🅑 앱 이름: 서비스 이름

🅒 사업자명: 서비스의 사업자 이름

🅓 저장: 입력한 기본 정보로 앱 등록

애플리케이션 등록 시 입력하는 위 항목들은 [내 애플리케이션] > [일반] > [기본 정보]에 반영됩니다.

참고: 기본 정보의 용도

기본 정보는 아래 이미지와 같이 카카오 로그인 동의 화면, 연결된 서비스 관리, 카카오톡 메시지 하단의 출처 등에 표시됩니다. 이를 통해 사용자가 올바른 서비스임을 확인하여 안심하고 서비스를 이용할 수 있도록, 앱 기본 정보를 실제 서비스와 동일하게 입력해야 합니다. 기본 정보를 잘못 등록한 경우, [내 애플리케이션] > [일반] > [기본 정보] 메뉴에서 [수정] 버튼을 눌러 변경할 수 있습니다.

🅐 앱 아이콘 🅑 앱 이름 🅒 사업자명

앱 키

앱을 생성하면 플랫폼별 앱 키(App Key)가 발급됩니다. 발급받은 앱 키는 [내 애플리케이션] > [요약 정보] 또는 [내 애플리케이션] > [앱 키]에서 확인할 수 있습니다. 각 앱 키의 [복사] 버튼으로 값을 그대로 복사해 사용하면 편리합니다.

앱 키는 플랫폼별로 각각 발급됩니다. 카카오 플랫폼은 앱 키 값으로 올바른 API 요청인지 검증하며, 플랫폼에 맞지 않는 앱 키를 사용하면 에러 응답을 반환합니다.

• 네이티브 앱 키: Kakao SDK for Android 초기화, Kakao SDK for iOS 초기화 시 사용
• REST API 키: REST API 요청 시 HTTP 헤더(Header)에 전달
• JavaScript 키: Kakao SDK for JavaScript 초기화 시 사용
• Admin 키: 일부 관리자 기능에 사용, 모든 권한을 갖고 있는 키이므로 유출되지 않도록 주의

플랫폼 등록

등록한 앱에서 API를 호출하려면 사용하려는 플랫폼에 대한 정보를 개발자 웹사이트에 등록해야 합니다.

[내 애플리케이션] > [플랫폼] 메뉴에서 서비스에 필요한 플랫폼을 등록합니다.

• Android
• iOS
• Web

참고: 잘못된 플랫폼 정보로 인한 에러

플랫폼 별로 필요한 정보를 등록하지 않았거나, 등록한 정보가 실제 앱 정보와 다르면 "invalid android_key_hash or ios_bundle_id or web_site_url" 에러가 발생합니다. 해당 에러 발생 시, 플랫폼별로 다음 사항을 확인합니다.

• Android: 등록한 패키지명이 AndroidManifest.xml 파일의 package 속성 값과 동일한지, 키 해시 값이 등록되어 있는지 확인
• iOS: 등록한 번들 ID가 Xcode 프로젝트 파일에 설정된 Bundle Identifier ID 값와 동일한지 확인, 번들 ID는 Xcode의 [TARGETS] > [General] > [Identify]에서 확인 가능
• Web: 카카오 API 호출 시 사용한 사이트 도메인을 등록했는지 확인

Android

🅐 패키지명(Package Name)

• Android 앱의 고유한 이름입니다.
• AndroidManifest.xml 파일의 package 속성 값과 동일한 값을 입력합니다.

🅑 마켓 URL(Market URL)

• 사용자가 카카오톡 공유나 메시지 API로 전송된 메시지의 링크를 통해 앱을 실행시킬 때, 사용자 기기에 해당 앱이 설치되어 있지 않을 경우 이동할 오픈마켓 주소입니다.
• [구글 플레이] 선택 시 패키지명 기반으로 마켓 URL이 자동 입력되고, [직접 입력] 선택 시 전체 마켓 URL 값을 등록해야 합니다. [직접 입력] 선택 시, 구글 플레이 스토어 외에 원스토어 등의 마켓 URL도 등록할 수 있습니다.

🅒 키 해시(Key Hash)

• 개발 및 서비스 릴리즈 빌드를 위해 필요한 키 해시 값입니다.
• 카카오 API 요청 시 유효성 검증에 사용되며, 개발 환경별로 등록해야 합니다. 키 해시 등록을 참고합니다.

🅓 저장: 플랫폼 정보 등록 및 수정 내용을 저장합니다.

iOS

🅐 번들 ID(Bundle ID)

• iOS 앱의 고유 값입니다.
• Xcode의 프로젝트 정보에 설정된 Bundle Identifier 값과 동일한 값을 입력합니다.

🅑 앱스토어 ID(Appstore ID) 및 마켓 URL(Market URL)

• 애플 앱스토어 등록 시 발급받은 앱 ID를 등록하면 마켓 URL이 자동 입력됩니다.
• 마켓 URL은 사용자가 카카오톡 공유나 메시지 API로 전송된 메시지의 링크를 통해 앱을 실행시킬 때, 사용자 기기에 해당 앱이 설치되어 있지 않을 경우 이동할 오픈마켓 주소입니다.

🅒 저장: 플랫폼 정보 등록 및 수정 내용을 저장합니다.

Web

🅐 사이트 도메인

• Kakao SDK for JavaScript, 카카오톡 공유를 포함한 메시지 API를 사용하려면 도메인 정보를 등록해야 합니다.
• http://, https://, file:// 형식의 도메인을 등록할 수 있으며, http와 https 도메인은 둘 중 한 가지만 등록해도 사용할 수 있습니다.
• 최대 10개의 도메인을 등록할 수 있습니다.
  • 11개 이상의 도메인 등록이 필요한 경우, 비즈 앱 전환을 통해 와일드카드 문자를 포함한 서브 도메인을 추가하거나 별도 문의합니다. (참고: 사이트 도메인 등록 수 제한 및 도메인 추가 등록 안내)

🅑 기본 도메인

• 하나 이상의 도메인을 등록한 경우, 맨 윗줄에 등록된 도메인이 기본 도메인으로 설정됩니다.
• 기본 도메인은 카카오톡 공유, 카카오톡 메시지 API를 통해 발송되는 메시지의 Web 링크 기본값으로 사용됩니다.

🅒 저장: 플랫폼 정보 등록 및 수정 내용을 저장합니다.

참고: 서브 도메인 설정

비즈 앱은 서브 도메인과 카카오 로그인 Redirect URI에 와일드카드 문자를 포함한 URI를 등록할 수 있습니다. 와일드카드 문자를 포함한 서브 도메인 사용 시, 아래 규칙을 준수해야 합니다.

• 와일드카드 문자를 포함한 도메인은 기본 도메인이 될 수 없습니다. 와일드카드 문자를 포함한 도메인만 등록돼 있을 경우, 기본 도메인이 없어 일부 기능이 정상 동작하지 않을 수 있습니다.
• 각 서브 도메인은 반드시 고유한 도메인명(Domain name) 또는 호스트명(Host name)을 포함해야 합니다.
  • https://*.sample.com (O)
  • https://*.com (X)
• 서브 도메인은 중간에 와일드카드 문자를 포함할 수 없습니다.
  • https://*.sample.com (O)
  • https://sub.*.sample.com (X)
• 서브 도메인은 두 개 이상의 와일드카드 문자를 포함할 수 없습니다.
  • https://*.sample.com (O)
  • https://*.*.sample.com (X)

팀 관리

팀은 앱 접근 권한을 관리하는 체계입니다. 앱의 개발 구성원인 팀원으로 등록된 사용자만이 앱 정보를 조회 또는 수정할 수 있습니다. 테스트 앱의 경우, 팀원만 API 호출이 가능합니다.

권한 종류

팀원 권한 종류는 다음과 같습니다.

권한	상세
오너(OWNER)	앱 소유자 앱 정보 조회 및 수정, 앱 키 재발급, 앱 삭제 등 앱에 대한 모든 권한 보유
에디터(EDITOR)	앱 정보 조회 및 수정 가능 앱 삭제, 팀원 초대, 앱 키 재발급 불가능
템플릿 에디터(EDITOR_MESSAGE_TEMPLATE)	앱 정보 조회, 메시지 템플릿 등록 및 수정 가능
리더(READER)	앱 정보 조회만 가능

팀원 등록 방법

[내 애플리케이션] > [팀 관리] 메뉴의 [팀원 초대] 버튼을 눌러 팀원을 추가할 수 있습니다.

🅐 팀원 초대

• 사용자의 카카오계정 이메일을 입력하고, 부여할 권한을 선택하여 팀원으로 초대합니다.
• 팀원 초대 시 초대 이메일이 발송됩니다. 카카오계정 로그인 시 사용되는 이메일로만 팀원 초대가 가능합니다.
• 초대하려는 팀원에게 아직 카카오계정이 없다면 카카오계정 페이지를 통해 가입한 뒤 초대할 수 있습니다.

🅑 팀원 정보 및 관리:

• 카카오계정: 팀원의 카카오계정 이메일을 나타냅니다.
• 권한: 팀원이 소유한 권한을 나타냅니다.
• 상태: 팀원의 상태를 나타냅니다.
  • 활성: 정상적으로 개발자 웹사이트 가입 및 팀원 등록이 완료된 사용자
  • 초대 메일 발송됨: 아직 개발자 웹사이트에 가입하지 않은 사용자, 초대 이메일을 통해 가입 후 팀원으로 합류 가능
  • 휴면: 카카오계정이 휴면 상태인 사용자, 오너를 포함한 모든 팀원에게 해당 사용자의 카카오계정 이메일이 노출되지 않음, 휴면 상태인 팀원은 수정이 불가능하며 내보내기만 가능
• 관리: 팀원 권한 수정, 제외 기능을 제공합니다. 오너는 각 팀원에 대해 [수정]과 [내보내기] 버튼을 사용할 수 있으며, 팀원은 [팀 나가기] 버튼으로 자신을 팀에서 제외시킬 수 있습니다. 팀원 권한 수정을 통해 다른 팀원에게 오너 권한을 이전할 수도 있습니다. FAQ를 참고합니다.

비즈 앱

비즈 앱(비즈니스 애플리케이션)은 해당 서비스를 소유한 사업자 정보를 등록한 앱을 말합니다.

추가 기능

비즈 앱은 다음과 같은 추가 기능을 이용할 수 있습니다.

• 카카오비즈니스 관리자센터에서 동일한 사업자 정보로 등록된 비즈니스 채널과 연결할 수 있습니다.
• 카카오 로그인 동의 항목 중 [이메일(account_email)] 항목을 검수 과정 없이 [필수 동의]로 설정할 수 있습니다.
• 와일드카드 문자를 포함한 서브 도메인을 설정할 수 있습니다.
• 카카오싱크를 이용할 수 있습니다.
• 친구 목록 가져오기를 이용할 수 있습니다.
• 카카오톡 메시지 보내기를 이용할 수 있습니다.

전환 방법

[내 애플리케이션] > [비즈니스] > [사업자 정보 등록]을 눌러 사업자등록번호를 입력합니다. 사업자등록번호를 등록하면 곧바로 비즈 앱으로 사용 가능합니다.

참고: 개인 개발자 비즈 앱 전환 방법

사업자등록번호가 없는 개인이나 단체가 제공하는 서비스의 앱이라면, 아래 조건 만족 시 개인 개발자 비즈 앱으로 전환할 수 있습니다.

• 앱 소유자(Owner) 카카오계정의 본인인증 완료
  • 본인인증 완료 여부는 개발자 웹사이트 로그인 후 상단 메뉴의 [계정 설정] > [본인인증]에서 확인 가능
• 카카오비즈니스 통합 서비스 약관 동의
• 각 조건을 만족하지 않은 상태라면 [내 애플리케이션] > [비즈니스] > [개인 개발자 비즈 앱]에서 본인인증 또는 카카오비즈니스 통합 서비스 약관 동의 바로가기 버튼 제공

조건 만족 시, [내 애플리케이션] > [비즈니스] > [개인 개발자 비즈 앱]에서 [개인 개발자 비즈 앱 전환] 버튼을 눌러 앱을 비즈 앱으로 전환 가능합니다.

테스트 앱

테스트 앱은 실제로 운영 중인 앱에 영향을 미치지 않고 신규 기능이나 업데이트 개발을 해야 할 때 사용합니다. 실제 서비스에서 사용 중인 앱 설정을 변경하지 않고, 테스트 앱을 사용하여 설정을 변경하며 개발을 진행할 수 있습니다.

테스트 앱은 카카오비즈니스 관리자센터에서 비즈니스 채널과 연결된 비즈 앱에만 제공되는 기능으로 테스트 앱의 팀원만 사용할 수 있습니다.

생성 방법

[내 애플리케이션] > [일반] > [테스트 앱 정보]에서 [테스트앱 생성]을 눌러 생성할 수 있으며, 앱마다 한 개의 테스트 앱을 만들 수 있습니다.

테스트 앱은 별도 앱 키를 가지며, 동의 항목 권한 및 서비스 이용 약관 설정은 원본 앱과 동일하게 설정됩니다. 최초 생성 이후에는 원본 앱의 [내 애플리케이션] > [일반] > [테스트 앱 정보]에서 [테스트앱과 권한 동기화]를 눌러 다시 동기화할 수 있습니다.

이용 정책

카카오 플랫폼 이용 시 준수해야 할 사항은 개발자 웹사이트 하단의 서비스 약관과 운영 정책에서 확인할 수 있습니다. 이 외 자세한 사항은 각 제품 문서의 이용 정책을 함께 참고합니다.

쿼터

카카오 플랫폼에서 제공하는 대부분의 API는 오픈 API로, 플랫폼 정책 범위 안에서 애플리케이션 등록을 통해 누구나 무료로 이용할 수 있습니다. 단, 원활한 서비스 제공을 위해 일정한 사용량 제한(이하 쿼터, Quota)이 적용됩니다. 현재 적용되는 쿼터 정보는 쿼터에서, 각 앱의 쿼터 소모량은 [내 애플리케이션] > [통계] > [쿼터]에서 각각 확인할 수 있습니다.

쿼터는 각 개발자 계정이 소유한 모든 앱의 쿼터 소모량을 합산하여 적용됩니다. 개발자 계정이 소유한 하나의 앱에서 특정 API의 쿼터를 초과할 경우, 다른 앱의 해당 API 이용이 제한될 수 있으므로 주의합니다.

각 API에 대해 적용되는 쿼터는 월간 제공량 및 일일 제공량 제한이 각각 존재하며, 해당 API의 기간별 요청 수를 기준으로 합니다. API 요청 수는 카카오 플랫폼에 정상적으로 전달되어 요청 수행 및 응답에 성공한 요청 1건당 1씩 집계(Count)됩니다. 번역, 음성, 포즈 API 중 일부 API의 쿼터는 문자나 프레임 수와 같은 API 요청에 따른 데이터 처리량을 기준으로 별도 집계됩니다.