카카오톡 공유: Flutter

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

시작하기 전에

구현 방법 선택하기

bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  print('카카오톡으로 공유 가능');
} else {
  print('카카오톡 미설치: 웹 공유 기능 사용 권장');
}

프로젝트 설정

네이티브 앱 서비스에서 카카오톡 공유 API를 사용하려면 커스텀 URL 스킴(Custom URL Scheme)을 설정해야 합니다. 아래의 디바이스 환경별 프로젝트 설정 방법을 참고합니다.

• Android: 커스텀 URL 스킴
• iOS: 커스텀 URL 스킴

메시지 만들기

Flutter SDK는 카카오톡 공유 및 카카오톡 메시지를 통해 전송할 기본 템플릿을 생성할 때 DefaultTemplate 인터페이스를 구현한 다섯 가지 클래스를 사용합니다. 다음은 종류별 기본 템플릿 생성 예제입니다.

final FeedTemplate defaultFeed = FeedTemplate(
  content: Content(
    title: '딸기 치즈 케익',
    description: '#케익 #딸기 #삼평동 #카페 #분위기 #소개팅',
    imageUrl: Uri.parse(
        'https://mud-kage.kakao.com/dn/Q2iNx/btqgeRgV54P/VLdBs9cvyn8BJXB3o7N8UK/kakaolink40_original.png'),
    link: Link(
        webUrl: Uri.parse('https://developers.kakao.com'),
        mobileWebUrl: Uri.parse('https://developers.kakao.com')),
  ),
  itemContent: ItemContent(
    profileText: 'Kakao',
    profileImageUrl: Uri.parse(
        'https://mud-kage.kakao.com/dn/Q2iNx/btqgeRgV54P/VLdBs9cvyn8BJXB3o7N8UK/kakaolink40_original.png'),
    titleImageUrl: Uri.parse(
        'https://mud-kage.kakao.com/dn/Q2iNx/btqgeRgV54P/VLdBs9cvyn8BJXB3o7N8UK/kakaolink40_original.png'),
    titleImageText: 'Cheese cake',
    titleImageCategory: 'cake',
    items: [
      ItemInfo(item: 'cake1', itemOp: '1000원'),
      ItemInfo(item: 'cake2', itemOp: '2000원'),
      ItemInfo(item: 'cake3', itemOp: '3000원'),
      ItemInfo(item: 'cake4', itemOp: '4000원'),
      ItemInfo(item: 'cake5', itemOp: '5000원')
    ],
    sum: 'total',
    sumOp: '15000원',
  ),
  social: Social(likeCount: 286, commentCount: 45, sharedCount: 845),
  buttons: [
    Button(
      title: '웹으로 보기',
      link: Link(
        webUrl: Uri.parse('https: //developers.kakao.com'),
        mobileWebUrl: Uri.parse('https: //developers.kakao.com'),
      ),
    ),
    Button(
      title: '앱으로보기',
      link: Link(
        androidExecutionParams: {'key1': 'value1', 'key2': 'value2'},
        iosExecutionParams: {'key1': 'value1', 'key2': 'value2'},
      ),
    ),
  ],
);

final ListTemplate defaultList = ListTemplate(
  headerTitle: 'WEEKLY MAGAZINE',
  headerLink: Link(
    webUrl: Uri.parse('https://developers.kakao.com'),
    mobileWebUrl: Uri.parse('https://developers.kakao.com'),
  ),
  contents: [
    Content(
      title: '취미의 특징, 탁구',
      description: '스포츠',
      imageUrl: Uri.parse(
          'https://mud-kage.kakao.com/dn/bDPMIb/btqgeoTRQvd/49BuF1gNo6UXkdbKecx600/kakaolink40_original.png'),
      link: Link(
        webUrl: Uri.parse('https://developers.kakao.com'),
        mobileWebUrl: Uri.parse('https://developers.kakao.com'),
      ),
    ),
    Content(
      title: '크림으로 이해하는 커피이야기',
      description: '음식',
      imageUrl: Uri.parse(
          'https://mud-kage.kakao.com/dn/QPeNt/btqgeSfSsCR/0QJIRuWTtkg4cYc57n8H80/kakaolink40_original.png'),
      link: Link(
        webUrl: Uri.parse('https://developers.kakao.com'),
        mobileWebUrl: Uri.parse('https://developers.kakao.com'),
      ),
    ),
    Content(
      title: '감성이 가득한 분위기',
      description: '사진',
      imageUrl: Uri.parse(
          'https://mud-kage.kakao.com/dn/c7MBX4/btqgeRgWhBy/ZMLnndJFAqyUAnqu4sQHS0/kakaolink40_original.png'),
      link: Link(
        webUrl: Uri.parse('https://developers.kakao.com'),
        mobileWebUrl: Uri.parse('https://developers.kakao.com'),
      ),
    ),
  ],
  buttons: [
    Button(
      title: '웹으로 보기',
      link: Link(
        webUrl: Uri.parse('https://developers.kakao.com'),
        mobileWebUrl: Uri.parse('https://developers.kakao.com'),
      ),
    ),
    Button(
      title: '앱으로 보기',
      link: Link(
        androidExecutionParams: {'key1': 'value1', 'key2': 'value2'},
        iosExecutionParams: {'key1': 'value1', 'key2': 'value2'},
      ),
    ),
  ],
);

final LocationTemplate defaultLocation = LocationTemplate(
  address: '경기 성남시 분당구 판교역로 235 에이치스퀘어 N동 8층',
  content: Content(
    title: '신메뉴 출시❤️ 체리블라썸라떼',
    description: '이번 주는 체리블라썸라떼 1+1',
    imageUrl: Uri.parse(
        'https://mud-kage.kakao.com/dn/bSbH9w/btqgegaEDfW/vD9KKV0hEintg6bZT4v4WK/kakaolink40_original.png'),
    link: Link(
      webUrl: Uri.parse('https://developers.kakao.com'),
      mobileWebUrl: Uri.parse('https://developers.kakao.com'),
    ),
  ),
  social: Social(likeCount: 286, commentCount: 45, sharedCount: 845),
);

final CommerceTemplate defaultCommerce = CommerceTemplate(
  content: Content(
    title: 'Ivory long dress (4 Color)',
    imageUrl: Uri.parse(
        'https://mud-kage.kakao.com/dn/RY8ZN/btqgOGzITp3/uCM1x2xu7GNfr7NS9QvEs0/kakaolink40_original.png'),
    link: Link(
      webUrl: Uri.parse('https://developers.kakao.com'),
      mobileWebUrl: Uri.parse('https://developers.kakao.com'),
    ),
  ),
  commerce: Commerce(
    regularPrice: 208800,
    discountPrice: 146160,
    discountRate: 30,
    productName: "Ivory long dress",
    currencyUnit: "₩",
    currencyUnitPosition: 1,
  ),
  buttons: [
    Button(
      title: '구매하기',
      link: Link(
        webUrl: Uri.parse('https://developers.kakao.com'),
        mobileWebUrl: Uri.parse('https://developers.kakao.com'),
      ),
    ),
    Button(
      title: '공유하기',
      link: Link(
        androidExecutionParams: {'key1': 'value1', 'key2': 'value2'},
        iosExecutionParams: {'key1': 'value1', 'key2': 'value2'},
      ),
    )
  ],
);

final TextTemplate defaultText = TextTemplate(
  text:
      '카카오톡 공유는 카카오 플랫폼 서비스의 대표 기능으로써 사용자의 모바일 기기에 설치된 카카오 플랫폼과 연동하여 다양한 기능을 실행할 수 있습니다.\n현재 이용할 수 있는 카카오톡 공유는 다음과 같습니다.\n카카오톡링크\n카카오톡을 실행하여 사용자가 선택한 채팅방으로 메시지를 전송합니다.',
  link: Link(
    webUrl: Uri.parse('https: //developers.kakao.com'),
    mobileWebUrl: Uri.parse('https: //developers.kakao.com'),
  ),
);

final CalendarTemplate defaultCalendar = CalendarTemplate(
  idType: IdType.event,
  id: '${YOUR_EVENT_ID}',
  content: Content(
    title: '1월 신작 평론 모임',
    description: '따끈한 신작 감상평을 나누는 월간 모임에 초대합니다.',
    imageUrl: Uri.parse(
        'http://k.kakaocdn.net/dn/dFUqwp/bl3SUTqb2VV/VFSqyPpKUzZVVMcmotN9A0/kakaolink40_original.png'),
    link: Link(
      webUrl: Uri.parse('https://developers.kakao.com'),
      mobileWebUrl: Uri.parse('https://developers.kakao.com'),
    ),
  ),
  buttons: [
    Button(
      title: '모임 주제 보기',
      link: Link(
        webUrl: Uri.parse('https://developers.kakao.com'),
        mobileWebUrl: Uri.parse('https://developers.kakao.com'),
      ),
    )
  ],
);

기본 템플릿으로 메시지 보내기

기본 정보

기본 템플릿을 사용해 카카오톡으로 메시지를 공유합니다.

요청

메시지 공유 방법 확인하기와 예제를 참고하여 다음 중 원하는 방법으로 공유하기를 구현합니다. 두 가지 공유 방법을 모두 사용하도록 구현할 수도 있습니다.

카카오톡 실행이 가능한 경우, ShareClient의 shareDefault()을 호출합니다. 요청 성공 시, 카카오톡에서 기본 템플릿으로 메시지를 공유하는 화면으로 이동할 수 있는 Uri가 반환됩니다. 반환된 Uri를 전달하여 ShareClient의 launchKakaoTalk() 메서드를 호출해 공유하기를 실행합니다.

카카오톡 실행이 불가능한 경우, WebSharerClient의 makeDefaultUrl()를 호출합니다. 요청 성공 시, 웹 공유 기능을 실행하는 Uri가 반환됩니다. 반환된 Uri를 전달하여 launchBrowserTab() 메서드를 호출해 공유하기를 실행합니다. 웹 환경에서는 launchBrowserTab() 호출 시 popupOpen 파라미터 값을 true로 지정해 카카오톡 공유 페이지를 팝업으로 열 수 있습니다.

예제

// 카카오톡 실행 가능 여부 확인
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    Uri uri =
        await ShareClient.instance.shareDefault(template: defaultFeed);
    await ShareClient.instance.launchKakaoTalk(uri);
    print('카카오톡 공유 완료');
  } catch (error) {
    print('카카오톡 공유 실패 $error');
}
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance
        .makeDefaultUrl(template: defaultFeed);
    await launchBrowserTab(shareUrl, popupOpen: true);
  } catch (error) {
    print('카카오톡 공유 실패 $error');
  }
}

사용자 정의 템플릿으로 메시지 보내기

기본 정보

[도구] > [메시지 템플릿]에서 직접 구성한 사용자 정의 템플릿을 사용해 카카오톡으로 메시지를 공유합니다.

요청

메시지 공유 방법 확인하기와 예제를 참고하여 다음 중 원하는 방법으로 공유하기를 구현합니다. 두 가지 공유 방법을 모두 사용하도록 구현할 수도 있습니다.

카카오톡 실행이 가능한 경우, ShareClient의 shareCustom()을 호출합니다. 요청 성공 시, 카카오톡에서 기본 템플릿으로 메시지를 공유하는 화면으로 이동할 수 있는 Uri가 반환됩니다. 반환된 Uri를 전달하여 ShareClient의 launchKakaoTalk() 메서드를 호출해 공유하기를 실행합니다.

카카오톡 실행이 불가능한 경우, WebSharerClient의 makeCustomUrl()를 호출합니다. 요청 성공 시, 웹 공유 기능을 실행하는 Uri가 반환됩니다. 반환된 Uri를 전달하여 launchBrowserTab() 메서드를 호출해 공유하기를 실행합니다. 웹 환경에서는 launchBrowserTab() 호출 시 popupOpen 파라미터 값을 true로 지정해 카카오톡 공유 페이지를 팝업으로 열 수 있습니다.

예제

// 사용자 정의 템플릿 ID
int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';
// 카카오톡 실행 가능 여부 확인
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    Uri uri =
        await ShareClient.instance.shareCustom(templateId: templateId);
    await ShareClient.instance.launchKakaoTalk(uri);
    print('카카오톡 공유 완료');
  } catch (error) {
    print('카카오톡 공유 실패 $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance.makeCustomUrl(
        templateId: templateId, templateArgs: {'key1': 'value1'});
    await launchBrowserTab(shareUrl, popupOpen: true);
  } catch (error) {
    print('카카오톡 공유 실패 $error');
  }
}

기본 템플릿으로 스크랩 메시지 보내기

기본 정보

지정한 웹 페이지를 스크랩한 정보로 스크랩 메시지를 구성하여 공유합니다.

요청

메시지 공유 방법 확인하기와 예제를 참고하여 다음 중 원하는 방법으로 공유하기를 구현합니다. 두 가지 공유 방법을 모두 사용하도록 구현할 수도 있습니다.

카카오톡 실행이 가능한 경우, ShareClient의 shareScrap()을 호출합니다. 요청 성공 시, 카카오톡에서 기본 템플릿으로 메시지를 공유하는 화면으로 이동할 수 있는 Uri가 반환됩니다. 반환된 Uri를 전달하여 ShareClient의 launchKakaoTalk() 메서드를 호출해 공유하기를 실행합니다.

카카오톡 실행이 불가능한 경우, WebSharerClient의 makeScrapUrl()를 호출합니다. 요청 성공 시, 웹 공유 기능을 실행하는 Uri가 반환됩니다. 반환된 Uri를 전달하여 launchBrowserTab() 메서드를 호출해 공유하기를 실행합니다. 웹 환경에서는 launchBrowserTab() 호출 시 popupOpen 파라미터 값을 true로 지정해 카카오톡 공유 페이지를 팝업으로 열 수 있습니다.

예제

// 스크랩할 웹 페이지 URL
String url = "https://developers.kakao.com";
// 카카오톡 실행 가능 여부 확인
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    Uri uri = await ShareClient.instance.shareScrap(url: url);
    await ShareClient.instance.launchKakaoTalk(uri);
    print('카카오톡 공유 완료');
  } catch (error) {
    print('카카오톡 공유 실패 $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance
        .makeScrapUrl(url: url, templateArgs: {'key1': 'value1'});
    await launchBrowserTab(shareUrl, popupOpen: true);
  } catch (error) {
    print('카카오톡 공유 실패 $error');
  }
}

사용자 정의 템플릿으로 스크랩 메시지 보내기

기본 정보

[도구] > [메시지 템플릿]에서 직접 구성한 사용자 정의 템플릿에 지정한 웹 페이지의 스크랩 정보를 대입해 메시지를 구성하고 공유합니다.

요청

메시지 공유 방법 확인하기와 예제를 참고하여 다음 중 원하는 방법으로 공유하기를 구현합니다. 두 가지 공유 방법을 모두 사용하도록 구현할 수도 있습니다.

카카오톡 실행이 가능한 경우, ShareClient의 shareScrap()을 호출합니다. 웹 페이지 스크랩 정보를 대입할 사용자 정의 템플릿의 ID를 반드시 전달해야 합니다.

요청 성공 시, 카카오톡에서 기본 템플릿으로 메시지를 공유하는 화면으로 이동할 수 있는 Uri가 반환됩니다. 반환된 Uri를 전달하여 ShareClient의 launchKakaoTalk() 메서드를 호출해 공유하기를 실행합니다.

카카오톡 실행이 불가능한 경우, WebSharerClient의 makeScrapUrl()를 호출합니다. 웹 페이지 스크랩 정보를 대입할 사용자 정의 템플릿의 ID를 반드시 전달해야 합니다.

요청 성공 시, 웹 공유 기능을 실행하는 Uri가 반환됩니다. 반환된 Uri를 전달하여 launchBrowserTab() 메서드를 호출해 공유하기를 실행합니다. 웹 환경에서는 launchBrowserTab() 호출 시 popupOpen 파라미터 값을 true로 지정해 카카오톡 공유 페이지를 팝업으로 열 수 있습니다.

예제

// 사용자 정의 템플릿 ID
int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';
// 스크랩할 웹 페이지 URL
String url = "https://developers.kakao.com";
// 카카오톡 실행 가능 여부 확인
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    Uri uri = await ShareClient.instance.shareScrap(url: url, templateId: templateId);
    await ShareClient.instance.launchKakaoTalk(uri);
    print('카카오톡 공유 완료');
  } catch (error) {
    print('카카오톡 공유 실패 $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance
        .makeScrapUrl(url: url, templateId: templateId, templateArgs: {'key1': 'value1'});
    await launchBrowserTab(shareUrl, popupOpen: true);
  } catch (error) {
    print('카카오톡 공유 실패 $error');
  }
}

콜백 사용자 정의 파라미터 설정하기

전송 성공 알림은 사용자가 선택한 친구나 채팅방으로 카카오톡 공유 메시지가 성공적으로 전달된 경우, 카카오디벨로퍼스에 설정된 콜백 URL로 메시지가 성공적으로 전달되었음을 알려주는 기능입니다.

전송 성공 알림은 카카오톡 공유 메시지 전송 시에만 사용할 수 있고, 카카오톡 메시지 전송에는 지원되지 않습니다. 카카오톡 공유는 사용자가 카카오톡에서 메시지를 전송하므로 서비스에서 전송 성공 여부를 직접 확인할 수 없기 때문에 메시지 전송 성공 시 알림을 받는 서버 콜백(Callback) 기능을 제공합니다.

이 기능을 사용하려면 다음을 수행해야 합니다.

1. 카카오톡 공유 전송 성공 알림 설정을 참고하여 콜백 URL과 요청 방법(Method) 설정
2. 카카오톡 공유 콜백을 받을 서버 구현
3. 카카오톡 공유 API 호출 시 사용자 정의(Custom) 파라미터 전달
4. 서비스 서버의 콜백 URL로 전달되는 알림에 대한 처리 구현

서비스 서버로 보내지는 카카오톡 공유 전송 성공 알림은 자세한 메시지 전송 관련 정보를 포함하지 않습니다. 어떤 메시지의 전송 결과인지, 사용자가 어떤 콘텐츠를 공유했는지 등 서비스에서 필요한 추가 정보를 파악하려면 사용자 정의(Custom) 파라미터를 사용해야 합니다. 또한, 사용자 정의 파라미터를 포함하지 않은 카카오톡 공유 메시지는 카카오톡 공유 전송 성공 알림이 전달되지 않습니다.

사용자 정의 파라미터는 serverCallbackArgs 파라미터를 통해 카카오톡 공유 요청 시에 전달해야 하며, 키에는 시스템 예약어인 CHAT_TYPE, HASH_CHAT_ID, TEMPLATE_ID를 사용할 수 없습니다. 해당 키는 카카오톡 공유 전송 성공 알림의 명세에 정의된 값으로 알림에 포함됩니다.

다음은 사용자 정의 파라미터를 포함한 카카오톡 공유 요청 예제입니다.

try {
  // serverCallbackArgs 파라미터로 사용자 정의 파라미터 전달
  // 해당 파라미터 미사용 시 카카오톡 공유 전송 성공 알림 전달되지 않음
  Uri uri =
      await ShareClient.instance.defaultTemplate(template: defaultFeed, serverCallbackArgs: {'key1': 'value1'});
  await ShareClient.instance.launchKakaoTalk(uri);
  print('카카오톡 공유 완료');
} catch (error) {
  print('카카오톡 공유 실패 $error');
}

이미지 업로드하기

기본 정보

메시지에 넣을 이미지는 URL 형태로 메시지 템플릿 구성 시에 첨부하거나, 메시지 템플릿 도구에서 미리 업로드할 수 있습니다. 이미지 파일은 카카오 서버에 업로드하거나 스크랩해야 메시지 전송에 사용할 수 있습니다.

ShareClient에서 제공하는 메서드를 사용해 카카오 서버에 이미지를 업로드하거나 스크랩할 수 있습니다. 파일 용량 5MB 이하 이미지만 업로드할 수 있습니다. 카카오 서버에 업로드된 이미지는 최대 100일간 보관되고, 기간이 지나면 자동으로 삭제됩니다.

이미지 파일을 카카오 서버에 업로드하려면 uploadImage()를 호출합니다. 업로드할 이미지 파일은 다음 파라미터 중 하나를 사용해 전달합니다.

• image: 이미지를 File 형식으로 전달해 업로드
• byteData: 이미지를 ByteData 형식으로 전달해 업로드

웹 상의 이미지를 카카오 서버에 스크랩하려면 scrapImage()를 호출합니다.

요청 성공 시 ImageUploadResult 객체가 반환됩니다. 해당 객체 내부의 ImageInfo에서 메시지 전송에 사용할 이미지 URL 등 업로드된 이미지 정보를 확인할 수 있습니다.

예제

이미지 업로드

// 로컬 이미지 파일
// 이 예제에서는 프로젝트 리소스로 추가한 이미지 파일을 사용했습니다.
// 갤러리 등 서비스에 필요한 사진 파일을 준비합니다.
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));

try {
  // 카카오 이미지 서버로 업로드
  ImageUploadResult imageUploadResult =
      await ShareClient.instance.uploadImage(image: file);
  print('이미지 업로드 성공'
        '\n${imageUploadResult.infos.original}');
} catch (error) {
  print('이미지 업로드 실패 $error');
}

// 이 샘플에서는 file_picker를 사용해 이미지 파일을 가져왔습니다.
var filePickerResult = await FilePicker.platform.pickFiles();

if (filePickerResult != null) {
  var byteData = filePickerResult.files.first.bytes;

  try {
    // 카카오 이미지 서버로 업로드
    ImageUploadResult imageUploadResult =
        await ShareClient.instance.uploadImage(byteData: byteData);
    Log.i(context, tag,
        '이미지 업로드 성공\n${imageUploadResult.infos.original}');
  } catch (e) {
    Log.e(context, tag, '이미지 업로드 실패', e);
  }
}

이미지 스크랩

// 원본 이미지 URL
String url =
    'https://t1.kakaocdn.net/kakaocorp/Service/KakaoTalk/pc/slide/talkpc_theme_01.jpg';

try {
  // 카카오 서버에 이미지 스크랩
  ImageUploadResult imageUploadResult =
      await ShareClient.instance.scrapImage(imageUrl: url);
  print('이미지 스크랩 성공'
        '\n${imageUploadResult.infos.original}');
} catch (error) {
  print('이미지 스크랩 실패 $error');
}

더 보기

메시지 템플릿 도구outlink