이 문서는 채널 선택해 동의 요청 API 사용 방법을 안내합니다.

채널 선택해 동의 요청은 카카오싱크 간편가입 화면에서 상황에 따라 카카오톡 채널을 선택해 노출하는 기능입니다. 기본적으로 간편가입 시 동의 화면의 카카오톡 채널 추가 항목은 대표 채널 1개가 고정으로 노출됩니다. 채널 선택해 동의 요청 기능을 사용하면 동의 화면의 카카오톡 채널 추가 항목을 최대 2개까지 선택하여 노출할 수 있어, 여러 서비스가 하나의 앱으로 카카오싱크를 적용할 때 서비스마다 적합한 카카오톡 채널을 보여줄 수 있습니다.

아래와 같이 활용 가능합니다.

• 대표 서비스와 각 하위 서비스의 카카오톡 채널을 함께 노출
• 오프라인 본점과 각 지점의 카카오톡 채널을 함께 노출

이 기능은 별도의 추가 설정 없이 앱과 카카오톡 채널이 연결된 환경에서 동작하며, 서비스 약관 선택해 동의 요청과 마찬가지로 인가 코드 요청에 추가 파라미터를 전달하는 방식으로 구현합니다.

동의 화면에 추가 노출할 카카오톡 채널을 선택하는 channel_public_id 파라미터를 전달할 경우, 대표 채널 설정과 무관하게 선택된 카카오톡 채널이 동의창에 나타납니다. 대표 채널 외 채널들은 앱 관리 페이지의 [카카오 로그인] > [카카오톡 채널]에 연결된 비즈니스 채널로 설정되어 있어야 노출됩니다.

인가 코드 요청 시 channel_public_id 파라미터로 동의 화면에 추가 노출할 카카오톡 채널의 프로필 ID를 전달합니다.

각각의 카카오톡 채널 프로필 ID를 쉼표(,)로 묶은 하나의 문자열로 전달합니다.

• 인가 코드 요청의 쿼리 파라미터와 함께 아래 파라미터 사용

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

카카오 로그인 API인 Kakao.Auth.authorize() 요청 시 channelPublicId 파라미터로 카카오톡 채널 프로필 ID를 전달합니다.

각각의 카카오톡 채널 프로필 ID를 쉼표(,)로 묶은 하나의 문자열로 전달합니다.

channelPublicId 파라미터를 포함하지 않으면 자동 로그인이 아닌 일반적인 카카오 로그인으로 API가 동작합니다. 따라서 사용자에게 동의 받을 카카오톡 채널을 지정할 수 없으므로 주의합니다.

카카오 로그인과 같은 응답을 받으며, 요청 성공 시 간편가입 화면에 선택한 카카오톡 채널 추가 항목이 노출됩니다.

• 카카오 로그인 요청의 파라미터와 함께 아래 파라미터 사용

Kakao.Auth.authorize({
  redirectUri: "${REDIRECT_URI}",
  channelPublicId: "_AagLj,_xkTLLj",
})

채널 선택해 동의 요청 API는 카카오 로그인 모듈의 UserApiClient가 제공합니다.

카카오 로그인의 추가 파라미터를 사용해 채널 선택해 동의 요청 기능을 구현할 수 있습니다. loginWithKakaoTalk() 또는 loginWithKakaoAccount() 요청 시 사용자에게 동의 받을 카카오톡 채널 프로필 ID를 channelPublicIds 파라미터에 담아 전달합니다.

channelPublicIds 파라미터를 포함하지 않으면 자동 로그인이 아닌 일반적인 카카오 로그인으로 API가 동작합니다. 따라서 사용자에게 동의 받을 카카오톡 채널을 지정할 수 없으므로 주의합니다.

카카오 로그인과 같은 응답을 받으며, 요청 성공 시 간편가입 화면에 선택한 카카오톡 채널 추가 항목이 노출됩니다.

• 카카오 로그인 요청의 파라미터와 함께 아래 파라미터 사용

//channelPublicIds 설정
val channelPublicIds = listOf("_Abcdef", "_Ghijkl")

UserApiClient.instance.loginWithKakaoTalk(
    context = context,
    channelPublicIds = channelPublicIds
) { token, error ->
    if (error != null) {
        Log.e(TAG, "로그인 실패", error)
    }
    else if (token != null) {
        Log.i(TAG, "로그인 성공 ${token.accessToken}")
    }
}

카카오 로그인의 추가 파라미터를 사용해 채널 선택해 동의 요청 기능을 구현할 수 있습니다.

loginWithKakaoTalk() 또는 loginWithKakaoAccount() 요청 시 사용자에게 동의 받을 카카오톡 채널 프로필 ID를 channelPublicIds 파라미터에 담아 전달합니다.

channelPublicIds 파라미터를 포함하지 않으면 자동 로그인이 아닌 일반적인 카카오 로그인으로 API가 동작합니다. 따라서 사용자에게 동의 받을 카카오톡 채널을 지정할 수 없으므로 주의합니다.

카카오 로그인과 같은 응답을 받으며, 요청 성공 시 간편가입 화면에 선택한 카카오톡 채널 추가 항목이 노출됩니다.

• 카카오 로그인 요청의 파라미터와 함께 아래 파라미터 사용

// channelPublicIds 설정
let channelPublicIds = ["_Abcdef", "_Ghijkl"]

UserApi.shared.loginWithKakaoAccount(channelPublicIds: channelPublicIds, completion: {(oauthToken, error) in
if let error = error {
        print(error)
    }
    else {
        print("Success.")
        // 성공 시 동작 구현
        _ = oauthToken
    }
})

사용자에게 선택한 카카오톡 채널 친구 추가 항목을 포함한 동의 화면을 거친 로그인을 요청합니다.

이 기능은 카카오 로그인의 파라미터를 사용한 추가 기능으로, UserApi의 loginWithKakaoTalk() 또는 loginWithKakaoAccount()를 호출합니다.

요청 시 channelPublicIds 파라미터로 노출할 카카오톡 채널의 프로필 ID 목록을 문자열 리스트(List<String>)로 전달해야 합니다. channelPublicIds 파라미터를 포함하지 않으면 일반적인 카카오 로그인으로 동작한다는 점에 주의합니다.

요청 성공 시 선택한 카카오톡 채널의 친구 추가 항목을 포함한 카카오 로그인 동의 화면이 출력되고, 사용자가 동의 후 로그인을 완료하면 새로운 토큰이 발급됩니다. 사용자가 동의 화면에서 로그인을 취소하거나, 다른 에러가 발생한 경우에는 레퍼런스를 참고하여 각각 예외 처리합니다.

• 카카오 로그인 요청의 파라미터와 함께 아래 파라미터 사용

// 동의 받을 서비스 약관 태그 목록
List<String> channelPublicIds = ['${KAKAOTALK_CHANNEL_PROFILE_ID}'];

// loginWithKakaoTalk() 또는 loginWithKakaoAccount()로 요청
try {
  OAuthToken token = await UserApi.instance
      .loginWithKakaoTalk(channelPublicIds: channelPublicIds);
  print('로그인 성공 ${token.accessToken}');
} catch (error) {
  print('로그인 실패 $error');
}