시작하기

이 문서는 카카오 API 플랫폼에서 제공하는 Kakao SDK for Flutter(이하 Flutter SDK) 사용 방법을 안내합니다.

패키지 정보

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

패키지 의존성

Flutter SDK의 일부 패키지는 다른 패키지에 의존성이 있으며, 각 패키지 설치 시 의존하는 패키지를 자동으로 함께 설치합니다. 패키지 의존성 구조는 아래 이미지를 참고합니다.

준비

요구 사양

• Flutter 3.22.0 이상
• Dart 3.4.0 이상
• Android Studio 3.0 이상
• Android 5.0(API 21) 이상
• iOS 11 이상

참고: 외부 라이브러리 의존성

Flutter SDK는 아래 라이브러리를 사용합니다.

• dio
• json_annotation
• platform
• shared_preference
• crypto
• encrypt

지원하는 웹 브라우저

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

* Internet Explorer(IE) 미지원

** 개발 및 디버깅(Debugging) 시 기본 브라우저(Default browser)

플랫폼

아래 내용과 플랫폼을 참고해 서비스가 지원하는 플랫폼 정보를 [내 애플리케이션] > [플랫폼]에 등록합니다.

• 네이티브 앱만 서비스: Android, iOS
• 웹만 서비스: Web
• 네이티브 앱, 웹 모두 서비스: Android, iOS, Web

참고: iOS 번들 ID 확인 방법

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

프로젝트 설정

커스텀 URL 스킴

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

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

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

Android

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

• 카카오 로그인
  • <application> 엘리먼트(Element) 하위에 카카오 로그인 Redirect 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.AuthCodeCustomTabsActivity"
        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" 형식의 앱 실행 스킴 설정 -->
            <!-- 카카오 로그인 Redirect 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

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 스킴 수신

카카오톡 공유, 카카오톡 메시지 커스텀 URL 스킴 수신 방법에 대해 안내합니다.

실행중이지 않은 앱을 대상으로 호출한 커스텀 URL 스킴은, 앱 실행 시 아래 함수를 호출해 전달받을 수 있습니다.

String? url = await receiveKakaoScheme();
// url에 커스텀 URL 스킴이 할당됩니다. 할당된 스킴의 활용 코드를 작성합니다.

실행중인 앱을 대상으로 호출한 커스텀 URL 스킴은 Dart 언어에서 제공하는 Stream으로 전달받을 수 있습니다. 아래 예제를 참고합니다.

kakaoSchemeStream.listen((url) {
    // url에 커스텀 URL 스킴이 할당됩니다. 할당된 스킴의 활용 코드를 작성합니다.
}, onError: (e) {
    // 에러 상황의 예외 처리 코드를 작성합니다.
});

위의 두 함수는 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와 동일하므로, 하이브리드 앱 가이드를 참고하여 조치합니다.

설치

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

$ flutter pub add kakao_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() {
    ...
    // 웹 환경에서 카카오 로그인을 정상적으로 완료하려면 runApp() 호출 전 아래 메서드 호출 필요
    WidgetsFlutterBinding.ensureInitialized();

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