페이지 이동경로
  • 문서>
  • 카카오싱크>
  • 고급: 싱크 플러그인

카카오싱크

카카오싱크 플러그인

이 문서는 카카오싱크 플러그인(이하 싱크 플러그인) 사용법을 안내합니다.

기능 소개

카카오싱크는 카카오톡 채널을 비롯해 다양한 플랫폼 서비스와 함께 사용할 때 더욱 효과적인 솔루션입니다. 특히 카카오싱크의 필수 요소인 카카오톡 채널과 함께 활용하면 효율적인 회원 관리 및 마케팅이 가능합니다.

챗봇은 카카오톡 채널이 지원하는 기능 중 하나입니다. 서비스는 챗봇 관리자센터를 사용해 손쉽게 카카오톡 챗봇을 만들 수 있고, 사용자는 챗봇을 통해 카카오톡 채팅방에서 서비스를 이용할 수 있습니다. 챗봇에 카카오싱크의 간편가입을 적용하면, 사용자가 챗봇으로 서비스를 가입 및 이용하는 편리한 경험을 선사할 수 있습니다.

싱크 플러그인은 챗봇에서 카카오싱크를 사용할 때 매끄러운 가입 동선을 제공하는 추가 기능입니다. 사용자가 챗봇과 대화하다가 서비스 회원 로그인이 필요한 기능을 요청했을 때, 채팅방 안에서 나타나는 하프뷰(Half-View) 동의화면을 통해 손쉽게 로그인 및 가입하고 대화를 이어갈 수 있도록 해 줍니다.

카카오싱크 플러그인의 동의화면

이 기능은 카카오 로그인 요청의 특정 파라미터를 활용하여 카카오톡 채널 채팅방 안에서 로그인 과정을 완료합니다. OAuth 2.0 표준을 따르는 카카오 로그인 REST API와 유사하게 동작하므로 이미 카카오 로그인을 구현한 서비스는 보다 쉽게 싱크 플러그인을 적용할 수 있습니다.

앱 설정

서비스의 카카오톡 채널 챗봇에 카카오싱크 플러그인을 적용하려면 기본적으로 카카오 로그인과 카카오싱크 간편가입 기능을 사용해야 합니다.

카카오 로그인은 카카오계정을 이용한 소셜 로그인으로 [내 애플리케이션] > [카카오 로그인] 메뉴에서 사용 설정할 수 있습니다. 카카오 로그인 사용 설정이 켜져(ON) 있지 않으면 카카오싱크를 통한 간편 로그인 및 가입도 불가능하므로 반드시 사용하도록 설정합니다.

간편가입 기능은 서비스 약관 및 제3자 정보제공 동의를 카카오 로그인 동의 화면을 통해 받도록 해 주는 기능으로, 카카오싱크 신청하기 과정을 거쳐야 사용할 수 있습니다. 카카오싱크 검수 완료 후, [내 애플리케이션] > [카카오 로그인] > [간편가입] 메뉴에서 사용 설정합니다. 간편가입 시 동의 받는 항목의 종류와 설명은 사용자 정보동의 항목을 참고합니다.

마지막으로 [내 애플리케이션] > [카카오 로그인] > [간편가입] 메뉴에서 싱크 플러그인을 통한 카카오 로그인 요청 시 사용할 싱크 플러그인 redirect_uri를 등록합니다. 이 메뉴에서 설정한 redirect_uri는 [카카오 로그인] 메뉴에서 등록한 것과 별개로, 싱크 플러그인 동작에만 사용됩니다.

테스트 환경 만들기

실제 서비스에 영향을 미치지 않고 앱과 카카오톡 채널 설정을 수정하며 개발을 진행하려면, 테스트 앱과 카카오톡 채널의 개발자용 프로필을 이용합니다. 카카오싱크 단계별 가이드에서 "Step 3.카카오싱크 설정 및 개발"의 "5. 테스트 개발 환경 설정" 부분을 참고합니다.

싱크 플러그인 설정 화면

싱크 플러그인 ID 발급

카카오디벨로퍼스(Kakao Developers)의 설정을 마친 후, 카카오비즈니스 관리자센터를 통해 싱크 플러그인을 등록하고 ID를 발급 받아야 합니다. 싱크 플러그인 ID 발급은 카카오톡 채널에서 싱크 플러그인이 정상적으로 동작하기 위해 필요한 설정으로, 개발 진행 전 반드시 완료하여야 합니다.

이 과정은 2단계로 진행됩니다:

  1. 카카오싱크 앱과 싱크 플러그인을 적용할 카카오톡 채널 연결
  2. 카카오싱크 앱에 싱크 플러그인 등록
주의

싱크 플러그인은 카카오싱크 신청 및 검수를 완료한 앱으로만 이용할 수 있습니다. 카카오싱크 검수를 완료하지 않은 앱은 다음 플러그인 사용 목적 중 '싱크 플러그인' 선택이 제한되어 정상적으로 싱크 플러그인 ID 발급을 완료할 수 없습니다.

Step 1. 카카오싱크 앱과 싱크 플러그인을 적용할 카카오톡 채널 연결하기

1단계는 카카오비즈니스 관리자센터의 [내 비즈니스] > [비즈니스 설정] > [채널-앱 연결] 메뉴에서 설정합니다. 카카오싱크 서비스 앱에 싱크 플러그인을 적용할 카카오톡 채널을 연결해야 합니다. 앱과 채널의 연결 조건 등 자세한 설명은 카카오싱크 신청하기 가이드를 참고합니다.

Step 2. 카카오싱크 앱에 싱크 플러그인 등록하기

2단계는 카카오비즈니스 관리자센터의 [비즈플러그인] 메뉴에서 설정합니다. 아직 등록한 플러그인이 없을 경우 아래와 같은 화면이 나타나며, [비즈플러그인 등록] 버튼을 클릭해 새로운 플러그인을 등록하는 과정을 시작할 수 있습니다.

이미 등록한 플러그인이 있는 경우, 아래와 같이 사용 중인 플러그인 목록이 나타납니다. 새로운 플러그인을 등록하기 위해 [플러그인 등록] 버튼을 클릭합니다.

먼저 싱크 플러그인을 사용할 비즈 앱을 목록에서 선택하고 [다음]을 클릭합니다.

플러그인 등록 개수 제한

싱크 플러그인은 앱마다 한 개만 등록할 수 있습니다. 이미 싱크 플러그인을 등록한 앱은 싱크 플러그인을 추가 등록할 수 없습니다.

이어서 플러그인 사용 목적을 '싱크 플러그인'으로 선택하고 [다음]을 클릭합니다.

싱크 플러그인을 선택할 수 없는 경우

다음 중 하나 이상의 조건에 해당한다면 사용 목적으로 '싱크 플러그인'을 선택할 수 없습니다. - 카카오싱크 검수를 완료하지 않은 앱 - 카카오디벨로퍼스 설정을 완료하지 않은 앱 - 이미 싱크 플러그인이 등록되어 있는 앱

마지막으로 플러그인 이름을 입력하고 [등록]을 클릭합니다.

이후 카카오비즈니스 관리자센터의 [비즈플러그인] 메뉴의 비즈플러그인 목록에서 등록한 싱크 플러그인의 ID와 상세 정보를 확인하고 수정할 수 있습니다.

챗봇 개발 가이드

챗봇과 카카오싱크 플러그인 연동에 대한 개발 가이드는 챗봇 관리자센터 도움말에서 확인할 수 있습니다.

개발 가이드

Step 1. 로그인 요청하기

싱크 플러그인의 로그인을 시작하는 단계는 챗봇의 인증 블록이 수행합니다. 앱 설정에서 안내된 싱크 플러그인 redirect_uri및 인증 블록 설정을 완료하였고, 챗봇 관리자센터 도움말을 참고해 인증 블록 설정을 완료했다면 로그인을 시작하는 단계에서는 별도 개발이 필요하지 않습니다.

싱크 플러그인을 통한 카카오 로그인의 동작은 다음과 같이 진행됩니다.

  1. 사용자가 카카오톡 채널 채팅방에서 인증 블록을 통해 카카오싱크 플러그인을 통한 카카오 로그인을 요청합니다.
  2. 사용자가 채팅방에 나타나는 카카오 동의 화면의 내용에 동의합니다.
  3. 카카오 API에서 사용자 인증을 위한 code 값과 함께 Redirect Continue URL을 서비스의 카카오싱크 플러그인 전용 Redirect URI로 리다이렉트(Redirect)합니다.
  4. 서비스에서 로그인 Redirect URI로 전달된 codecontinue 파라미터 값을 전달 받습니다.
  5. 서비스에서 전달 받은 code 값으로 액세스 토큰(Access Token)을 요청합니다.
  6. 서비스에서 전달 받은 액세스 토큰을 사용하여 사용자 정보를 요청합니다.
  7. 서비스에서 전달받은 액세스 토큰을 사용하여 사용자의 동의한 약관을 확인합니다.
  8. 서비스에서 해당 카카오계정 사용자 정보로 서비스 회원 가입 처리를 하거나, 정보 식별 결과 기존 회원이라면 카카오 로그인으로도 기존 정보로 서비스를 이용할 수 있도록 회원 정보 맵핑 및 연동 처리를 합니다.
  9. 서비스에서 사용자 등록을 완료한 후, Redirect URI로 전달된 continue의 값인 Redirect Continue URL로 302 리다이렉트합니다.
  10. 카카오에서 서비스의 응답을 전달 받아 싱크 플러그인을 통한 로그인을 완료 처리합니다.

사용자가 카카오톡 채널 챗봇에게 싱크 플러그인 인증 블록을 통해 로그인 및 가입을 요청하면, 카카오톡의 인증 정보를 토대로 인가 코드가 발급되며, 이어 채팅방 안에서 카카오싱크 동의화면이 화면 하단 하프뷰로 열립니다. 사용자는 이를 통해 이용약관, 제3자 정보제공에 동의하고 로그인을 요청할 수 있습니다.

싱크 플러그인을 통한 로그인은 카카오톡 안에서 이뤄지기 때문에, 카카오톡에 로그인된 카카오계정 인증 정보를 사용합니다. 따라서 사용자가 카카오계정 정보를 추가로 입력하거나, 다른 웹 브라우저나 서비스 앱으로 이동하지 않아 채팅방으로부터 이탈하지 않습니다.

사용자가 약관과 정보 제공에 동의하면 카카오톡은 카카오 인증 서버에 인가 코드 발급을 요청합니다. 카카오톡은 응답으로 받은 인가 코드와 Redirect Continue URL 값을 서비스 서버의 싱크 플러그인 redirect_uri로 전달합니다. 이때 앞서 [내 애플리케이션] > [카카오 로그인] > [간편가입] 메뉴에서 등록해 둔 redirect_uri 값이 사용됩니다.

다음은 카카오톡이 서비스 서버에 continue 파라미터 값으로 전달하는 Redirect Continue URL의 상세 정보입니다. Redirect Continue URL에 필요한 파라미터와 값이 모두 포함되어 있으므로, 서비스에서는 continue 값의 URL로 302 리다이렉트 처리를 하여 싱크 플러그인을 통한 로그인 요청을 완료할 수 있습니다.

URL
GET /sync/complete
HTTP/1.1
Host: talk-plugin.kakao.com
Parameter
Name Description Required
client_id 앱 생성 시 발급 받은 REST API 키 O
state 싱크 플러그인 요청 정보 O
complete 싱크 가입 완료 여부(true 또는 false, 기본값 true) X
user_match_url 추가 사용자 정보가 필요한 경우, 입력 페이지 URL X
Step 2. 사용자 정보 확인

서비스 서버는 STEP 1.의 과정을 통해 카카오톡으로부터 인가 코드와 Redirect Continue URL을 전달 받았습니다. 전달 받은 인가 코드로 토큰 받기를 요청해 로그인을 완료하고 토큰 값을 획득해야 합니다.

서비스 서버는 발급 받은 토큰을 사용해 사용자 정보 가져오기를 요청하여 로그인 및 가입에 필요한 사용자 정보들을 받습니다. 또한 동의한 약관 확인하기 요청을 통해 사용자가 동의한 약관 내역을 확인합니다. 이를 통해 회원 가입에 필요한 사용자 정보를 얻어 회원 가입 처리를 하거나, 대화를 이어가는 데 필요한 사용자 정보를 받습니다.

사용자 정보 및 약관 확인 시 사용자가 신규 회원이라 가입 처리가 필요하다면, 받은 사용자 정보를 토대로 가입 처리를 합니다. 사용자 정보를 회원 데이터베이스(DB)와 대조했을 때 기존 회원이면서 처음 카카오 로그인을 통해 로그인한 경우라면 기존 회원 처리 가이드를 참고해 회원 정보 맵핑(Mapping)합니다.

만약 사용자 정보 가져오기 응답만으로 회원 가입 처리가 불가능하고 사용자로부터 추가 정보를 입력 받아야 한다면 다음 단계인 STEP 3. 사용자 정보 추가 입력 받기로 넘어갑니다.

추가 정보 입력 없이 로그인 및 가입 처리를 완료했다면, 카카오로부터 전달 받은 Redirect Continue URL로 302 리다이렉트하여 로그인 완료 처리를 요청합니다. 리다이렉트 후 카카오 API 서버는 카카오톡 채널 챗봇 채팅방에 로그인 및 가입 처리가 완료되었음을 알려줘 싱크 플러그인을 통한 로그인 및 가입 과정을 완료합니다.

Step 3. 사용자 정보 추가 입력 받기

서비스 회원 가입 또는 회원 정보 맵핑 시 사용자 정보 가져오기 응답에 포함된 정보 외에 추가 입력이 필요한 항목이 있는 경우에는, 로그인 완료 처리 전 추가 작업이 필요합니다. 사용자 정보 추가 입력 시의 싱크 플러그인 로그인 절차는 다음과 같습니다.

  1. ➊~➐까지의 흐름은 기본적인 카카오싱크 플러그인 로그인 과정과 동일합니다. 하지만 ➑ 회원 등록 단계에서 서비스에서 싱크 플러그인을 통해 카카오계정으로 가입하려는 사용자를 내부 시스템에 자동 등록하지 못하는 경우가 발생하는 경우에는 다음 순서와 같이 처리합니다.
  2. 서비스에서 전달 받은 Redirect Continue URL에 추가 맵핑을 위한 URL Query Parameter를 다음과 같이 추가하여 302 리다이렉트합니다.
    • user_match_url: 추가 맵핑을 위한 서비스의 웹 페이지 주소
    • complete: 가입 완료 여부, 가입이 완료되지 않았으므로 false로 전달
    • 참고: Redirect Continue URL 상세
  3. 카카오에서 서비스의 응답을 전달 받아 자동 가입 실패 처리를 합니다.
  4. 서비스로부터 전달 받은 추가 맵핑 웹 페이지를 Redirect Continue URL 파라미터와 함께 호출합니다.
  5. 사용자가 채팅방 내 웹뷰에서 회원 가입 및 정보 맵핑을 위한 추가 정보를 입력합니다.
  6. 서비스에서 카카오계정 정보와 추가 정보로 회원 가입 또는 기존 회원 맵핑 처리를 합니다.
  7. 서비스에서 사용자 등록을 완료한 후, 앞서 4단계에서 전달 받은 Redirect Continue URL로 302 리다이렉트합니다.
  8. 카카오에서 서비스의 응답을 전달 받아 카카오싱크 플러그인을 통한 로그인을 완료합니다.

사용자로부터 추가 정보를 입력 받는 웹 페이지를 카카오톡 인앱브라우저에서 띄울 수 있도록, 앞서 카카오로부터 전달 받은 Redirect Continue URL에 파라미터를 추가해 함께 302 리다이렉트합니다.

이때 추가해야 할 파라미터는 user_match_url, complete입니다. user_match_url은 사용자 정보를 추가 입력 받을 서비스의 웹 페이지의 주소로써, 카카오톡이 해당 웹 페이지를 채팅방에서 인앱브라우저로 띄웁니다.

사용자 정보 추가 입력을 받아 서비스 가입 또는 회원 정보 맵핑 처리를 끝내면, 서비스 서버는 다시 Redirect Continue URLcomplete 파라미터를 true로 추가하고 302 리다이렉트합니다. 리다이렉트 후 카카오 API 서버는 카카오톡 채널 챗봇 채팅방에 로그인 및 가입 처리가 완료되었음을 알려줘 싱크 플러그인을 통한 로그인 및 가입 과정을 완료합니다.

탈퇴 및 연결 끊기

사용자가 카카오톡 채널 챗봇을 통해 서비스를 사용하다 보면 로그인 또는 회원 가입 처리가 올바르게 완료되지 않을 수 있습니다. 사용자가 가입 도중 채팅방을 나가거나 멀티태스킹으로 다른 앱에 넘어가는 등의 경우입니다. 이렇게 되면 카카오 플랫폼에서는 사용자와 서비스가 연결되어 있지만, 서비스 회원으로 정상 가입되지 않은 상태라 이용에 불편을 겪게 됩니다.

사용자와 서비스 사이의 연결과 가입 상태가 일치하지 않는다면 연결 끊기 기능을 사용합니다. 이 기능은 사용자와 서비스의 연결을 끊고 다시 회원 가입 절차를 밟을 수 있도록 합니다. 카카오싱크 플러그인 사용 시, 이 기능은 필수로 구현해야 합니다.

카카오싱크를 통해 가입한 사용자가 탈퇴하는 경우에도 연결 끊기 처리가 필요합니다. 서비스의 회원 데이터베이스(DB)에 탈퇴 처리를 할 때 카카오 플랫폼에서도 사용자 정보를 삭제할 수 있도록 연결 끊기 요청을 보내야 합니다.