시작하기

카카오 플랫폼 서비스는 카카오톡, 카카오스토리와 같은 카카오 서비스 및 카카오 플랫폼 기술과 관련된 API를 제공합니다.

본 문서는 카카오 플랫폼 서비스의 다양한 기능을 HTTP 요청으로 활용할 수 있는 REST API에 대해 설명하며, 카카오 플랫폼 서비스가 제공하는 각각의 기능별 상세 설명을 포함합니다.

앞으로 제공될 상세기능에 대한 설명을 참고하거나 해당 기능을 실행해 보기전에, 아래의 기본 내용을 참고해 보시기를 권장합니다.

REST API에 대해 빠른 참조를 원하시면 아래를 참고하세요.

본 문서에서 제공되는 상세기능은 다음과 같습니다.

  • 사용자 관리
    카카오계정을 통한 간편 로그인을 제공합니다. 이외에도 사용자들의 개별 정보를 손쉽게 관리해주는 기능을 포함합니다. 카카오 플랫폼 서비스에서 제공하는 기능 중 로그인이 필요한 기능을 사용하기 위해서는 반드시 선행되어야 할 내용들을 다룹니다.
  • 카카오톡
    카카오톡에서 제공하는 API를 앱에서 직접 사용할 수 있습니다.
  • 카카오페이
    카카오페이를 사용하기 위한 REST API에 대해 설명합니다.
  • 카카오스토리
    카카오스토리에서 제공하는 API를 앱에서 직접 사용할 수 있습니다.
  • 푸시 알림
    푸시 알림을 사용하기 위한 기본 과정 및 REST API에 대해 설명합니다. REST API를 통해 iOS, Android 애플리케이션으로 푸시 알림을 보낼 수 있습니다.
  • 검색
    다음검색에서 제공하는 웹문서, 동영상, 이미지, 블로그, 팁, 책, 카페 서비스 검색결과를 사용하기 위한 REST API에 대해 설명합니다.
  • 로컬
    다음지도에서 제공하는 로컬 API를 서버에서 사용할 수 있습니다.
  • 비전
    이미지 분석을 위한 비전 API에 대해 설명합니다.

아래 문서는 다음의 환경을 기준으로 작성되었으며, 개발자의 시스템 환경에 따라 구성이 다를 수 있습니다.

  • Apple OS X system 10.9.2
  • Curl(7.30.0) tool
  • Chrome(33.0.1750.146), Firefox(28.0) browser

개발환경 구성

REST API는 HTTP 요청을 보낼 수 있는 환경이라면 어디에서든 이용할 수 있습니다. 다음은 REST API를 활용할 수 있는 환경의 예입니다.

  • 모바일/PC 웹 환경에서 Javascript를 활용
  • 다양한 환경(Java, Ruby, Python 등)의 웹 서버에서 활용
  • iOS, Android 등 다양한 모바일 환경에서 활용

    iOS, Android, Javascript의 경우 개발을 좀 더 쉽고 편리하게 할 수 있는 Kakao SDK를 제공합니다.

개발자 웹사이트에서는 REST API를 개발하고 디버깅 할 수 있는 다양한 툴을 제공하며, 본 문서에서는 curl을 사용한 예시 화면을 제공합니다.

curl이 설치되어 있지 않은 환경의 경우 curl 다운로드를 통해 설치가 가능합니다.

앱 생성

내 애플리케이션 > 앱 만들기를 통해 앱을 생성합니다.

  • 앱 이름과 앱 아이콘을 지정합니다. dev_0017.png
  • 앱 만들기를 클릭하면 앱 생성이 완료되고 앱 키가 할당됩니다. REST API를 사용할 때에는 REST API 키를 사용합니다. dev_018.png
  • 설정을 클릭하여 설정을 이어 갑니다. 플랫폼 추가 > 선택후 사이트 도메인을 입력합니다.
  • 추가로 사용자 관리 기능을 사용하기 위해서 코드를 리다이렉트 해줄 Redirect Path를 입력해야 합니다. dev_019.png

사용자 관리 설정

사용자 관리 기능을 사용하기 위해서 설정 > 사용자 관리에서 추가 설정이 필요합니다.

dev_021.png

  • 첫째, 설정 > 사용자 관리 > 사용ON 해야합니다

  • 둘째, 서비스에서 필요한 동의항목을 설정하고 해당 동의항목의 수집 목적을 설정해야 합니다.

    입력한 수집목적과 서비스에서 사용하는 목적이 다를 경우 API서비스의 거부 사유가 될 수 있습니다. 카카오계정 이메일을 사용하기 위해서는 카카오계정(이메일)에 대한 동의항목 설정이 필요합니다.

  • 셋째, 플러스친구 설정을 통해서 앱 연결 시 플러스친구 추가를 유도할 수 있습니다. 설정한 플러스친구는 제 3자 정보제공 동의창에 표시되며 사용자가 동의한 경우 플러스친구 추가도 함께 됩니다. 플러스친구를 개설하지 않았다면 플러스친구 개설 후 설정 가능합니다.

    플러스친구는?

    하나, 국가/성별/연령 등의 타겟팅 기능으로 원하는 사람에게 효과적으로 카카오톡 메시지를 보낼 수 있습니다.
    둘, 스마트 채팅을 통해 사용자가 직접 필요한 정보를 찾아볼 수 있고 일대일 채팅으로 쉽고 빠른 소통이 가능합니다.
    셋, 포스트나 메시지에 대한 사용자의 반응을 통계로 확인할 수 있어 이용패턴과 트렌드를 쉽게 파악할 수 있습니다.

    플러스친구 활용사례가 궁금하다면, '@플러스친구'와 친구를 맺고, 채팅에 "성공사례"를 입력해 보세요!

  • 넷째, 연결끊기에서 콜백 API를 설정하면 사용자가 해당 서비스와의 연결을 끊는 시점에 콜백을 받을 수 있습니다.
    연결끊기 콜백을 받은 경우 카카오로 부터 제공 받았던 정보는 삭제해야 합니다.

    서비스 외부에서 연결해제가 가능한 시나리오는 아래 세 가지가 있습니다.

    하나, 카카오계정 탈퇴로 인한 모든 서비스 탈퇴 시 해당 서비스가 포함된 경우 (ACCOUNT_DELETE)
    둘, 사용자가 카카오계정에 '연결된 서비스 관리'에서 개별 서비스 연결해제 요청한 경우 (UNLINK_FROM_APPS)
    셋, 고객센터로 해당 서비스 연결해제를 사용자가 요청한 경우 (UNLINK_FROM_ADMIN)

    콜백 API 호출시 아래와 같은 정보가 포함됩니다.

    헤더 : Authorization: KakaoAK {해당 서비스의 admin_key}
    파라미터 1: user_id (String) : 연결해제를 요청한 사용자 id (사용자 id가 넘어가기 때문에 https만 지원)
    파라미터 2: referrer_type (String) : 연결해제를 요청한 경로 (ACCOUNT_DELETE/UNLINK_FROM_ADMIN/UNLINK_FROM_APPS)

    예를 들어, 도메인은 "https://api.example.com", API Path는 "/v1/user/deregister", http method는 "GET"으로 등록한 서비스는, user_id가 1234인 사용자가 카카오계정에 연결된 서비스 목록에서 해당 서비스 연결해제 요청한 경우에, 아래와 같은 콜백을 받게 됩니다.

    curl -v -X GET https://api.example.com/v1/user/deregister?user_id=1234&referrer_type=UNLINK_FROM_APPS \
      -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

    콜백을 받아 아래와 같이 처리해야 합니다.

    하나, 헤더로 들어온 앱키가 해당서비스의 어드민 키임을 확인 하고, user_id에 해당하는 사용자의 개인정보가 남아 있으면 삭제 작업을 수행해야 합니다. referrer_type는 연결해제 경로 정보로 참고하시면 됩니다.
    둘, 삭제 작업이 완료되면 응답을 http status "200 OK" 로 보내시면 됩니다. response body 정보는 보지 않고, http status만 보고 성공 여부를 확인하게 되니 body 정보는 포함하지 않아도 됩니다.
    셋, 서버 이슈로 사용자 정보 삭제를 실패한 경우를 제외하고는, "200 OK" 응답이 3초 내에 보장되어야 합니다.
    예를 들어, 어떠한 이유로 해당 사용자가 현재 가입자가 아니더라도 실패 응답이 아닌 성공 응답을 보내야 합니다. 즉, 해당 사용자의 지워질 정보가 있어서 삭제를 해야 하는데 실패한 경우를 제외한 모든 경우에는 성공 응답을 주어야 합니다.
    실패 응답이나 응답 지연 현상이 지속되는 경우, 사용자가 연결해제를 계속 실패하는 경험을 하게 되므로 콜백 설정이 임의로 삭제될 수 있습니다.

    등록한 설정이 제대로 동작하는지는 '카카오톡, 카카오스토리 앱 > 더보기 > 프로필 관리 > 카카오계정' 또는 '카카오계정 웹사이트'에서 카카오계정 탈퇴, 연결해제를 수행하여 콜백이 잘 호출되는 지 확인하시면 됩니다.

  • 다섯째, 서비스를 운영하는 곳이 국외라면 개인정보 국외이전 에서 개인정보가 저장되는 국가의 정보를 입력해야 합니다.

  • 여섯째, 앱 연결 시 추가하고 싶은 사용자 정보를 사용자 목록 및 프로퍼티 관리 메뉴를 통해 추가할 수 있습니다.

    사용자 프로퍼티의 수는 5개 이하로 제한 하고, 프로퍼티에 대한 값은 160자 이내로 권장합니다. 사용자 정보 저장 기능을 통해서 사용자 프로퍼티의 값을 관리할 수 있습니다.


Last Modified : 2019-02-18