Flutter

이 문서는 Kakao SDK for Flutter(이하 Flutter SDK)를 사용한 카카오톡 소셜 API 구현 방법을 안내합니다.

시작하기 전에

패키지 설정

카카오톡 소셜 API를 사용하려면 설치를 참고하여 pubspec.yaml 파일에 Flutter SDK 전체 또는 카카오톡 패키지에 대한 의존성을 추가해야 합니다.

프로필 가져오기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의항목	필요	필요: 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진	profile() TalkProfile

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡 프로필 정보를 불러옵니다. 프로필 정보 제공 기준에 대한 이용 정책을 확인한 후 사용해야 합니다. TalkApi의 profile()을 호출합니다.

요청 성공 시, 사용자의 카카오톡 프로필 정보를 담은 TalkProfile 객체가 반환됩니다.

try {
    TalkProfile profile = await TalkApi.instance.profile();
    print('카카오톡 프로필 받기 성공'
        '\n닉네임: ${profile.nickname}'
        '\n프로필사진: ${profile.thumbnailUrl}');
} catch (error) {
    print('카카오톡 프로필 받기 실패 $error');
}

피커: 친구 선택하기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
필요: 사용 권한	플랫폼 등록 카카오 로그인 활성화 동의항목	필요	필요: 카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)	selectFriend() selectFriends()

사용자가 카카오톡 친구를 선택할 수 있는 피커를 호출합니다. 선택 유형에 따라 호출해야 할 함수가 다르므로, 서비스의 필요에 맞는 함수를 선택해 사용합니다.

선택 유형	함수
싱글 피커	selectFriend()
멀티 피커	selectFriends()

Flutter SDK의 피커는 환경에 따라 서로 다른 방식으로 동작하며 호출 방법에 차이가 있습니다. 아래 설명과 예제를 참고합니다.

• 네이티브 앱(Android, iOS)

  • 피커 호출 함수의 인수로 BuildContext 객체(context) 전달 필요, 예제 참고

• 웹(Web)

  • 팝업(Pop-up)과 리다이렉트(Redirect) 방식 지원

팝업과 리다이렉트 방식의 차이점은 아래를 참고합니다.

• 팝업 방식

  • 피커가 팝업창으로 나타나는 형태
  • 선택한 친구 정보를 Future로 전달
  • 웹뷰 사용 시 팝업 윈도우 관련 설정 필요, 하이브리드 앱 가이드 참고

• 리다이렉트 방식

  • 현재 창에서 피커로 이동하는 형태
  • 선택한 친구 정보를 URL 인코딩하여 서비스 서버의 returnUrl로 리다이렉트(HTTP 302 Redirect)하여 쿼리 스트링(Query string)으로 전달
  • [내 애플리케이션] > [플랫폼] > [Web]에 returnUrl의 사이트 도메인 등록 필수

피커의 구성 요소, 언어는 파라미터를 사용해 선택적으로 지정할 수 있습니다. 아래 표를 참고합니다.

파라미터

이름	타입	설명	필수
title	String	친구 피커의 타이틀 영역에 표시될 텍스트 (기본값: "친구 선택")	X
enableSearch	Boolean	친구 검색 기능 사용 여부 (기본값: true)	X
showMyProfile	Boolean	내 프로필 표시 여부 true일 경우 자신의 프로필 선택 가능 (기본값: true)	X
showFavorite	Boolean	즐겨찾기 친구 표시 여부 (기본값: true)	X
showPickedFriend	Boolean	멀티 피커 전용 선택한 친구 표시 여부 (기본값: true)	X
maxPickableCount	Number	멀티 피커 전용 선택 가능한 친구 수의 최대 값 minPickableCount 보다 크거나 같은 수 (기본값: 30, 최대: 100)	X
minPickableCount	Number	멀티 피커 전용 선택 가능한 친구 수의 최소 값 maxPickableCount 보다 작거나 같은 수 (기본값: 1, 최대: 100)	X
returnUrl	String	Flutter web 리다이렉트 방식 사용 시 필수 선택한 친구 정보를 받을 서비스 URL 비고: [내 애플리케이션] > [플랫폼] > [Web]에 등록된 사이트 도메인만 허용	X
enableBackButton	Boolean	Flutter web 팝업 방식은 사용 불가 뒤로가기 버튼 사용 여부 지정 true: 사용 false: 미사용 (기본값: true)	X

예제

네이티브 앱

// 파라미터 설정
var params = PickerFriendRequestParams(
    title: '멀티 친구 피커',
    enableSearch: true,
    showMyProfile: true,
    showFavorite: true,
    showPickedFriend: null,
    maxPickableCount: null,
    minPickableCount: null,
    enableBackButton: true,
);

// 피커 호출
try {
    SelectedUsers users = await PickerApi.instance.selectFriends(params: params, context: context);
    print('친구 선택 성공: ${users.users!.length}');
} catch(e) {
    print('친구 선택 실패: $e');
}

웹: 리다이렉트 방식

// 파라미터 설정 (리다이렉트 방식)
PickerFriendRequestParams params = PickerFriendRequestParams(
    title: '멀티 친구 피커',
    enableSearch: true,
    showMyProfile: true,
    showFavorite: true,
    showPickedFriend: null,
    maxPickableCount: null,
    minPickableCount: null,
    returnUrl: 'https://developers.kakao.com', // 필수
    enableBackButton: true,
);

// 피커 호출
// 친구 선택 성공: ${returnUrl}?selected=${SelectedUsers}
// 친구 선택 실패: ${returnUrl}?error=${Error}
await PickerApi.instance.selectFriends(params: params);

웹: 팝업 방식

// 파라미터 설정 (팝업 방식)
PickerFriendRequestParams params = PickerFriendRequestParams(
    title: '멀티 친구 피커',
    enableSearch: true,
    showMyProfile: true,
    showFavorite: true,
    showPickedFriend: null,
    maxPickableCount: null,
    minPickableCount: null,
);

// 피커 호출
try {
    SelectedUsers users = await PickerApi.instance.selectFriends(params: params);
    print('친구 선택 성공: ${users.users!.length}'):
} catch(e) {
    print('친구 선택 실패: $e');
}

사용자가 피커 화면에서 친구 선택을 완료하면 SelectedUsers 객체가 반환됩니다. 해당 객체는 선택된 각 친구의 정보를 SelectedUser 객체의 배열로 포함합니다. 요청에 실패했거나 문제가 발생한 경우 문제 해결에서 원인을 확인합니다.

SelectedUsers

이름	타입	설명	필수
selectedTotalCount	Number	친구 피커에서 사용자가 선택한 친구 수 선택한 친구 정보 목록의 친구 수와 다를 수 있음 참고: 피커를 통해 제공받은 친구 정보의 수가 선택한 친구 수보다 적은 경우	O
users	SelectedUser[]	선택한 친구 정보 목록	X

SelectedUser

이름	타입	설명	필수
uuid	String	친구마다 고유한 값을 가지는 참고용 코드(Code) 카카오톡 메시지 전송 시 사용 참고: 카카오톡을 탈퇴하거나 새로 가입할 경우 값이 변경될 수 있음	O
id	String	친구의 회원번호	X
profileNickname	String	카카오톡 프로필 닉네임	X
profileThumbnailImage	String	카카오톡 프로필 썸네일 이미지	X
favorite	Boolean	카카오톡 친구 즐겨찾기 설정 여부	X

친구 목록 가져오기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
필요: 사용 권한	플랫폼 등록 카카오 로그인 활성화 동의항목	필요	필요: 카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)	friends() Friends

현재 로그인한 사용자의 카카오톡 친구 목록을 불러옵니다. 친구 정보 제공 조건에 대한 이용 정책을 확인한 후 사용해야 합니다. TalkApi의 friends()를 호출합니다.

요청 성공 시, 친구의 수와 각 친구의 정보를 담은 Friends 객체가 반환됩니다. 해당 객체의 프로퍼티인 elements 하위에 각 친구의 정보가 Friend 객체로 포함됩니다. Friend 하위의 uuid 값은 카카오톡 메시지 전송에 사용됩니다.

try {
    Friends friends = await TalkApi.instance.friends();
    print('카카오톡 친구 목록 가져오기 성공'
        '\n${friends.elements?.map((friend) => friend.profileNickname).join('\n')}');
} catch (error) {
    print('카카오톡 친구 목록 가져오기 실패 $error');
}

더 보기

Flutter SDK 다운로드Flutter SDK 레퍼런스outlink