시작하기

카카오 플랫폼 서비스는 카카오톡, 카카오스토리와 같은 카카오 서비스 및 카카오 플랫폼 기술과 관련된 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를 호출해야 사용자 가입이 완료됩니다.

    실제 서비스 가입하는 순간이 다름에도 불구 하고 자동 가입 옵션을 켜서 사용하는 경우는 사용자에게 혼란을 줄 수 있습니다. 예를 들어, 서비스 가입 과정 중에 이탈한 경우 카카오 로그인이 완료된 상태라면 연결된 앱관리에 해당 앱이 나타나게 됩니다. 이런 과정은 서비스를 탈퇴하고 난 후 탈퇴가 잘 되었는 지 확인차 로그인을 해보는 과정에서 자주 겪게 됩니다.

    사용자는 카카오계정으로 연결된 앱의 정보를 카카오톡이나 카카오스토리 내에 존재하는 카카오계정의 연결된 앱관리 페이지에서 확인할 수 있습니다.

  • 셋째, 앱 연동 > 카카오 계정 연동 을 선택할 수 있습니다.

    기본으로 제공되는 사용자 정보로 카카오톡 서비스 정보를 사용할지, 카카오스토리 서비스 정보를 사용할지, 두 서비스 모두 사용하는 사용자의 경우는 어느 서비스 정보에 우선순위를 둘지를 결정합니다. 기본으로 추가되어 있는 사용자 프로퍼티로는 nickname, profile_image, thumbnail_image가 있습니다.

    앱 연결 과정에서 최초 한번만 카카오톡 또는 카카오스토리 서비스와 동기화 연동을 하게 됩니다. 사용자가 해당 정보를 카카오톡 또는 카카오스토리에서 변경하였어도 추후 변경된 데이타는 반영되지 않습니다.

    카카오톡 또는 카카오스토리와의 동기화 연동 기능을 사용하지 않도록 설정되어 있을 경우, 해당 부가정보는 빈값으로 채워져 있습니다. 이 기본 부가정보는 사용자 정보 저장 기능을 통해 다른 데이타로 언제든 교체가 가능합니다.

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

    커스텀 사용자 정보 컬럼은 5개 이하로 제한 하고, 각 커스텀 사용자 정보 값은 160자 이내로 권장합니다. 실제로 사용자의 프로퍼티는 앱 연결 시에 추가 가능합니다. 또한 사용자 정보 저장 기능을 통해서도 추가 가능합니다.

  • 다섯째, 서비스에서 사용할 API에서 요구하는 동의항목을 선택하고, 해당 API를 호출하는 목적, 즉 해당 정보의 수집 목적을 설정해야 합니다.

    입력한 수집목적의 내용과 실제 서비스에서 해당 개인 정보를 사용하는 목적이 다를 경우 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초 내에 보장되어야 합니다.
    예를 들어, 어떠한 이유로 해당 사용자가 현재 가입자가 아니더라도 실패 응답이 아닌 성공 응답을 보내야 합니다. 즉, 해당 사용자의 지워질 정보가 있어서 삭제를 해야 하는데 실패한 경우를 제외한 모든 경우에는 성공 응답을 주어야 합니다.
    실패 응답이나 응답 지연 현상이 지속되는 경우, 사용자가 연결해제를 계속 실패하는 경험을 하게 되므로 콜백 설정이 임의로 삭제될 수 있습니다.

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


Last Modified : 2018-03-07