kakao developers

Flutter

이 문서는 Kakao SDK for Flutter(이하 Flutter SDK) 사용법을 설명합니다.

기능 소개

Flutter SDK는 Flutter로 작성된 애플리케이션(이하 앱)에서 카카오 API를 편리하게 호출할 수 있도록 도와주는 SDK입니다. Android, iOS, Web 앱 모두 정식으로 지원합니다.

요구 사양

Flutter SDK를 사용하기 위한 최소 요구 사양은 아래와 같습니다.

• Flutter 3.1.0 이상
• Dart 2.18.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)

설치

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 # 카카오톡 소셜(피커: 친구 선택하기)

$ flutter pub add kakao_flutter_sdk

$ flutter pub get

참고: 패키지 의존성

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

설정

플랫폼 정보 등록

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

• 네이티브 앱만 서비스: Android, iOS 플랫폼 정보 등록 필요
• 웹만 서비스: Web 플랫폼 정보 등록 필요
• 네이티브 앱, 웹 모두 서비스: Android, iOS, Web 플랫폼 정보 등록 필요

이 설정은 Flutter SDK를 통해 카카오 API를 사용하려면 필수입니다. 자세한 안내는 플랫폼 등록을 참고합니다.

참고: iOS 번들 ID 확인 방법

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

커스텀 URL 스킴

사용자가 카카오톡으로 로그인 후 서비스 앱으로 돌아오거나, 카카오톡 메시지 버튼 또는 링크로 서비스의 앱을 실행할 수 있는 커스텀 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 스킴의 활용과 관련된 추가 내용은 아래 항목을 참고합니다.

• 커스텀 URL 스킴 수신 방법
• 커스텀 URL 스킴으로 앱 실행 시 추가 정보 전달

Android

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

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]

초기화

설치 및 설정을 완료했다면, 초기화를 거쳐 Flutter SDK를 사용할 수 있습니다.

아래 예제를 참고하여 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());
    ...
}

참고

하이브리드 앱 가이드

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

커스텀 URL 스킴 수신 방법

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

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

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

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

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

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

커스텀 URL 스킴으로 앱 실행 시 추가 정보 전달

네이티브 앱의 경우, 커스텀 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 레퍼런스outlink