- 문서>
- 카카오스토리>
- Flutter
카카오스토리
Flutter
이 문서는 Kakao SDK for Flutter(이하 Flutter SDK)를 사용한 카카오스토리 기능 구현 방법을 안내합니다.
시작하기 전에
패키지 설정
카카오스토리 API를 사용하려면 설치를 참고하여 pubspec.yaml 파일에 Flutter SDK 전체 또는 카카오스토리 패키지에 대한 의존성을 추가해야 합니다.
프로젝트 설정
네이티브 앱 서비스에서 게시된 스토리의 링크를 통해 서비스 앱을 실행하려면 커스텀 URL 스킴(Custom URL Scheme)을 설정해야 합니다. 아래의 디바이스 환경별 프로젝트 설정 방법을 참고합니다.
- Android: 커스텀 URL 스킴
- iOS: 커스텀 URL 스킴
사용자 확인하기
기본 정보
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
|---|---|---|---|---|
| - | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | - | isStoryUser() |
카카오스토리 미사용으로 인한 에러를 방지하기 위해, 현재 로그인한 사용자가 카카오스토리를 사용하고 있는지 확인합니다. StoryApi의 isStoryUser()를 호출합니다.
요청 성공 시, 사용자가 카카오스토리를 사용하고 있다면 true를 반환합니다. 사용자가 카카오스토리를 사용하지 않는 경우 false를 반환하며, 이 경우 해당 사용자는 프로필 가져오기나 스토리 쓰기를 비롯한 카카오스토리 기능을 이용할 수 없도록 처리합니다.
try {
bool isStoryUser = await StoryApi.instance.isStoryUser();
print('카카오스토리 사용 여부: $isStoryUser');
} catch (error) {
print('카카오스토리 사용 여부 확인 실패 $error');
}
프로필 가져오기
기본 정보
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
|---|---|---|---|---|
| - | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진 카카오스토리 프로필 URL |
profile()StoryProfile |
현재 로그인한 사용자의 카카오스토리 프로필을 불러옵니다. StoryApi의 profile()을 호출합니다.
사용자는 카카오계정, 카카오톡, 카카오스토리에 각각 프로필을 설정할 수 있습니다. StoryApi의 profile()은 사용자가 카카오스토리에 설정한 프로필 정보를 제공하므로, 카카오톡 프로필 가져오기의 프로필 정보와 다를 수 있습니다.
요청 성공 시, 사용자의 카카오스토리 프로필 정보를 담은 StoryProfile 객체가 반환됩니다. 프로필 정보의 구성은 동의 항목 설정에 따라 달라질 수 있으므로 REST API 응답 정보를 함께 참고합니다.
try {
StoryProfile profile = await StoryApi.instance.profile();
print('카카오스토리 프로필 받기 성공'
'\n닉네임: ${profile.nickname}'
'\n프로필사진: ${profile.thumbnailUrl}'
'\n생일: ${profile.birthday}');
} catch (error) {
print('카카오스토리 프로필 받기 실패 $error');
}
스토리 쓰기
현재 로그인한 사용자의 카카오스토리에 새로운 스토리를 작성합니다.
스토리 종류
스토리 종류별로 글, 사진과 글, 링크로 나뉜 세 가지 메서드를 제공합니다.
| 타입 | 설명 | 메서드 |
|---|---|---|
| 글(Note) | 텍스트로 구성된 스토리 | postNote() |
| 사진(Photo) | 텍스트와 사진으로 구성된 스토리 | postPhoto() |
| 링크(Link) | 텍스트와 스크랩할 웹 페이지에서 얻은 정보로 구성된 스토리 | postLink() |
세 가지 메서드는 각각 공통 파라미터와 스토리 종류별 고유 파라미터를 사용합니다. 아래 공통 파라미터는 스토리 종류와 관계없이 항상 전달해야 하는 파라미터입니다.
공통 파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| permission | StoryPermission |
스토리 공개 범위 다음 중 하나 PUBLIC: 전체 공개, FRIEND: 친구 공개, ONLY_ME: 나만 보기(기본값: PUBLIC) |
X |
| enableShare | bool |
친구 공개 스토리인 경우, 공유 가능 여부 설정 (기본값: false) |
X |
| androidExecParams | String |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 Android 앱 실행 URL에 붙일 파라미터 | X |
| iosExecParams | String |
스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 iOS 앱 실행 URL에 붙일 파라미터 | X |
| androidMarketParams | String |
스토리에서 오픈마켓으로 이동할 때 실행 URL에 붙일 파라미터 | X |
| iosMarketParams | String |
스토리에서 앱스토어로 이동할 때 실행 URL에 붙일 파라미터 | X |
세 가지 메서드 모두 요청 성공 시 작성된 스토리 ID를 담은 StoryPostResult 객체를 반환합니다.
StoryPostResult
| 이름 | 타입 | 설명 |
|---|---|---|
| id | String |
작성된 스토리 ID |
스토리 종류별 고유 파라미터와 호출 예제는 아래 각 개발 가이드에서 확인할 수 있습니다.
글 스토리 쓰기
기본 정보
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
|---|---|---|---|---|
| - | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
postNote() |
사진이나 웹 페이지 URL 등 다른 요소 없이 글로만 구성된 스토리를 게시합니다. StoryApi의 postNote()를 호출합니다.
요청 시 글 내용을 담은 content 파라미터를 필수 전달해야 합니다. 필요에 따라 공통 파라미터를 함께 사용할 수 있습니다.
파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| content | String |
스토리에 들어갈 글(최대: 2048자) | O |
예제
요청 성공 시 작성된 스토리 ID를 담은 StoryPostResult 객체를 반환합니다.
try {
String content = "Posting note from Kakao SDK Sample";
StoryPostResult storyPostResult =
await StoryApi.instance.postNote(content: content);
print('스토리 쓰기 성공 [${storyPostResult.id}]');
} catch (error) {
print('스토리 쓰기 실패 $error');
}
사진 스토리 쓰기
기본 정보
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
|---|---|---|---|---|
| - | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
postPhoto()upload() |
사진과 글로 구성된 스토리를 게시합니다. StoryApi의 postPhoto()를 호출합니다.
먼저 StoryApi의 upload()를 호출해 카카오스토리에 게시할 사진을 카카오 서버로 업로드해야 합니다. 파일 업로드 성공 시, 업로드된 파일의 경로 값이 <List<String> 형식으로 반환됩니다.
파일 업로드 후 반환받은 값을 postPhoto() 호출 시 images 파라미터로 전달해야 합니다. 필요에 따라 글 내용을 담은 content 파라미터와 공통 파라미터를 함께 사용할 수 있습니다.
파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| images | List<String> |
스토리에 들어갈 이미지들의 URL | O |
| content | String |
스토리에 들어갈 글(최대: 2048자) | X |
예제
요청 성공 시 작성된 스토리 ID를 담은 StoryPostResult 객체를 반환합니다.
// 이 예제에서는 프로젝트 리소스로 추가한 이미지 파일을 사용했습니다.
// 갤러리 등 서비스에 필요한 사진 파일을 준비합니다.
// 업로드할 사진 파일
ByteData byteData = await rootBundle.load('assets/images/cat1.png');
// 이 예제에서는 path_provider를 사용해 프로젝트 리소스를 이미지 파일로 저장했습니다.
File tempFile =
File('${(await getTemporaryDirectory()).path}/cat1.png');
File file = await tempFile.writeAsBytes(byteData.buffer
.asUint8List(byteData.offsetInBytes, byteData.lengthInBytes));
// 스토리에 업로드할 사진 파일 업로드
List<String> images;
try {
images = await StoryApi.instance.upload([file]);
print('사진 업로드 성공 $images');
} catch (error) {
print('사진 업로드 실패 $error');
return;
}
// 업로드한 사진 파일 정보로 사진 스토리 쓰기
try {
String content = 'Posting photo from Kakao SDK Sample.';
StoryPostResult storyPostResult = await StoryApi.instance
.postPhoto(images: images, content: content);
print('스토리 쓰기 성공 [${storyPostResult.id}]');
} catch (error) {
print('스토리 쓰기 실패 $error');
}
링크 스토리 쓰기
기본 정보
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
|---|---|---|---|---|
| - | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 작성(story_publish) |
postLink()linkInfo()LinkInfo |
웹 페이지를 공유하는 스토리를 게시합니다. StoryApi의 postLink()를 호출합니다.
먼저 StoryApi의 linkInfo()를 호출해 공유할 웹 페이지의 정보를 스크랩해야 합니다. linkInfo() 호출 시, 공유할 웹 페이지의 URL을 전달해야 합니다. 웹 페이지 스크랩 성공 시, 해당 웹 페이지의 스크랩 정보를 담은 LinkInfo 객체가 반환됩니다.
웹 페이지 스크랩을 통해 반환받은 LinkInfo 객체를 postLink() 호출 시 linkInfo 파라미터로 전달해야 합니다. 필요에 따라 글 내용을 담은 content 파라미터와 공통 파라미터를 함께 사용할 수 있습니다.
파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| linkInfo | LinkInfo |
웹 페이지 스크랩 정보 | O |
| content | String |
스토리에 들어갈 글(최대: 2048자) | X |
예제
요청 성공 시 작성된 스토리 ID를 담은 StoryPostResult 객체를 반환합니다.
// 웹 페이지 스크랩
LinkInfo linkInfo;
try {
linkInfo =
await StoryApi.instance.linkInfo('https://www.kakaocorp.com');
print('웹 페이지 스크랩 성공 ${linkInfo.title}');
} catch (error) {
print('링크 만들기 실패 $error');
return;
}
// 웹 페이지 스크랩 정보로 링크 스토리 쓰기
String content = 'Posting link from Kakao SDK Sample.';
try {
StoryPostResult storyPostResult = await StoryApi.instance
.postLink(linkInfo: linkInfo, content: content);
print('스토리 쓰기 성공 [${storyPostResult.id}]');
} catch (error) {
print('스토리 쓰기 실패 $error');
}
내 스토리 가져오기
현재 로그인한 사용자의 카카오스토리에서 스토리 목록을 불러옵니다.
다음 두 가지 방법으로 스토리를 가져올 수 있습니다.
- 여러 개의 스토리 가져오기를 통해 최근 스토리 정보 받아 특정 스토리를 스토리 ID로 지정하여 스토리 정보 받기
- 여러 개의 스토리 가져오기를 통해 최근 스토리 정보 받기
스토리 가져오기 요청 시 하나의 스토리를 요청하는지, 여러 개의 스토리를 요청하는지에 따라 전달해야 할 파라미터가 다릅니다.
여러 개의 스토리 가져오기
기본 정보
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
|---|---|---|---|---|
| - | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 목록(story_read) |
stories()Story |
현재 로그인한 사용자의 카카오스토리에서 스토리 목록을 불러옵니다. StoryApi의 stories()를 호출합니다.
요청 성공 시, 사용자의 스토리 목록인 List<Story>를 반환합니다. stories()는 기본적으로 가장 최근 스토리들의 정보를 제공합니다. lastId 파라미터로 조회 기준점으로 삼을 스토리 ID를 전달하여, 그 이전에 작성된 스토리만 불러올 수 있습니다.
stories() 응답의 각 Story 객체는 스토리 ID와 내용, 댓글과 좋아요 수를 포함합니다. 하지만 댓글 목록인 comments, 느낌 목록인 likes의 값은 포함하지 않습니다. 해당 정보는 스토리 ID로 특정 스토리를 지정해 가져오는 story()를 호출하여 제공받을 수 있습니다.
파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| lastId | String |
정보를 원하는 마지막 스토리 아이디 해당 스토리를 제외하고, 그 이전에 작성된 스토리 정보가 제공됨 기본 값은 가장 최근 작성된 스토리 아이디 파라미터 미포함 시 가장 최근 스토리 정보부터 제공 |
X |
예제
try {
List<Story> stories = await StoryApi.instance.stories();
print('스토리 가져오기 성공\n$stories');
} catch (error) {
print('스토리 가져오기 실패 $error');
}
하나의 스토리 가져오기
기본 정보
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
|---|---|---|---|---|
| - | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 목록(story_read) |
story()Story |
하나의 스토리를 지정해 요청합니다.
story()는 현재 로그인한 사용자의 카카오스토리에서 지정한 스토리의 상세 정보를 가져옵니다. 스토리 id를 필수 전달해야 합니다. 특정 스토리 ID를 지정하여 요청하면 해당 스토리의 댓글을 포함한 상세 정보를 받을 수 있습니다.
파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | String |
상세 정보를 가져올 스토리 ID | O |
예제
아래는 현재 로그인한 사용자의 전체 스토리 목록을 가져온 후, 그중 첫 번째 스토리를 지정하여 상세 정보를 가져오는 예제입니다.
// 전체 스토리 가져오기
List<Story> stories;
try {
stories = await StoryApi.instance.stories();
} catch (error) {
return;
}
if (stories.isEmpty) {
print('내 스토리가 하나도 없습니다');
return;
}
// 전체 스토리 중 첫 번째 스토리 아이디
String storyId = stories.first.id;
// 첫 번째 스토리 상세 정보 가져오기
try {
Story story = await StoryApi.instance.story(storyId);
print('스토리 가져오기 성공'
'\n아이디: ${story.id}'
'\n미디어 형식: ${story.mediaType}'
'\n작성일자: ${story.createdAt}'
'\n내용: ${story.content}');
} catch (error) {
print('스토리 가져오기 실패 $error');
}
내 스토리 삭제하기
기본 정보
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 | 레퍼런스 |
|---|---|---|---|---|
| - | 플랫폼 등록 카카오 로그인 활성화 동의 항목 |
필요 | 필요: 카카오스토리 글 목록(story_read) |
delete() |
현재 로그인한 사용자의 카카오스토리에서 지정한 ID에 해당하는 스토리를 삭제합니다. StoryApi의 delete()를 호출합니다.
요청 성공 시 반환되는 값은 없습니다.
예제
아래는 현재 로그인한 사용자의 전체 스토리 목록을 가져온 후, 그중 첫 번째 스토리를 삭제하는 예제입니다.
// 전체 스토리 가져오기
List<Story> stories;
try {
stories = await StoryApi.instance.stories();
} catch (error) {
print('스토리 가져오기 실패 $error');
return;
}
if (stories.isEmpty) {
print('내 스토리가 하나도 없습니다');
return;
}
// 전체 스토리 중 첫 번째 스토리 아이디
String storyId = stories.first.id;
// 첫 번째 스토리 삭제하기
try {
await StoryApi.instance.delete(storyId);
print('스토리 삭제 성공 [$storyId]');
} catch (error) {
print('스토리 삭제 실패 $error');
}