Getting started

This document guides how to use the Kakao SDK for Flutter("Flutter SDK") provided by the Kakao API platform.

Before you begin

Requirements

• Flutter 3.1.0 or higher
• Dart 2.18.0 or higher
• Android Studio 3.6.1 or higher
• Target Android API level 21 or higher (Android 5.0 or higher)
• Xcode 11.0 or higher
• iOS 11.0 or higher
• iOS Deployment Target 11.0 or higher

Note: External library dependency

The Flutter SDK uses the following libraries.

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

Supported web browser

The Flutter SDK supports web browsers below in the mobile and PC web environments.

* The Flutter SDK does not support Internet Explorer (IE).

** The default browser for development and debugging.

Packages

Note: Package dependency

Some packages in the Kakao SDK are dependent on another package. Each subordinate module is automatically added together.

Platform

Register the platform information that the service supports. Refer to Platform and the list below.

• Supports native apps only: Android, iOS
• Supports web only: Web
• Supports both Native apps and web: Android, iOS, Web

Note: How to check the bundle ID for iOS

The bundle ID for iOS platform information is on [Target] > [General] > [Bundle Identifier] in Xcode. Open the project in Xcode or [${Project}] > [ios] in Android Studio.

Project settings

Custom URL Scheme

To use a custom URL scheme on Android devices, set a custom URL scheme to launch the service app when a user clicks a button or link in the Kakao Talk message or to be returned to the service app when Kakao Login process is done.

After setting up a custom URL scheme, launching the service app using the kakao${YOUR_NATIVE_APP_KEY}://${PRODUCT_NAME} type scheme is available. Input the native app key to ${YOUR_NATIVE_APP_KEY} by referring to [My Application] > [App Keys]. Input the following host property of product to ${PRODUCT_NAME}.

• Kakao Login: oauth
• Kakao Talk Sharing, Kakao Talk Messaging: kakaolink

Android

Edit AndroidManifest.xml file in Flutter project ${Project} > android > app > src.

• Kakao Login
  • Add <activity> element for setting Redirect URI inside <application> element. See the example below.
• Kakao Talk Sharing, Kakao Talk Messaging
  • Inside of <application> element with android:name=".MainActivity" property, add <intent-filter> with <data android:host="${PRODUCT_NAME}" android:scheme="kakao${YOUR_NATIVE_APP_KEY}" /> type element. See the example below.
• For the app targeting Android 12 (API 31) or higher, declare android:exported and set it to true.

<application>

    <!-- Setting for Kakao Login Custom URI Scheme -->
    <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" />

            <!-- Setting for "kakao${YOUR_NATIVE_APP_KEY}://oauth" type app execution scheme -->
            <!-- Kakao Login Redirect URI -->
            <data android:scheme="kakao${YOUR_NATIVE_APP_KEY}" android:host="oauth"/>
        </intent-filter>
    </activity>

    <!-- Custom URL Scheme for Kakao Talk Sharing, Kakao Talk Messaging -->
    <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">
        <!-- skip -->

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

            <!-- Setting for "kakao${YOUR_NATIVE_APP_KEY}://oauth" type app execution scheme -->
            <!-- Kakao Talk Sharing, Kakao Talk Messaging -->
            <data android:host="kakaolink"
                android:scheme="kakao${YOUR_NATIVE_APP_KEY}" />
        </intent-filter>
    </activity>
</application>

iOS

To use a custom URL scheme on iOS devices, both setting below are required.

• Allowlist
  • Open the project in Xcode via [${Project}] > [ios] and set the allowlist
  • Setting path: [TARGET] > [Info] > [Custom iOS Target Properties]
  • Path of Info.plist file for manual setting: [${Project}] > [ios] > [Runner] > [Info.plist]
• URL Schemes
  • Open the project in Xcode via [${Project}] > [ios] and set the URL schemes
  • Setting path: [TARGET] > [Info] > [URL Types] > [URL Schemes]

Optional: Receiving a custom URL scheme

Explains to receive a custom URL scheme of Kakao Talk Sharing and Kakao Talk Messaging.

For an app that is not running, call the function below when the app runs.

String? url = await receiveKakaoScheme();
// Custom URL scheme is assigned to url. Write the usage code for the assigned scheme.

For a running app, you can receive a custom URL scheme via Stream provided by the Dart language. See the example below.

kakaoSchemeStream.listen((url) {
    // Custom URL scheme is assigned to url. Write the usage code for the assigned scheme.
}, onError: (e) {
    // Write an exception handling code for the error.
});

The above two functions should be called at the time after the Flutter SDK initialization. See Initialize.

Optional: Sending data when launch

In the case of native apps, additional data can be sent with a custom URL scheme for the service requirement. Set the key and value to androidExecutionParams, iosExecutionParams parameter. See the example below.

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

Optional: Hybrid app

To use the Flutter SDK for a web page on a hybrid application ("hybrid app"), develop a WebView as follows to work properly. Required actions are the same as Kakao SDK for JavaScript. Refer to Set up for hybrid app.

Install

To import the Kakao Flutter library in the project, set dependencies as follows.

dependencies:
  kakao_flutter_sdk: ^1.7.0 # Add all packages
  kakao_flutter_sdk_user: ^1.7.0 # Add for Kakao Login
  kakao_flutter_sdk_talk: ^1.7.0 # Add for Kakao Talk Messaging, Kakao Talk Social (Retrieve Kakao Talk profile, Retrieve list of friends)
  kakao_flutter_sdk_share: ^1.7.0 # Add for Kakao Talk Sharing
  kakao_flutter_sdk_navi: ^1.7.0 # Add for Kakao Navi
  kakao_flutter_sdk_friend: ^1.7.0 # Kakao Talk Social (Retrieve friends through picker)

$ flutter pub add kakao_flutter_sdk

$ flutter pub get

Initialize

Call the init() method in the main() function. Note that the initialization should be done before calling runApp() method.

App keys are required to initialize. Pass the app keys for the platforms that the service supports.

• Supports native apps only
  • Use Native app key to call Kakao APIs
  • Pass Native app key with nativeAppKey parameter when calling init() method
• Supports web only
  • Use JavaScript key to call Kakao APIs
  • Pass JavaScript key with javaScriptAppKey parameter when calling init() method
• Supports both Native apps and web
  • Use both JavaScript key and Native app key to call Kakao APIs
  • Pass Native app key with nativeAppKey parameter, and pass JavaScrip key with javaScriptAppKey when calling init() method

import 'package:kakao_flutter_sdk_common/kakao_flutter_sdk_common.dart';

// Initialize Flutter SDK for Kakao to use Kakao APIs.
void main() {
    ...

    // To finish Kakao Login process successfully, call the method below
    WidgetsFlutterBinding.ensureInitialized();

    // Initialize the Flutter SDK before call runApp()
    KakaoSdk.init(
      nativeAppKey: '${YOUR_NATIVE_APP_KEY}',
      javaScriptAppKey: '${YOUR_JAVASCRIPT_APP_KEY}',
    );

    runApp(MyApp());
    ...
}