고급: 멀티 앱

이 문서는 애플리케이션(이하 앱)의 추가 기능인 멀티 앱의 사용 방법을 안내합니다.

기능 소개

멀티 앱은 하나의 카카오디벨로퍼스 앱에 여러 개의 네이티브 앱 정보를 추가 등록하여, 하나의 카카오디벨로퍼스 앱 정보와 네이티브 앱 키로 Kakao SDK를 연동할 수 있게 해주는 기능입니다. 다음과 같은 경우에 사용합니다.

기본적으로 카카오디벨로퍼스 앱에는 [내 애플리케이션] > [플랫폼] 메뉴에서 Android, iOS 각각 하나의 네이티브 앱만 등록 가능합니다. 등록되지 않은 네이티브 앱에서 Kakao SDK를 사용하면 API 호출 시 에러가 발생합니다. 그러나 멀티 앱을 사용하면 정상적으로 여러 개의 네이티브 앱에서 하나의 카카오디벨로퍼스 앱으로 Kakao SDK 연동이 가능합니다.

용어

이 문서는 이해를 돕기 위하여 다음과 같은 용어를 사용합니다.

멀티 앱 설정

[내 애플리케이션] > [플랫폼]에서 각 네이티브 앱 정보를 추가 설정하여 멀티 앱을 사용할 수 있습니다. 아래 플랫폼별 가이드를 참고하여 멀티 패키지 및 멀티 번들 ID를 설정합니다.

• Android
• iOS

Android

멀티 앱 사용 권한을 받으면 [내 애플리케이션] > [플랫폼] > [Android]에서 [멀티 패키지명]과 [멀티 마켓 URL]을 설정할 수 있습니다. 아래를 참고하여 각 항목을 설정합니다.

🅐 패키지명: 메인 앱의 패키지명 입력 🅑 멀티 패키지명: 각 서브 앱의 패키지명 입력, 줄넘김으로 구분하여 여러 개 입력 가능 🅒 마켓 URL: 메인 앱을 다운로드할 수 있는 오픈마켓 URL 입력 🅓 멀티 마켓 URL: 각 서브 앱을 다운로드할 수 있는 오픈마켓 URL 입력, [추가] 버튼을 눌러 마켓 URL 추가 입력 가능 🅔 키 해시: 줄넘김으로 구분하여 여러 개 입력 가능, 키 해시 등록 참고 🅕 저장: 입력한 내용 저장

iOS

멀티 앱 사용 권한을 받으면 [내 애플리케이션] > [플랫폼] > [iOS]에서 [멀티 번들 ID]와 [멀티 마켓 URL]을 설정할 수 있습니다. 다음을 참고하여 각 항목을 설정합니다.

🅐 번들 ID: 메인 앱의 번들 ID 입력 🅑 멀티 번들 ID: 각 서브 앱의 번들 ID 입력, 줄넘김으로 구분하여 여러 개 입력 가능 🅒 iOS 앱, iPad 앱: 메인 앱을 다운로드할 수 있는 오픈마켓 URL 입력 🅓 멀티 마켓 URL: 각 서브 앱을 다운로드할 수 있는 오픈마켓 URL 입력, [추가] 버튼을 눌러 마켓 URL 추가 입력 가능 🅔 저장: 입력한 내용 저장

커스텀 URL 스킴 설정

Kakao SDK를 통해 카카오 로그인 사용 시, 커스텀 URL 스킴을 설정해야 합니다. 커스텀 URL 스킴은 사용자가 카카오톡으로 로그인한 후 서비스의 각 네이티브 앱으로 돌아가거나, 메시지의 앱 링크를 통해 네이티브 앱을 실행할 때 사용됩니다.

멀티 앱 설정으로 멀티 패키지명 및 멀티 번들 ID를 등록한 후, 각 네이티브 앱에 설정해야 할 커스텀 URL 스킴 값을 확인할 수 있습니다. 아래 플랫폼별 가이드에 따라 각 네이티브 앱에 커스텀 URL 스킴을 설정합니다.

• Android
• iOS

Android

[내 애플리케이션] > [플랫폼] > [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의 경우, 두 가지 설정이 필요합니다.

• URL Schemes
• 앱 실행 허용 목록

URL Schemes

[내 애플리케이션] > [플랫폼] > [iOS]의 [커스텀 스킴] 목록에서 각 네이티브 앱의 번들 ID에 해당하는 커스텀 URL 스킴을 찾아 [복사] 버튼을 눌러 복사합니다.

각 네이티브 앱의 [Target] > [Info] > [URL Types] > [URL Schemes]에 다음과 같이 복사한 커스텀 URL 스킴을 추가합니다.

앱 실행 허용 목록

각 네이티브 앱에서 카카오 로그인 및 카카오톡 공유를 사용하기 위해 앱 실행 허용 목록(Allowlist)을 등록해야 합니다. 설정을 참고해 카카오 로그인과 카카오톡 공유 중 사용하는 기능의 LSApplicationQueriesSchemes 설정을 추가합니다.

Flutter

Flutter의 경우, Android와 iOS 설정이 모두 필요합니다.

• Android
• iOS

SDK 초기화

멀티 앱 사용 시, 각 네이티브 앱에서 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 링크를 설정합니다. 이 문서는 메시지 템플릿 도구의 자세한 사용 방법을 다루지 않으므로, 메시지 템플릿 도구를 함께 참고합니다.

1. [도구] > [메시지 템플릿]에서 멀티 앱을 적용받는 카카오디벨로퍼스 앱을 선택합니다.
2. 🅒 목록에서 해당 앱의 기존 템플릿을 선택하거나, [템플릿 만들기]를 눌러 새 템플릿을 생성합니다.
3. 🅔 구성 요소별 설정에서 [컴포넌트 링크 관리] 설정이 가능합니다.
   • 특정 구성 요소의 링크를 따로 설정하려면 [개별 링크 설정]으로 설정합니다.
   • 메시지의 모든 구성 요소에 공통적으로 사용될 링크를 설정하려면 [공통 링크]로 설정합니다.
   • 메시지의 출처 앱 정보에 사용될 링크를 설정하려면 [출처 링크 설정]에서 설정합니다.
4. [개별 링크 설정]에서 필요한 항목을 [ON]으로 활성화합니다.
   • [Android Scheme]: 메시지를 통해 앱을 실행하기 위한 Android 커스텀 URL 스킴
   • [Android Market]: 메시지를 통한 앱 실행 시, 앱이 설치돼 있지 않다면 연결되는 Android 마켓 URL
   • [iOS Scheme]: 메시지를 통해 앱을 실행하기 위한 iOS 커스텀 URL 스킴
   • [iOS Market]: 메시지를 통한 앱 실행 시, 앱이 설치돼 있지 않다면 연결되는 iOS 마켓 URL

멀티 앱을 사용할 경우, Android와 iOS의 링크 설정 UI가 원하는 앱 정보를 선택하는 형태로 나타납니다. 다음 예시 화면과 안내를 참고하여 원하는 앱의 커스텀 스킴이나 마켓 URL로 링크를 설정합니다.

* Android와 iOS의 설정 화면 UI 구조는 동일함

이용 정책

사용 권한 신청

멀티 앱은 사용 권한이 주어진 앱에서만 사용할 수 있습니다. 실제 서비스에서 기능을 사용하려면 [내 애플리케이션] > [앱 권한 신청]에서 사용 권한을 신청해야 합니다.

사용 권한 신청 시, 앱이 아래 조건을 만족해야 합니다.

• 카카오 로그인 또는 카카오싱크 사용
• 두 개 이상의 네이티브 앱을 운영 중이거나, 운영할 예정
• 서비스 중인 웹, 앱이 통합회원 사용

주의사항

멀티 앱은 하나의 카카오디벨로퍼스 앱을 기반으로 동작합니다. 카카오디벨로퍼스 앱은 서비스의 정보를 카카오 플랫폼에 등록한 것이므로, 멀티 앱은 카카오 플랫폼 안에서 하나의 서비스 정보를 여러 네이티브 앱에서 사용하는 기능이라고 할 수 있습니다. 이에 따라 다음과 같은 제약 사항이 있습니다.

앱 기본 정보 공유

멀티 앱은 앱 기본 정보를 네이티브 앱마다 다르게 설정할 수 없습니다.

앱 기본 정보는 멀티 앱을 적용받는 카카오디벨로퍼스 앱의 서비스 이름, 사업자명, 아이콘으로 구성됩니다. 앱 기본 정보는 카카오 로그인 동의 화면, 연결된 서비스 관리, 카카오톡 메시지에 노출되며, 멀티 앱을 적용받는 모든 네이티브 앱에서 동일하게 나타납니다.

앱 기본 정보의 노출 위치는 아래 이미지를 참고합니다.

이 중 카카오톡 메시지는 카카오톡 공유, 카카오톡 메시지 API로 발송된 메시지입니다.

카카오톡 메시지 하단에 노출되는 출처 앱 정보는 앱 기본 정보와 마켓 URL, 커스텀 URL 스킴으로 구성됩니다. 이 중 앱 기본 정보는 고정이지만, 마켓 URL과 커스텀 URL 스킴은 멀티 앱을 지원합니다. 자세한 안내는 메시지 설정에서 확인할 수 있습니다.

연결 상태 공유

멀티 앱을 적용 받는 모든 네이티브 앱은 카카오 로그인 사용 시 사용자의 앱 연결 상태를 서로 공유합니다. 사용자가 멀티 앱 중 다른 네이티브 앱을 통해 연결 또는 연결 끊기함으로써 API 호출 시 에러가 발생할 수 있으므로 주의합니다.