이 문서는 서비스에 카카오싱크를 연동할 때 실제 개발에 필요한 구현 흐름과 확인 사항을 안내합니다.

카카오싱크는 카카오 로그인을 기반으로 동작합니다. 카카오싱크의 간편가입 기능을 도입하면, 사용자가 동의 화면에서 서비스 약관에 함께 동의할 수 있어, 사용자는 한번의 클릭으로 서비스에 가입할 수 있습니다.

사용자가 카카오 로그인에 성공해도 서비스 데이터베이스에 회원을 생성하거나 기존 회원과 연결하지 않으면 서비스 가입은 완료되지 않습니다. 사용자 정보 조회와 서비스 약관 동의 내역 확인 후, 서비스 정책에 맞게 회원 가입 또는 로그인 처리를 구현해야 합니다.

개발에 어려움이 있는 경우, 쇼핑몰 호스팅 서비스를 이용할 수도 있습니다. 전자상거래 플랫폼을 위한 가이드를 참고합니다.

아래는 REST API 방식으로 카카오싱크 간편 가입의 기본 흐름입니다. 아래 다이어그램과 함께 단계별 설명을 참고합니다.

카카오싱크 간편가입 과정

서비스는 사용자가 [카카오로 시작하기] 버튼을 선택하면 카카오 로그인 인가 코드 요청 API를 호출합니다.

카카오 인증 서버는 사용자에게 카카오계정 인증과 동의 화면을 제공합니다. 카카오싱크 동의 화면에는 앱 설정에 따라 아래 항목이 함께 표시될 수 있습니다.

• 서비스 회원 가입에 필요한 사용자 정보 제공 동의
• 서비스 약관 동의
• 카카오톡 채널 추가 동의

사용자가 동의항목과 서비스 약관에 동의하면 카카오 인증 서버는 설정한 리다이렉트 URI로 인가 코드를 전달합니다.

서비스 서버는 전달받은 인가 코드로 토큰 요청 API를 호출해 액세스 토큰을 발급받습니다.

인가 코드는 한 번만 사용할 수 있습니다. 토큰 요청에 실패했다면 같은 인가 코드로 재시도하지 말고 사용자가 다시 로그인하도록 처리합니다.

서비스 서버는 액세스 토큰으로 사용자 정보 조회 API를 호출합니다. 응답의 회원번호(id)는 카카오싱크 사용자를 식별하는 기준값입니다.

서비스는 사용자 정보 조회 응답으로 아래 내용을 확인할 수 있습니다.

• 회원번호(id)
• 사용자가 동의한 항목에 대한 사용자 정보
• 사용자 동의항목 동의 내역
• 카카오싱크 간편가입 시각(synched_at)

필수 정보가 응답에 없다면 서비스 정책에 따라 가입을 중단하거나, 서비스 화면에서 사용자가 직접 정보를 입력하도록 별도 동선을 제공합니다.

서비스 서버는 서비스 약관 동의 내역 조회 API를 호출해 사용자가 어떤 서비스 약관에 동의했는지 확인합니다.

서비스 약관은 간편가입 설정 시 지정한 태그로 식별합니다. 서비스는 앱에 등록된 필수 약관 태그와 사용자의 동의 내역을 비교해 가입 완료 여부를 판단합니다.

필요한 필수 약관에 동의하지 않은 사용자는 아래 방법 중 하나로 처리합니다.

• 서비스 약관 선택해 동의 요청 API로 필요한 약관만 다시 동의 요청
• 서비스 자체 약관 동의 화면에서 추가 동의 처리

카카오싱크 동의 화면에서 사용자가 채널 추가에 동의하더라도, 서비스에서 실제 친구 상태를 기준으로 혜택을 제공하거나 메시지 발송 대상을 관리해야 한다면 카카오톡 채널 관계 조회 API를 사용합니다.

채널 친구 상태는 서비스 앱과 사용자 연결 상태와 별개입니다. 사용자가 서비스와 앱의 연결을 끊어도 카카오톡 채널 친구 상태는 유지될 수 있습니다.

서비스는 사용자 정보와 약관 동의 내역을 확인한 뒤 서비스 데이터베이스에서 회원 가입 또는 로그인 처리를 수행합니다.

• 신규 사용자: 일치하는 서비스 회원이 없으면 카카오 회원번호와 필요한 사용자 정보를 저장하고 서비스 회원을 생성합니다.
• 기존 회원: 서비스 정책에 따라 기존 서비스 회원을 찾고, 사용자 동의를 거쳐 해당 회원과 카카오 회원번호를 매핑해 저장합니다.
• 이미 연결된 사용자: 서비스 데이터베이스에 저장된 카카오 회원번호로 회원을 찾아 로그인 처리합니다.

자세한 내용은 카카오 로그인 > 기존 회원 연동을 참고합니다.

카카오 로그인 또는 카카오싱크 동의가 완료되어도 서비스의 로그인 처리가 자동으로 끝나는 것은 아닙니다.

서비스에서 신규 회원을 생성하거나 기존 회원을 찾은 뒤, 해당 사용자가 로그인한 상태로 서비스를 이용할 수 있도록 서비스 세션을 생성하고 로그인 완료 화면으로 이동시켜야 합니다.

카카오싱크를 사용하려면 앱에 아래 설정이 완료되어 있어야 합니다. 전반적인 설정 과정은 설정하기를 참고합니다.

• 카카오 로그인 활성화
• 리다이렉트 URI
• 동의항목
• 간편가입

카카오싱크 개발을 시작하기 전에 사용자가 카카오싱크 동의 화면을 거친 뒤 어떤 화면과 처리 과정을 지나 서비스 가입 또는 로그인을 완료하는지 먼저 설계합니다. 카카오싱크는 카카오가 회원 가입에 필요한 동의와 정보를 전달하는 기능이며, 서비스 회원 생성, 기존 회원 확인, 계정 연결, 추가 정보 수집은 서비스에서 구현해야 합니다.

권장하는 기본 동선은 카카오싱크 동의 화면 이후 추가 입력을 최소화해 바로 가입을 완료하는 방식입니다.

1. 사용자가 [카카오로 시작하기] 버튼을 선택합니다.
2. 서비스는 카카오 로그인 동의화면에서 사용자 정보 제공과 서비스 약관에 동의합니다.
3. 서비스는 사용자 정보 조회와 서비스 약관 동의 내역 조회로 가입에 필요한 정보와 약관 동의 상태를 확인합니다.
4. 서비스 데이터베이스에서 기존 회원 여부를 확인합니다.
5. 신규 회원이면 회원을 생성하고, 기존 회원이면 사용자 동의를 거쳐 기존 회원과 카카오 회원번호를 연결합니다.
6. 서비스 세션을 발급해 로그인 처리를 완료합니다.

이미 운영 중인 서비스라면 카카오싱크로 들어온 사용자가 기존 회원일 수 있습니다. 서비스는 기존 회원 여부 확인을 수행한 뒤, 결과에 따라 신규 가입 또는 기존 회원 연동 동선을 제공해야 합니다.

기존 회원 확인은 아래 우선순위로 설계합니다.

기존 회원과 연결할 때는 사용자가 계정 연결을 원하는지 반드시 확인합니다. 정보가 일치하더라도 실제 계정 소유자가 다르거나 사용자가 새 계정으로 가입하기를 원할 수 있습니다. 자세한 처리 흐름은 회원 등록과 연동을 참고합니다.

[필수 동의]로 설정한 동의항목이라도 사용자 정보 조회 응답에 값이 없을 수 있습니다. [필수 동의]는 사용자가 해당 항목 제공에 동의해야 가입을 계속할 수 있다는 의미이며, 카카오계정에 없는 값을 카카오가 생성해 제공한다는 의미는 아닙니다.

사용자 정보 조회 응답에 서비스의 회원가입에 필요한 필수 정보가 없다면, 서비스 정책에 따라 별도 동선을 제공해야 합니다.

• 사용자가 직접 정보를 입력하도록 추가 입력 화면 제공
• 본인확인이 필요한 서비스라면 서비스에서 자체적으로 본인확인 절차 구현해 제공
• 필수 정보가 없으면 가입할 수 없다는 안내 후 가입 중단

사용자 정보를 받을 수 없는 대표적인 경우와 권장 조치는 아래와 같습니다.

사용자 정보 항목별 제공 조건은 사용자 정보를 참고합니다. 자세한 원인과 해결 방법은 사용자 정보 누락을 참고합니다.

카카오싱크 간편가입 과정을 참고해 API를 연동합니다.

플랫폼별 API 개발 문서는 아래를 참고합니다.

• REST API
• JavaScript SDK
• Android SDK
• iOS SDK
• Flutter SDK

연동 개발을 마친 뒤 운영 서비스에 적용하기 전에 아래 항목을 최종 확인합니다.

개발 완료 후 실제 계정으로 아래 시나리오를 확인합니다.

세부 설정 방법은 각 참고 문서에서 확인합니다.

활용하기에서 안내한 오프라인 QR 코드, 카카오 비즈보드 애드뷰에서 바로 카카오싱크 동의 화면으로 사용자를 보내야 하는 경우, 랜딩 페이지를 추가 개발해야 합니다.

QR 코드용 카카오싱크 퍼머링크 생성이 필요한 경우 카카오싱크 퍼머링크 발급 요청하기를 참고합니다.

REST API 키로 카카오 로그인을 구현한 서비스는 QR 코드나 애드뷰 버튼의 랜딩 URL에 카카오 로그인 인가 코드 요청을 시작하는 서비스 URL을 입력합니다. 보통 서비스의 [카카오로 시작하기] 버튼이 호출하는 URL입니다.

https://a.com/login/kakao

서비스 로그인 URL을 별도로 제공하기 어렵다면 https://kauth.kakao.com/oauth/authorize로 시작하는 카카오 로그인 인가 코드 요청 URL을 사용할 수 있습니다. 이 경우 client_id에는 REST API 키를, redirect_uri에는 앱에 등록된 리다이렉트 URI와 동일한 값을 전달합니다.

https://kauth.kakao.com/oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code

매장, 캠페인, 광고 소재별 유입 경로를 구분해야 한다면 인가 코드 요청의 state 파라미터에 트래킹 값을 포함할 수 있습니다. state는 CSRF 방지 용도로도 사용되므로 서비스에서 발급한 값과 응답으로 돌아온 값이 일치하는지 검증합니다.

JavaScript SDK를 사용해 카카오 로그인을 구현한 서비스는 QR 코드나 애드뷰 버튼의 랜딩 URL에서 JavaScript SDK를 초기화한 뒤 카카오 로그인을 호출해 카카오싱크 동의 화면을 호출합니다.

사용자 경험을 위해서는 빈 랜딩 페이지에서 바로 카카오싱크 동의 화면을 호출하는 방식을 권장합니다.

Kakao.init("${JAVASCRIPT_KEY}")
Kakao.Auth.authorize({
  redirectUri: "${REDIRECT_URI}",
})

카카오톡 인앱브라우저에서만 자동으로 동의 화면을 호출하고 싶다면 사용자 에이전트를 확인해 분기할 수 있습니다.

Kakao.init("${JAVASCRIPT_KEY}")

if (/KAKAOTALK/i.test(navigator.userAgent)) {
  Kakao.Auth.authorize({
    redirectUri: "${REDIRECT_URI}",
  })
}