이 문서는 Kakao SDK for Flutter(이하 Flutter SDK) 사용법을 설명합니다.
Flutter SDK는 Flutter로 작성된 애플리케이션(이하 앱)에서 카카오 API를 편리하게 호출할 수 있도록 도와주는 SDK입니다. Android, iOS, Web 앱 모두 정식으로 지원합니다.
Flutter SDK를 사용하기 위한 최소 요구 사양은 아래와 같습니다.
Flutter SDK는 다음 라이브러리를 사용합니다.
Flutter SDK는 모바일, PC 웹 환경에서 다음 웹 브라우저를 지원합니다.
Browser | Android | iOS | macOS | Windows | Linux |
---|---|---|---|---|---|
Chrome | O | O | O** | O** | O** |
Edge | O | O | O | O** | O |
Firefox | O | O | O | O | O |
Safari | X | O | O | X | X |
* Internet Explorer(IE) 미지원
** 개발 및 디버깅(Debugging) 시 기본 브라우저(Default browser)
pubspec.yaml 파일의 dependencies
하위에 다음과 같이 Flutter SDK에 대한 의존성을 추가합니다. 전체 또는 필요한 패키지만 선택해 추가할 수 있습니다. 패키지 추가 시 들여 쓰기에 주의합니다.
dependencies:
kakao_flutter_sdk: ^1.4.1 # 전체 추가
kakao_flutter_sdk_user: ^1.4.1 # 카카오 로그인
kakao_flutter_sdk_talk: ^1.4.1 # 카카오톡 메시지, 카카오톡 소셜(프로필 가져오기, 친구 목록 가져오기)
kakao_flutter_sdk_story: ^1.4.1 # 카카오스토리
kakao_flutter_sdk_share: ^1.4.1 # 카카오톡 공유
kakao_flutter_sdk_navi: ^1.4.1 # 카카오내비
kakao_flutter_sdk_friend: ^1.4.1 # 카카오톡 소셜(피커: 친구 선택하기)
터미널(Terminal)에 아래 명령어를 입력해 전체 패키지를 추가할 수도 있습니다.
$ flutter pub add kakao_flutter_sdk
Flutter SDK 1.3.0 버전부터 웹 애플리케이션(Web application)을 정식 지원합니다. 베타(Beta) 버전에서는 일부 기능이 정상 동작하지 않을 수 있으며, 데브톡에서 베타 버전 관련 문의나 제보가 가능합니다.
카카오톡 공유 패키지명이 1.2.0 버전부터 변경되었습니다. 아래 내용과 공지사항을 참고합니다. - 1.2.0 미만 버전: kakao_flutter_sdk_link - 1.2.0 이상 버전: kakao_flutter_sdk_share
터미널(Terminal)에 아래 명령어를 입력해 추가한 Flutter SDK의 패키지를 설치할 수 있습니다.
$ flutter pub get
Flutter SDK 0.9.0 이하 버전을 사용하고 있었다면, 최신 버전 업데이트 시 Flutter 마이그레이션을 참고하여 변경 사항을 적용해야 합니다.
Kakao SDK의 일부 패키지는 다른 패키지에 의존성이 있으며, 각 패키지는 설치 시 의존하는 패키지를 자동으로 함께 설치합니다. 패키지 의존성 구조는 아래 이미지를 참고합니다.
[내 애플리케이션] > [플랫폼]에서 플랫폼 정보를 등록합니다. 아래 내용을 참고해 서비스가 지원하는 플랫폼의 정보를 등록합니다.
이 설정은 Flutter SDK를 통해 카카오 API를 사용하려면 필수입니다. 자세한 안내는 플랫폼 등록을 참고합니다.
iOS 플랫폼 등록 시 필요한 앱의 번들 ID는 Xcode의 [Target] > [General] > [Bundle Identifier]에서 확인할 수 있습니다. Xcode에서 프로젝트를 직접 열거나, ${Project}
> ios 폴더에 마우스 우클릭하여 Xcode를 통해 프로젝트를 열 수 있습니다. 아래 이미지를 참고합니다.
사용자가 카카오톡으로 로그인 후 서비스 앱으로 돌아오거나, 카카오톡 메시지 버튼 또는 링크로 서비스의 앱을 실행할 수 있는 커스텀 URL 스킴(Custom URL Scheme) 설정 방법입니다. Android와 iOS 환경을 지원합니다.
커스텀 URL 스킴을 설정하면 kakao${YOUR_NATIVE_APP_KEY}://${PRODUCT_NAME}
형식의 스킴으로 서비스의 앱을 실행할 수 있습니다. ${YOUR_NATIVE_APP_KEY}
에 [내 애플리케이션] > [앱 키]에서 확인한 네이티브 앱 키를 입력합니다. ${PRODUCT_NAME}
에는 아래의 커스텀 URL 스킴을 지원하는 제품별 host
속성값을 입력해야 합니다.
oauth
kakaolink
kakaostory
커스텀 URL 스킴의 활용과 관련된 추가 내용은 아래 항목을 참고합니다.
Android 디바이스에서 커스텀 URL 스킴 설정 방법에 대해 안내합니다.
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}" />
<!-- 카카오스토리 -->
<data android:host="kakaostory"
android:scheme="kakao${YOUR_NATIVE_APP_KEY}" />
</intent-filter>
</activity>
</application>
iOS 디바이스에서 커스텀 URL 스킴을 사용하려면 다음 두 가지 설정이 모두 필요합니다.
${Project}
> ios 폴더를 우클릭하여 Xcode에서 프로젝트를 열고 설정${Project}
> ios > Runner > Info.plist${Project}
> ios 폴더를 우클릭하여 Xcode에서 프로젝트를 열고 설정설치 및 설정을 완료했다면, 초기화를 거쳐 Flutter SDK를 사용할 수 있습니다.
아래 예제를 참고하여 main()
함수 안에서 Flutter SDK 초기화 메서드인 init()
메서드를 호출합니다. runApp()
메서드 호출 전 Flutter SDK를 초기화해야 한다는 점에 주의합니다.
초기화 시 [내 애플리케이션] > [앱 키]에서 확인한 앱 키를 입력해야 합니다. init()
메서드 호출 시 다음 내용을 참고해 필요한 앱 키를 전달합니다.
init()
호출 시 nativeAppKey
파라미터로 네이티브 앱 키 전달init()
호출 시 javaScriptAppKey
파라미터로 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());
...
}
하이브리드 애플리케이션(이하 하이브리드 앱) 내 웹 페이지에서 Flutter SDK 사용 시, 웹뷰(WebView)에서 Flutter SDK가 올바르게 동작하도록 하려면 추가 조치가 필요합니다. 필요한 조치 사항은 Kakao SDK for JavaScript와 동일하므로, JavaScript를 참고하여 조치합니다.
카카오톡 공유, 카카오톡 메시지, 카카오스토리의 커스텀 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