페이지 이동경로
  • 문서>
  • Flutter>
  • 시작하기

Flutter

시작하기

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

패키지 정보

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

패키지 클라이언트 설명
kakao_flutter_sdk_common - 필수 요소를 담은 공통 패키지
iOS 앱을 위한 PrivacyInfo.xcprivacy 파일 포함

주요 기능: 초기화
kakao_flutter_sdk_auth AuthApi 카카오 로그인 인증 및 토큰 관리 패키지

주요 기능: 토큰 존재 여부 확인하기 API
kakao_flutter_sdk_user UserApi 카카오 로그인 API 패키지

주요 기능: 카카오 로그인 API, 사용자 정보 가져오기 API
kakao_flutter_sdk_share ShareClient 카카오톡 공유 API 패키지

주요 기능: 사용자 정의 템플릿으로 메시지 보내기 API
kakao_flutter_sdk_talk TalkApi 카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 패키지

주요 기능: 카카오톡 채널 간편 추가하기 API
kakao_flutter_sdk_template - 메시지 템플릿 패키지
kakao_flutter_sdk_friend PickerApi 피커 API 패키지

주요 기능: 피커: 친구 선택하기 API
kakao_flutter_sdk_navi NaviApi 카카오내비 API 패키지

패키지 의존성

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

패키지 의존성 구조도

준비

요구 사양

  • Flutter 3.22.0 이상
  • Dart 3.4.0 이상
  • Android Studio 3.0 이상
  • Android 5.0(API 21) 이상
  • iOS 11 이상
참고: 외부 라이브러리 의존성

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)

플랫폼

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

  • 네이티브 앱만 서비스: Android, iOS
  • 웹만 서비스: Web
  • 네이티브 앱, 웹 모두 서비스: Android, iOS, Web
참고: iOS 번들 ID 확인 방법

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

번들 ID 확인 1 번들 ID 확인 2

프로젝트 설정

커스텀 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와 동일하므로, 하이브리드 앱 가이드를 참고하여 조치합니다.

설치

1. pubspec.yaml 파일에 의존성 설정

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

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 패키지

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

$ flutter pub add kakao_flutter_sdk
주의

카카오톡 공유 패키지명이 1.2.0 버전부터 변경되었습니다. 공지사항을 참고합니다. - 1.2.0 미만 버전: kakao_flutter_sdk_link - 1.2.0 이상 버전: kakao_flutter_sdk_share

2. Flutter SDK 설치

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

$ flutter pub get

참고: 정식 서비스 시 변경 사항

Flutter SDK 0.9.0 이하 버전을 사용하고 있었다면, 최신 버전 업데이트 시 Flutter 마이그레이션을 참고하여 변경 사항을 적용해야 합니다.

초기화

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());
    ...
}