이 문서는 카카오디벨로퍼스 앱 사용 시 필요한 설정에 대해 안내합니다.
앱은 서비스 정보가 등록된 카카오디벨로퍼스 프로젝트입니다. 서비스는 앱을 설정해서 카카오디벨로퍼스가 제공하는 다양한 기능을 사용할 수 있고, 앱 키로 카카오 API를 호출할 수 있습니다.
앱 관리 페이지의 [앱] > [일반] > [앱 기본 정보]에서, 앱 생성 시 등록한 카카오 API를 사용하려는 서비스의 기본 정보를 확인하고 수정할 수 있습니다.
🅐 앱 아이콘: 서비스 로고 또는 앱 아이콘, 250KB 미만인 파일만 등록 가능, 128*128 이하 크기 권장 🅑 앱 이름(필수): 서비스 이름 🅒 회사명(필수): 서비스의 상호, 법인 또는 단체명 🅓 카테고리(필수): 서비스의 카테고리
앱에 등록한 기본 정보는 사용자에게 노출되므로, 실제 서비스와 동일하게 입력해야 합니다. 아래 이미지와 같이 카카오 로그인 동의 화면, 연결된 서비스 관리, 카카오톡 메시지 하단의 출처 등에 표시됩니다.
카카오디벨로퍼스 앱은 가진 권한에 따라 아래와 같이 구분됩니다. 동시에 여러 권한을 가질 수 있습니다. 권한별 획득 방법은 각 항목의 내용을 참고합니다.
앱은 서비스별로 한 개여야 합니다. 기존에 카카오 로그인, 카카오톡 공유 등을 이용하고 있어 앱이 이미 등록돼 있는 경우, 새로운 앱을 등록하지 않고 기존 앱을 사용합니다. 관리자 계정을 분실해 기존 앱을 사용할 수 없는 경우, 데브톡에서 앱 소유자 변경을 요청합니다.
카카오 로그인을 사용 중인 서비스가 새로운 앱을 만들어 사용하면 사용자들이 모두 새로 가입해야 합니다. 이 경우 동일 사용자에 대해 두 개 이상의 서비스 회원 정보가 등록되어 문제가 발생할 수 있습니다.
앱 생성 시, 앱을 식별할 수 있는 고유한 ID가 부여됩니다. 앱 ID는 앱 관리 페이지 또는 도구 페이지 상단의 앱 정보 영역에서 확인할 수 있습니다. 데브톡 문의 시 앱 ID를 함께 기재하면 더 빠르게 확인할 수 있습니다.
앱 관리 페이지의 [앱] > [일반] > [비즈니스 정보]에 서비스의 비즈니스 정보를 등록해 비즈 앱으로 전환할 수 있습니다.
비즈 앱은 비즈니스 정보를 등록한 앱으로, 아래의 추가 기능을 제공합니다.
[앱] > [일반] > [비즈니스 정보]에서 [사업자 정보 등록]을 선택해 사업자등록번호를 입력합니다. 앱의 Owner만 비즈 앱 전환이 가능합니다. 사업자등록번호가 없는 개인 개발자는 개인 개발자 비즈 앱 전환을 참고합니다.
사업자등록번호가 없는 개인이나 단체가 제공하는 서비스의 앱도 아래 조건 만족 시 [앱] > [일반] > [비즈니스 정보] > [개인 개발자 비즈 앱]에서 비즈 앱 전환이 가능합니다.
개인 개발자 비즈 앱은 사업자 정보가 없어 비즈니스 채널을 연결할 수 없습니다. 개인 개발자 비즈 앱에서 비즈채널을 연결하려면 [앱] > [비즈니스 정보]에서 사업자 정보를 등록해 먼저 비즈 앱으로 전환해야 합니다.
비즈 앱은 사업자등록번호를 등록하거나 전화번호 본인인증을 완료한 경우에만 전환이 가능합니다.
만약 국내 사업자등록번호가 없거나, 해외에서 전화번호 인증이 불가능하다면 데브톡 메시지로 아래 정보를 담당자에게 전달합니다. 담당자가 내용 확인 후 비즈 앱으로 전환 예정입니다.
앱 키(App key)는 카카오 API를 사용하기 위해 플랫폼별로 발급되는 고유한 식별 키입니다. 앱 관리 페이지의 [앱] > [일반] > [앱 키]에서 확인할 수 있습니다.
앱 키는 플랫폼별로 각각 발급됩니다. 플랫폼에 맞지 않는 앱 키를 사용하면 에러 응답을 반환합니다.
앱 키가 노출되었을 경우, 앱 Owner가 앱 키를 재발급할 수 있습니다. 한 번 키가 재발급되면 이전으로 되돌릴 수 없음에 주의합니다. 앱 키 재발급 시, 서비스 앱이나 웹사이트에 적용된 앱 키를 재발급된 값으로 변경해야 합니다.
어드민 키(Admin Key)는 고정된 키 값을 사용해 API 접근을 허용하는 방식으로 절대로 유출되어서는 안 되는 중요 정보입니다. 정보 보안을 위해 어드민 키는 서버에서 호출할 때만 사용하고, 소스 코드에 포함하지 않도록 주의합니다.
카카오 API는 카카오디벨로퍼스에 플랫폼 정보를 등록한 서비스만 사용 가능합니다. 앱 관리 페이지의 [앱] > [일반] > [플랫폼]에서 서비스의 각 플랫폼 정보를 등록할 수 있습니다.
앱에 등록된 플랫폼 정보가 실제 서비스와 다르면 invalid android_key_hash or ios_bundle_id or web_site_url
에러가 발생합니다. 아래는 해당 에러 발생 시 플랫폼별로 확인해야 할 사항입니다.
package
속성 값과 동일한지, 키 해시 값이 등록되어 있는지 확인[플랫폼]에 등록된 오픈마켓 URL입니다. 카카오톡 공유나 카카오톡 메시지 API로 전송된 메시지는 서비스 앱 실행이 가능한 링크를 제공합니다. 서비스 앱 실행 시 사용자 기기에 해당 앱이 설치되어 있지 않을 경우, 등록된 마켓 URL로 이동합니다.
🅐 패키지명(Package Name)
package
속성 값 입력🅑 마켓 URL(Market URL)
🅒 키 해시(Key hash)
🅐 번들 ID(Bundle ID)
🅑 앱스토어 ID(Appstore ID) 및 마켓 URL(Market URL)
🅐 사이트 도메인
http://
, https://
, file://
형식의 도메인 등록http
와 https
도메인은 둘 중 한 가지만 등록해도 사용 가능🅑 기본 도메인
비즈 앱은 서브 도메인과 리다이렉트 URI(카카오 로그인, 비즈니스 인증)에 와일드카드 문자를 포함한 URI를 등록할 수 있습니다. 와일드카드 문자를 포함한 서브 도메인 사용 시, 아래 규칙을 준수해야 합니다.
테스트 앱은 실제 서비스에 사용 중인 앱에 영향을 미치지 않고 신규 기능이나 업데이트를 개발할 때 사용합니다. 원본 앱이 가진 권한과 테스트 앱용으로 기본 제공하는 권한을 검수 신청 전에 함께 활용할 수 있습니다. 실제 서비스 적용 시에는 테스트 앱이 아닌 원본 앱의 앱 키를 사용해야 합니다. 아래는 테스트 앱이 제공하는 주요 기능입니다.
아래는 테스트 앱 사용 시 고려해야 할 제한 사항입니다.
테스트 앱이 실제 서비스에 적용되지 않도록 주의합니다. 테스트 앱은 테스트 목적으로만 제공하는 기능으로 제한된 쿼터가 적용되며, 테스트 이외의 목적으로 사용 시 제재됩니다.
테스트 앱에 기본 제공하는 추가 기능 목록입니다. 테스트 앱용으로 제공하는 추가 기능을 원본 앱에서 사용하려면, 별도 검수 신청 후 권한을 획득해야 합니다.
앱의 기본 기능 및 권한
개인정보 동의항목의 사용자 정보 제공 동의 단계(필수 또는 선택 동의 권한 추가 제공)
account_email
): 필수 동의name
): 선택 동의, 필수 동의gender
): 필수 동의age_range
) 필수 동의birthday
): 필수 동의birthyear
): 선택 동의, 필수 동의phone_number
): 선택 동의, 필수 동의shipping_address
): 선택 동의, 필수 동의[앱] > [일반] > [테스트 앱]에서 🅐 [테스트 앱 생성]을 선택해 테스트 앱을 생성할 수 있습니다.
테스트 앱을 생성하면 원본 앱과 다른 별도의 앱 키, 독립된 설정값, 테스트 앱용 권한을 사용할 수 있습니다. 원본 앱의 오너가 아니더라도, 테스트 앱을 생성한 계정이 테스트 앱의 오너가 됩니다. 테스트 앱의 오너는 [테스트 앱] 항목에서 생성한 🅑 테스트 앱의 이름을 선택해 테스트 앱 설정 화면으로 이동할 수 있습니다.
앱이 더 이상 필요하지 않거나 다른 플랫폼에서 카카오디벨로퍼스 앱 삭제를 안내받은 경우, 아래와 같이 앱을 삭제할 수 있습니다.
앱 삭제 시 앱 사용자는 연동한 기능(카카오 로그인, 카카오톡 공유 등)을 더 이상 이용할 수 없으며, 삭제한 앱은 복구할 수 없습니다.
아래의 경우 앱을 삭제할 수 없습니다. Q. 왜 앱을 삭제할 수 없나요?를 함께 참고합니다.
앱 관리 페이지의 [앱] > [카카오톡 채널]에서 카카오디벨로퍼스 앱에 서비스의 카카오톡 채널을 연결해 마케팅에 활용할 수 있습니다. 앱과 카카오톡 채널의 연결 방법은 앱에 카카오톡 채널 연결을 참고합니다.
🅐 연결된 카카오톡 채널 🅑 대표 채널 🅒 고객 관리 API 정책 동의
앱에 연결된 카카오톡 채널 목록을 확인하고 관리할 수 있습니다.
[카카오톡 채널 관리]를 누르면 추가 기능 신청 페이지로 이동합니다. 앱과 카카오톡 채널을 연결하려면 [카카오톡 채널 연결] 열의 [신청]을 눌러 연결을 요청할 수 있습니다. 연결을 해제하려면 [연결 관리] 항목에서 [연결 해제]를 선택합니다.
쇼핑몰 호스팅 서비스(Hosting Service)로 카카오싱크를 이용 중인 경우, 이 기능으로 채널 연결을 해제할 수 없습니다. 카카오싱크 간편설정 팝업을 지원하는 호스팅사를 참고해 호스팅사의 관리자 설정을 변경해야 합니다.
대표 채널은 서비스를 대표하는 카카오톡 채널입니다. 대표 채널을 설정하면 카카오 로그인 동의 화면에 채널 추가를 위한 동의항목이 노출됩니다. 설정 방법은 대표 채널에서 확인할 수 있습니다.
카카오톡 채널 고객 관리 API를 사용하기 위해 필요한 정책에 동의할 수 있습니다. 아래 단계별 안내를 참고합니다.
앱의 추가 기능을 사용하기 위한 심사를 요청합니다. 신청 가능한 추가 기능 목록은 추가 기능 신청 대상에서 확인할 수 있습니다.
앱 관리 페이지의 [앱] > [추가 기능 신청]에서 심사를 요청합니다. 추가 기능 신청 전 신청 자격 확인을 완료해야 합니다. 아래 항목별 안내를 참고합니다.
카카오톡 채널 목록 확인 및 연결 해제 관련 내용은 카카오톡 채널을 참고합니다.
앱과 계정의 추가 기능 신청 자격을 확인합니다.
앱의 비즈니스 정보 심사를 신청합니다.
앱의 추가 기능을 사용하기 위한 심사를 요청합니다. 신청 가능한 추가 기능 목록은 추가 기능 신청 대상에서 확인할 수 있습니다.
추가 기능 심사 상태를 아래 문구로 표시합니다.
추가 기능 신청과 관련해 궁금한 점이 있는 경우, 데브톡의 [추가 기능 신청] 게시판 또는 메시지로 문의합니다. 빠른 응답을 위해 문의 시 앱 ID를 함께 기재해 주시기 바랍니다.
서비스 외부에서 발생한 사용자 활동이나 계정 상태 변화를 전달받기 위한 웹훅 관련 설정을 등록합니다. 관련된 자세한 내용은 웹훅에서 확인할 수 있습니다.
웹훅 테스트가 필요한 경우 [웹훅 테스트]를 선택해 간편하게 테스트할 수 있습니다. 자세한 내용은 웹훅 테스트를 확인합니다.
앱 관리 페이지의 [앱] > [웹훅] > [계정 상태 변경 웹훅]에서 [웹훅 등록]을 선택해 계정 상태 변경 웹훅을 설정할 수 있습니다. 아래 설명을 참고해 상세 정보를 입력합니다.
🅐 활성화 상태: 계정 상태 변경 웹훅 사용 여부 선택 🅑 웹훅 URL: 변경 이벤트 정보를 전달받을 서비스의 웹훅 URL 입력, HTTPS만 지원 🅒 변경 이벤트: 변경 이벤트 카테고리 및 타입 선택 ⓐ 카테고리: 변경 이벤트 카테고리 선택, [카카오계정 상태 변경 내역] 동의항목 설정 권한이 있는 경우에만 RISC, CAEP 노출 (참고: 동의항목 설정) ⓑ 타입: 변경 이벤트 타입 선택
상세 정보 입력 후 [저장]을 선택하면 등록한 웹훅 상세 정보가 표시됩니다. [수정]을 선택해 등록한 정보를 수정하거나, [삭제]를 선택해 삭제할 수 있습니다.
위의 설정만으로 웹훅이 동작하지 않습니다. 웹훅 요청을 처리할 수 있는 수신 서버를 함께 구현해야 합니다. 자세한 내용은 구현 절차를 참고합니다.
앱 관리 페이지의 [앱] > [웹훅] > [연결 해제 웹훅]에서 [웹훅 등록]을 선택해 연결 해제 웹훅을 설정할 수 있습니다. 아래 설명을 참고해 상세 정보를 입력합니다.
[웹훅 URL]에 웹훅을 받아 처리할 사이트 도메인 주소, 메서드 및 요청 주소(Path)를 입력합니다. 웹훅 URL은 사용자 정보 보호를 위해 HTTPS만 지원하며, 443 포트(Port)만 등록 가능합니다.
상세 정보 입력 후 [저장]을 선택하면 등록한 웹훅 상세 정보가 표시됩니다. [수정]을 선택해 등록한 정보를 수정하거나, [삭제]를 선택해 삭제할 수 있습니다.
위의 설정만으로 웹훅이 동작하지 않습니다. 웹훅 요청을 처리할 수 있는 수신 서버를 함께 구현해야 합니다. 자세한 내용은 구현 절차를 참고합니다.
장기간 웹훅 수신 응답이 없거나 오류 발생 빈도가 높은 경우, 카카오 API 플랫폼은 더 이상 웹훅을 전달하지 않고 연결 해제 설정의 [활성화 상태]를 [일시 중지]로 변경합니다. 앱 멤버의 메일로 발송된 안내를 참고하여 웹훅 처리가 올바르게 이뤄지는지 확인 및 조치 후, [활성화 상태]를 [사용함]으로 변경해야 다시 웹훅을 전달받을 수 있습니다.
앱 관리 페이지의 [앱] > [웹훅] > [카카오톡 공유 웹훅]에서 [웹훅 등록]을 선택해 카카오톡 공유 웹훅을 설정할 수 있습니다. 아래 설명을 참고해 상세 정보를 입력합니다.
[메서드]와 [웹훅 URL]에 웹훅을 받아 처리할 사이트 도메인 주소, 메서드 및 요청 주소(Path)를 입력합니다. 웹훅 URL은 사용자 정보 보호를 위해 HTTPS만 지원하며, 443 포트(Port)만 등록 가능합니다.
상세 정보 입력 후 [저장]을 선택하면 등록한 웹훅 상세 정보가 표시됩니다. [수정]을 선택해 등록한 정보를 수정하거나, [삭제]를 선택해 삭제할 수 있습니다.
위의 설정만으로 웹훅 기능이 동작하지 않습니다. 웹훅 요청을 처리할 수 있는 수신 서버를 함께 구현해야 합니다. 자세한 내용은 구현 절차를 참고합니다. 또한, 카카오톡 공유 웹훅은 사용자 정의 파라미터 설정을 완료해야 수신할 수 있습니다.
카카오톡 메시지 API는 메시지 전송 결과를 응답으로 확인할 수 있어 별도의 웹훅 기능이 필요하지 않습니다.
앱 관리 페이지의 [앱] > [웹훅] > [카카오톡 채널 웹훅]에서 [웹훅 등록]을 선택해 카카오톡 채널 웹훅을 설정할 수 있습니다. 카카오톡 채널 웹훅은 앱에 카카오톡 채널 연결을 완료한 후 설정할 수 있습니다.
[웹훅 URL] 등록만으로는 웹훅 기능이 동작하지 않습니다. 웹훅 요청을 처리할 수 있는 수신 서버를 함께 구현해야 합니다. 자세한 내용은 구현 절차를 참고합니다.
웹훅을 구현하면 앱에 연결된 모든 비즈니스 카카오톡 채널을 대상으로 웹훅이 발송됩니다. 앱 관리 페이지의 [앱] > [카카오톡 채널] > [연결된 카카오톡 채널]에서 대상 카카오톡 채널을 확인할 수 있습니다.
멤버는 앱을 관리하는 구성원으로, 앱 관리 페이지의 [앱] > [멤버]에서 멤버를 관리할 수 있습니다. 멤버로 등록된 개발자 계정만 앱 정보를 조회 또는 수정할 수 있으며, 테스트 앱의 경우 멤버만 카카오 API를 호출할 수 있습니다.
🅐 멤버 추가
🅑 멤버 정보 및 관리
앱 소유자인 개발자 계정을 알 수 없다면 FAQ를 참고합니다.
운영 중인 서비스의 경우, 카카오 API를 사용하는 기능의 동작에 영향을 미칠 수 있는 설정입니다. 아래 내용을 충분히 이해한 후 사용해야 합니다.
앱 키 유출과 같은 보안 사고에 대비해 카카오 API 서버가 등록된 IP 주소의 요청만 허용하도록 설정하는 기능입니다. 앱 관리 페이지의 [앱] > [고급] > [허용 IP 주소]에서, [IP 주소 등록]을 선택해 서비스 서버의 IP 주소를 등록할 수 있습니다. CIDR(IP/CIDR), Subnet Mask(IP/Mask) 정보로 설정하기를 권장하며, 개별 IP(IPv4, IPv6)도 등록할 수 있습니다. 줄바꿈으로 여러 개의 IP를 추가할 수 있습니다.
허용 IP 주소 설정은 REST API 키 혹은 어드민 키를 사용하는 모든 카카오 API 호출에 적용됩니다. 설정 후에는 등록된 IP 주소에서만 REST API로 카카오 API를 호출할 수 있습니다. 등록되지 않은 IP 주소에서 카카오 API 요청 시 아래와 같이 에러 응답을 받습니다. 문제를 해결하려면 요청을 보낸 서비스 서버의 IP 주소를 추가 등록하거나, 허용 IP 등록 기능을 비활성화해야 합니다.
"msg": "ip mismatched! callerIp=XXX.XXX.XXX.XXX. check out registered ips.",
"code": -401
허용 IP 등록 기능을 비활성화하려면 [삭제]를 눌러 등록된 모든 IP 주소를 삭제합니다.