이 문서는 카카오디벨로퍼스에서 제공하는 Flutter SDK(Kakao SDK for Flutter) 사용 방법을 안내합니다.

Flutter SDK가 제공하는 패키지와 주요 기능은 아래와 같습니다.

• Flutter 3.38.0 이상
• Dart 3.9.0 이상
• Android 5.0(API 21) 이상
• iOS 13.0 이상

Flutter SDK는 모바일, PC 웹 환경에서 아래 웹 브라우저를 지원합니다.

아래 내용과 플랫폼 키를 참고해 서비스가 지원하는 플랫폼 정보를 앱 관리 페이지의 [앱] > [플랫폼 키]에 등록합니다.

• 네이티브 앱만 서비스: 네이티브 앱 키(Android, iOS)
• 웹만 서비스: JavaScript 키
• 네이티브 앱, 웹 모두 서비스: 네이티브 앱 키(Android, iOS), JavaScript 키

iOS 앱 정보 등록 시 필요한 앱의 번들 ID는 Xcode의 [Target] > [General] > [Bundle Identifier]에서 확인할 수 있습니다. Xcode에서 프로젝트를 직접 열거나, Android Studio의 [${Project}] > [ios] 폴더에 마우스 우클릭해 Xcode에서 프로젝트를 열 수 있습니다.

번들 ID 확인 1

번들 ID 확인 2

카카오디벨로퍼스는 Flutter SDK의 주요 기능을 빠르게 확인할 수 있는 샘플 앱을 제공합니다. 샘플 앱으로 카카오 로그인, 카카오톡 공유 등 SDK 기능을 직접 테스트하고, 구현 예제 코드를 확인할 수 있습니다.

Flutter SDK 샘플 앱을 실행하는 방법에 대해 안내합니다.

1. Flutter SDK 깃허브 레포지토리에서 프로젝트를 가져옵니다.
2. Android 환경에서 샘플 앱 기능을 실행하려면, 가져온 샘플 앱 프로젝트의 디버그 키해시를 계정 설정 페이지의 [Android SDK 샘플 앱]에 등록해야 합니다. 자세한 내용은 Android SDK 샘플 앱을 참고합니다.
3. 샘플 앱을 실행해 Flutter SDK의 주요 기능을 테스트하고, 구현 예제 코드를 확인할 수 있습니다.

커스텀 URL 스킴(Custom URL Scheme)은 사용자가 Android와 iOS 환경에서 카카오톡으로 로그인 후 서비스 앱으로 돌아오거나, 카카오톡 메시지 버튼 또는 링크로 서비스의 앱을 실행하는 데 사용됩니다.

커스텀 URL 스킴을 설정하면 kakao${YOUR_NATIVE_APP_KEY}://${PRODUCT_NAME} 형식의 스킴으로 서비스의 앱을 실행할 수 있습니다. ${YOUR_NATIVE_APP_KEY}에 앱 관리 페이지의 [앱] > [플랫폼 키] > [네이티브 앱 키]에서 확인한 네이티브 앱 키, ${PRODUCT_NAME}에 아래의 제품별 host 속성값을 각각 입력합니다.

• 카카오 로그인: oauth
• 카카오톡 공유, 카카오톡 메시지: kakaolink

Flutter 프로젝트의 [${Project}] > [android] > [app] > [src] 경로 내부의 AndroidManifest.xml 파일을 수정합니다.

• 카카오 로그인
  • <application> 엘리먼트(Element) 하위에 카카오 로그인 리다이렉트 URI 설정을 위한 <activity> 엘리먼트 추가
• 카카오톡 공유, 카카오톡 메시지
  • android:name=".MainActivity" 속성을 갖는 <activity> 엘리먼트(Element) 하위에 <data android:host="${PRODUCT_NAME}" android:scheme="kakao${YOUR_NATIVE_APP_KEY}" /> 형식의 엘리먼트를 포함하는 <intent-filter> 추가
• Android 12(API 31) 이상 타깃 앱인 경우, exported 속성을 반드시 true로 선언

<application>

    <!-- 카카오 로그인 커스텀 URL 스킴 설정 -->
    <activity
        android:name="com.kakao.sdk.flutter.auth.AuthCodeHandlerActivity"
        android:exported="true">
        <intent-filter android:label="flutter_web_auth">
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />

            <!-- "kakao${YOUR_NATIVE_APP_KEY}://oauth" 형식의 앱 실행 스킴 설정 -->
            <!-- 카카오 로그인 리다이렉트 URI -->
            <data android:scheme="kakao${YOUR_NATIVE_APP_KEY}" android:host="oauth"/>
        </intent-filter>
    </activity>

    <!-- 카카오톡 공유, 카카오톡 메시지 커스텀 URL 스킴 설정 -->
    <activity
        android:name=".MainActivity"
        android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
        android:exported="true"
        android:hardwareAccelerated="true"
        android:launchMode="singleTop"
        android:theme="@style/LaunchTheme"
        android:windowSoftInputMode="adjustResize">
        <!-- 생략 -->

        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />

            <!-- "kakao${YOUR_NATIVE_APP_KEY}://${PRODUCT_NAME}" 형식의 앱 실행 스킴 설정 -->
            <!-- 카카오톡 공유, 카카오톡 메시지 -->
            <data android:host="kakaolink"
                android:scheme="kakao${YOUR_NATIVE_APP_KEY}" />
        </intent-filter>
    </activity>
</application>

iOS 디바이스에서 커스텀 URL 스킴을 사용하려면 아래 두 가지 설정이 모두 필요합니다.

• 앱 실행 허용 목록
  • [${Project}] > [ios] 폴더를 우클릭하여 Xcode에서 프로젝트를 열고 설정
  • 설정 경로: [TARGET] > [Info] > [Custom iOS Target Properties]
  • 파일을 직접 수정하여 설정 시, Info.plist 파일 경로: [${Project}] > [ios] > [Runner] > [Info.plist]
• URL Schemes
  • [${Project}] > [ios] 폴더를 우클릭하여 Xcode에서 프로젝트를 열고 설정
  • 설정 경로: [TARGET] > [Info] > [URL Types] > [URL Schemes]

카카오톡 공유, 카카오톡 메시지는 앱 실행 여부와 관계없이 아래 함수를 호출해 커스텀 URL 스킴을 전달받을 수 있습니다.

receiveKakaoScheme((Uri uri) {
    // url에 커스텀 URL 스킴이 할당됩니다. 할당된 스킴의 활용 코드를 작성합니다.
});

위 함수는 Flutter SDK 초기화 이후 시점에 호출해야 합니다. 초기화를 참고합니다.

네이티브 앱의 경우, 커스텀 URL 스킴으로 앱 실행 시 서비스의 필요에 따라 추가 정보를 전달할 수 있습니다. androidExecutionParams, iosExecutionParams 파라미터로 앱 실행 시 전달할 키와 값을 설정합니다. 해당 파라미터 사용 시 아래와 같은 스킴이 호출됩니다.

kakao${YOUR_NATIVE_APP_KEY}://${PRODUCT_NAME}?${androidExecutionParams}
kakao${YOUR_NATIVE_APP_KEY}://${PRODUCT_NAME}?${iosExecutionParams}
// 예시
kakao${YOUR_NATIVE_APP_KEY}://kakaolink?key1=value1&key2=value2&key3=value3

하이브리드 애플리케이션(이하 하이브리드 앱) 내 웹 페이지에서 Flutter SDK 사용 시, 웹뷰(WebView)에서 Flutter SDK가 올바르게 동작하도록 하려면 추가 조치가 필요합니다. 필요한 조치 사항은 Kakao SDK for JavaScript와 동일하므로, 하이브리드 앱 가이드를 참고하여 조치합니다.

pubspec.yaml 파일의 dependencies 하위에 아래와 같이 Flutter SDK에 대한 의존성을 추가합니다. 전체 또는 필요한 패키지만 선택해 추가할 수 있습니다. 패키지 추가 시 들여 쓰기에 주의합니다.

dependencies:
  kakao_flutter_sdk: ^{LATEST_VERSION} # 전체 추가
  kakao_flutter_sdk_user: ^{LATEST_VERSION} # 카카오 로그인 API 패키지
  kakao_flutter_sdk_share: ^{LATEST_VERSION} # 카카오톡 공유 API 패키지
  kakao_flutter_sdk_talk: ^{LATEST_VERSION} # 카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 패키지
  kakao_flutter_sdk_friend: ^{LATEST_VERSION} # 피커 API 패키지
  kakao_flutter_sdk_navi: ^{LATEST_VERSION} # 카카오내비 API 패키지

터미널(Terminal)에 아래 명령어를 입력해 전체 패키지를 추가할 수도 있습니다.

$ flutter pub add kakao_flutter_sdk

터미널(Terminal)에 아래 명령어를 입력해 추가한 Flutter SDK의 패키지를 설치할 수 있습니다.

$ flutter pub get

main() 함수 안에서 Flutter SDK 초기화 메서드인 init() 메서드를 호출합니다. runApp() 메서드 호출 전 Flutter SDK를 초기화해야 한다는 점에 주의합니다.

초기화 시 플랫폼 키를 입력해야 합니다. init() 메서드 호출 시 아래 내용을 참고해 필요한 앱 키를 전달합니다.

• 네이티브 앱만 서비스
  • 네이티브 앱 키를 사용해 모든 카카오 API 호출
  • init() 호출 시 nativeAppKey 파라미터로 네이티브 앱 키 전달
• 웹만 서비스
  • JavaScript 키를 사용해 모든 카카오 API 호출
  • init() 호출 시 javaScriptAppKey 파라미터로 JavaScript 키 전달
• 웹, 네이티브 앱 모두 서비스
  • JavaScript 키를 사용해 일부 카카오 API 호출, 네이티브 앱 키와 JavaScript 키 모두 필요
  • init() 호출 시 nativeAppKey 파라미터로 네이티브 앱 키, javaScriptAppKey 파라미터로 JavaScript 키 각각 전달

import 'package:kakao_flutter_sdk_common/kakao_flutter_sdk_common.dart';

void main() async {
    ...
    // 웹 환경에서 카카오 로그인을 정상적으로 완료하려면 runApp() 호출 전 아래 메서드 호출 필요
    WidgetsFlutterBinding.ensureInitialized();

    // runApp() 호출 전 Flutter SDK 초기화
    await KakaoSdk.init(
        nativeAppKey: '${YOUR_NATIVE_APP_KEY}',
        javaScriptAppKey: '${YOUR_JAVASCRIPT_APP_KEY}',
    );
    runApp(MyApp());
    ...
}