이 문서는 애플리케이션(이하 앱)의 추가 기능인 멀티 앱의 사용 방법을 안내합니다.
멀티 앱은 하나의 카카오디벨로퍼스 앱에 여러 개의 네이티브 앱 정보를 추가 등록하여, 하나의 카카오디벨로퍼스 앱 정보와 네이티브 앱 키로 Kakao SDK를 연동할 수 있게 해주는 기능입니다. 다음과 같은 경우에 사용합니다.
서비스 요구사항 | 멀티 앱이 제공하는 기능 |
---|---|
서비스에서 회원 체계를 공유하는 여러 네이티브 앱을 제공하는 경우 | 하나의 카카오디벨로퍼스 앱을 통해 서비스의 여러 네이티브 앱에서 카카오 로그인 또는 카카오싱크 적용 가능 |
서비스의 여러 네이티브 앱에서 카카오톡 공유나 카카오톡 메시지를 발송하려는 경우 | 하나의 카카오디벨로퍼스 앱을 통해 카카오톡 공유, 카카오톡 메시지 API를 사용해 메시지 발송 가능 각 메시지의 앱 링크에 원하는 네이티브 앱 링크 개별 설정 가능 |
기본적으로 카카오디벨로퍼스 앱에는 [내 애플리케이션] > [플랫폼] 메뉴에서 Android, iOS 각각 하나의 네이티브 앱만 등록 가능합니다. 등록되지 않은 네이티브 앱에서 Kakao SDK를 사용하면 API 호출 시 에러가 발생합니다. 그러나 멀티 앱을 사용하면 정상적으로 여러 개의 네이티브 앱에서 하나의 카카오디벨로퍼스 앱으로 Kakao SDK 연동이 가능합니다.
이 문서는 이해를 돕기 위하여 다음과 같은 용어를 사용합니다.
용어 | 설명 |
---|---|
멀티 앱 | 하나의 카카오디벨로퍼스 앱에 여러 개의 네이티브 앱 정보를 추가 등록하여, 하나의 카카오디벨로퍼스 앱 정보와 네이티브 앱 키로 Kakao SDK를 연동할 수 있게 해주는 기능 |
멀티 패키지 | [내 애플리케이션] > [플랫폼] > [Android]에 여러 네이티브 앱의 패키지명을 등록할 수 있는 기능 |
멀티 번들 ID | [내 애플리케이션] > [플랫폼] > [iOS]에 여러 네이티브 앱의 번들 ID를 등록할 수 있는 기능 |
멀티 마켓 URL | [내 애플리케이션] > [플랫폼]의 [Android], [iOS]에 여러 네이티브 앱의 마켓 URL을 등록할 수 있는 기능 |
카카오디벨로퍼스 앱 | 카카오디벨로퍼스의 [내 애플리케이션]에 등록된 서비스의 앱 |
네이티브 앱 | 서비스의 Android, iOS 앱 |
메인 앱 | 서비스의 기본 네이티브 앱 [패키지명] 또는 [번들 ID]에 등록된 네이티브 앱 |
서브 앱 | 멀티 앱을 통해 추가 등록된 네이티브 앱 [멀티 패키지명] 또는 [멀티 번들 ID]에 등록된 네이티브 앱 |
[내 애플리케이션] > [플랫폼]에서 각 네이티브 앱 정보를 추가 설정하여 멀티 앱을 사용할 수 있습니다. 아래 플랫폼별 가이드를 참고하여 멀티 패키지 및 멀티 번들 ID를 설정합니다.
멀티 앱 사용 권한을 받으면 [내 애플리케이션] > [플랫폼] > [Android]에서 [멀티 패키지명]과 [멀티 마켓 URL]을 설정할 수 있습니다. 아래를 참고하여 각 항목을 설정합니다.
🅐 패키지명: 메인 앱의 패키지명 입력 🅑 멀티 패키지명: 각 서브 앱의 패키지명 입력, 줄넘김으로 구분하여 여러 개 입력 가능 🅒 마켓 URL: 메인 앱을 다운로드할 수 있는 오픈마켓 URL 입력 🅓 멀티 마켓 URL: 각 서브 앱을 다운로드할 수 있는 오픈마켓 URL 입력, [추가] 버튼을 눌러 마켓 URL 추가 입력 가능 🅔 키 해시: 줄넘김으로 구분하여 여러 개 입력 가능, 키 해시 등록 참고 🅕 저장: 입력한 내용 저장
멀티 앱 사용 권한을 받으면 [내 애플리케이션] > [플랫폼] > [iOS]에서 [멀티 번들 ID]와 [멀티 마켓 URL]을 설정할 수 있습니다. 다음을 참고하여 각 항목을 설정합니다.
🅐 번들 ID: 메인 앱의 번들 ID 입력 🅑 멀티 번들 ID: 각 서브 앱의 번들 ID 입력, 줄넘김으로 구분하여 여러 개 입력 가능 🅒 iOS 앱, iPad 앱: 메인 앱을 다운로드할 수 있는 오픈마켓 URL 입력 🅓 멀티 마켓 URL: 각 서브 앱을 다운로드할 수 있는 오픈마켓 URL 입력, [추가] 버튼을 눌러 마켓 URL 추가 입력 가능 🅔 저장: 입력한 내용 저장
Kakao SDK를 통해 카카오 로그인 사용 시, 커스텀 URL 스킴을 설정해야 합니다. 커스텀 URL 스킴은 사용자가 카카오톡으로 로그인한 후 서비스의 각 네이티브 앱으로 돌아가거나, 메시지의 앱 링크를 통해 네이티브 앱을 실행할 때 사용됩니다.
멀티 앱 설정으로 멀티 패키지명 및 멀티 번들 ID를 등록한 후, 각 네이티브 앱에 설정해야 할 커스텀 URL 스킴 값을 확인할 수 있습니다. 아래 플랫폼별 가이드에 따라 각 네이티브 앱에 커스텀 URL 스킴을 설정합니다.
[내 애플리케이션] > [플랫폼] > [Android]의 [커스텀 스킴] 목록에서 각 네이티브 앱의 패키지명에 해당하는 커스텀 URL 스킴을 찾아 [복사] 버튼을 눌러 복사합니다.
복사한 커스텀 URL 스킴 값을 각 네이티브 앱의 AndroidManifest.xml에 추가합니다. 아래 예제를 참고하여 카카오 로그인, 카카오톡 공유 중 사용하는 기능의 커스텀 URL 스킴을 각각 추가해야 합니다.
<activity android:name="com.kakao.sdk.auth.AuthCodeHandlerActivity">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<!-- 카카오 로그인 Redirect URI: "${COPIED_CUSTOM_SCHEME}://oauth" -->
<data android:host="oauth" android:scheme="${COPIED_CUSTOM_SCHEME}" />
<!-- 카카오톡 공유: "${COPIED_CUSTOM_SCHEME}://kakaolink -->
<data android:host="kakaolink" android:scheme="${COPIED_CUSTOM_SCHEME}" />
<!-- 카카오톡 채널 간편 추가하기: "${COPIED_CUSTOM_SCHEME}://channel" -->
<data android:host="channel" android:scheme="${COPIED_CUSTOM_SCHEME}" />
<!-- 배송지 피커: "${COPIED_CUSTOM_SCHEME}://address" -->
<data android:host="address" android:scheme="${COPIED_CUSTOM_SCHEME}" />
</intent-filter>
</activity>
iOS의 경우, 두 가지 설정이 필요합니다.
[내 애플리케이션] > [플랫폼] > [iOS]의 [커스텀 스킴] 목록에서 각 네이티브 앱의 번들 ID에 해당하는 커스텀 URL 스킴을 찾아 [복사] 버튼을 눌러 복사합니다.
각 네이티브 앱의 [Target] > [Info] > [URL Types] > [URL Schemes]에 다음과 같이 복사한 커스텀 URL 스킴을 추가합니다.
각 네이티브 앱에서 카카오 로그인 및 카카오톡 공유를 사용하기 위해 앱 실행 허용 목록(Allowlist)을 등록해야 합니다. 설정을 참고해 카카오 로그인과 카카오톡 공유 중 사용하는 기능의 LSApplicationQueriesSchemes
설정을 추가합니다.
Flutter의 경우, Android와 iOS 설정이 모두 필요합니다.
멀티 앱 사용 시, 각 네이티브 앱에서 Kakao SDK를 초기화할 때 추가 파라미터로 커스텀 URL 스킴 설정에서 설정했던 커스텀 URL 스킴 값을 customScheme
파라미터로 전달해야 합니다.
KakaoSdk.init(
context,
appKey = "${NATIVE_APP_KEY}",
customScheme = "${COPIED_CUSTOM_SCHEME}"
)
KakaoSDK.initSDK(
appKey: "${NATIVE_APP_KEY}",
customScheme: "${COPIED_CUSTOM_SCHEME}"
)
KakaoSdk.init(
nativeAppKey: '${NATIVE_APP_KEY}',
customScheme: '${COPIED_CUSTOM_SCHEME}',
);
기본적으로 카카오톡 공유 및 카카오톡 메시지 API로 보내는 메시지의 앱 링크는 플랫폼별로 하나의 네이티브 앱만 설정 가능합니다. 그러나 멀티 앱을 사용하면 메인 앱과 서브 앱 모두 메시지의 앱 링크에 설정할 수 있습니다. 메시지에 설정 가능한 앱 링크의 종류는 아래와 같습니다.
현재 멀티 앱을 사용한 링크 설정은 기본 템플릿에 지원되지 않으며 사용자 정의 템플릿에만 지원됩니다. 기본 템플릿과 사용자 정의 템플릿의 차이는 사용 방법에서 확인할 수 있습니다.
[도구] > [메시지 템플릿]에서 앱의 사용자 정의 템플릿을 등록할 수 있습니다. 멀티 앱을 사용할 경우, 해당 메뉴에서 멀티 앱의 커스텀 URL 스킴 및 마켓 URL을 메시지의 앱 링크에 원하는 대로 설정할 수 있습니다.
예를 들어, 서비스의 멀티 앱 중 '가' 네이티브 앱에서 보내는 메시지에는 '가' 네이티브 앱의 링크를 설정하고, '나' 네이티브 앱에서 보내는 메시지에는 '나' 네이티브 앱의 링크를 설정할 수 있습니다.
메시지 템플릿의 일부 구성 요소에만 다른 네이티브 앱의 링크를 설정할 수도 있습니다. 아래 예시와 같이 각 메시지의 🅐 영역에는 '가' 네이티브 앱, 🅑 영역에는 '나' 네이티브 앱의 링크를 각각 설정 가능합니다.
아래 안내와 예시 화면을 참고해 Android, iOS 링크를 설정합니다. 이 문서는 메시지 템플릿 도구의 자세한 사용 방법을 다루지 않으므로, 메시지 템플릿 도구를 함께 참고합니다.
멀티 앱을 사용할 경우, Android와 iOS의 링크 설정 UI가 원하는 앱 정보를 선택하는 형태로 나타납니다. 다음 예시 화면과 안내를 참고하여 원하는 앱의 커스텀 스킴이나 마켓 URL로 링크를 설정합니다.
* Android와 iOS의 설정 화면 UI 구조는 동일함
구성 요소 | 설명 |
---|---|
🅐 커스텀 URL 스킴 선택 버튼 | 멀티 앱 설정에 등록된 Android 패키지명 목록 또는 iOS 번들 ID 목록 출력 원하는 항목을 선택하여 설정 가능 [Custom]은 사용자 인자를 통해 API 요청 시 원하는 앱 정보를 전달해 동적으로 링크 값을 지정하고자 할 때 사용하는 옵션 비고: [Custom] 사용 시, 사용자 인자의 값은 🅓 중 하나여야 함 |
🅑 마켓 URL 선택 버튼 | 멀티 앱 설정에 등록된 마켓 URL 목록 출력 [Custom]은 사용자 인자를 통해 API 요청 시 원하는 앱 정보를 전달해 동적으로 링크 값을 지정하고자 할 때 사용하는 옵션 비고: [Custom] 사용 시, 사용자 인자의 값은 🅓 중 하나여야 함 |
🅒 사용자 인자(User argument) | 커스텀 스킴 또는 마켓 URL의 설정을 [Custom]으로 선택한 경우, 카카오톡 공유 또는 카카오톡 메시지 API 요청 시 전달해야 할 사용자 인자(User argument)의 키 원하는 값으로 변경 가능 |
🅓 사용 가능한 값 목록 | 커스텀 스킴 또는 마켓 URL의 설정을 [Custom]으로 선택한 경우, 카카오톡 공유 또는 카카오톡 메시지 API 요청 시 사용자 인자의 값으로 전달 가능한 값 목록 비고: 사용 가능한 값 목록에 없는 임의의 값 전달 시, 유효성 검증에 따라 멀티 앱 설정이 적용되지 않고 메인 앱 정보가 반영됨 |
멀티 앱은 사용 권한이 주어진 앱에서만 사용할 수 있습니다. 실제 서비스에서 기능을 사용하려면 [내 애플리케이션] > [앱 권한 신청]에서 사용 권한을 신청해야 합니다.
사용 권한 신청 시, 앱이 아래 조건을 만족해야 합니다.
멀티 앱은 하나의 카카오디벨로퍼스 앱을 기반으로 동작합니다. 카카오디벨로퍼스 앱은 서비스의 정보를 카카오 플랫폼에 등록한 것이므로, 멀티 앱은 카카오 플랫폼 안에서 하나의 서비스 정보를 여러 네이티브 앱에서 사용하는 기능이라고 할 수 있습니다. 이에 따라 다음과 같은 제약 사항이 있습니다.
멀티 앱은 앱 기본 정보를 네이티브 앱마다 다르게 설정할 수 없습니다.
앱 기본 정보는 멀티 앱을 적용받는 카카오디벨로퍼스 앱의 서비스 이름, 회사명(상호, 법인 또는 단체명), 아이콘으로 구성됩니다. 앱 기본 정보는 카카오 로그인 동의 화면, 연결된 서비스 관리, 카카오톡 메시지에 노출되며, 멀티 앱을 적용받는 모든 네이티브 앱에서 동일하게 나타납니다.
앱 기본 정보의 노출 위치는 아래 이미지를 참고합니다.
이 중 카카오톡 메시지는 카카오톡 공유, 카카오톡 메시지 API로 발송된 메시지입니다.
카카오톡 메시지 하단에 노출되는 출처 앱 정보는 앱 기본 정보와 마켓 URL, 커스텀 URL 스킴으로 구성됩니다. 이 중 앱 기본 정보는 고정이지만, 마켓 URL과 커스텀 URL 스킴은 멀티 앱을 지원합니다. 자세한 안내는 메시지 설정에서 확인할 수 있습니다.
멀티 앱을 적용 받는 모든 네이티브 앱은 카카오 로그인 사용 시 사용자의 앱 연결 상태를 서로 공유합니다. 사용자가 멀티 앱 중 다른 네이티브 앱을 통해 연결 또는 연결 끊기함으로써 API 호출 시 에러가 발생할 수 있으므로 주의합니다.