Flutter

This document describes how to integrate Kakao Talk Share APIs into your service with the Kakao SDK for Flutter ("Flutter SDK").

Before you begin

Choose implementation method

1. Select message sending feature

Kakao Developers provides two types of message sending features: Kakao Talk Share and Kakao Talk Message. Select the feature to use by referring to Message sending features. If you want to use Kakao Talk Share, check the content after Step 2.

2. Select message type and configuration method

Decide which message template to use by referring to Template types.

Decide how to configure a message by referring to Configuration method comparison. You can configure a message in object format based on predefined default templates or use custom templates configured directly for your service.

3. Check message sharing method

Kakao Talk Share basically provides functionality to share messages through Kakao Talk, but it also supports web sharing functionality, so it can be used regardless of whether Kakao Talk is installed on the device.

If you want to support sharing only through Kakao Talk according to your service needs, you can check whether Kakao Talk execution is possible using ShareClient's isKakaoTalkSharingAvailable(). The meaning of the method call result is as follows.

• true: One of the following
  • Requested from a native app on a mobile device and Kakao Talk is installed
  • Requested from a web browser (webview) on a mobile device
• false
  • Requested from a native app on a mobile device and Kakao Talk is not installed
  • Not a mobile device

To support Kakao Talk Share on devices where Kakao Talk is not installed or in web browser environments, use the web sharing functionality. Refer to the example below.

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

if (isKakaoTalkSharingAvailable) {
  print('Sharing through Kakao Talk available');
} else {
  print('Kakao Talk not installed: Web sharing functionality recommended');
}

Project configuration

To use Kakao Talk Share APIs in native app services, you need to set up Custom URL Scheme. Refer to the device environment-specific project configuration methods below.

• Android: Custom URL scheme
• iOS: Custom URL scheme

Send message with default template

Basic information

Shares messages through Kakao Talk using predefined default templates.

Request

1. Check if Kakao Talk is installed: To check if it is possible to share a message through Kakao Talk, first call isKakaoTalkSharingAvailable() to check if Kakao Talk is installed on the user's device.
   • If Kakao Talk is installed: Call ShareClient's shareDefault() to execute sharing.
   • If Kakao Talk is not installed: Call WebSharerClient's makeDefaultUrl(). When the request is successful, a Uri is returned that executes web sharing functionality. Execute sharing by calling the launchBrowser() method with the returned Uri.
2. Configure message template: For message creation, implement the DefaultTemplate interface, then use one of the classes below according to the desired template type to configure template objects.
   • Feed template: FeedTemplate
   • List template: ListTemplate
   • Location template: LocationTemplate
   • Commerce template: CommerceTemplate
   • Text template: TextTemplate
   • Calendar template: CalendarTemplate
3. Pass template object: When calling shareDefault() or makeDefaultUrl(), pass the previously configured template object as the template parameter.

Sample

// Check if Kakao Talk execution is available
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    await ShareClient.instance.shareDefault(template: defaultFeed);
    print('Kakao Talk Share completed');
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance.makeDefaultUrl(
        template: defaultFeed,
    );
    await launchBrowser(shareUrl);
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
}

Send message with custom template

Basic information

Shares messages through Kakao Talk using custom templates configured in [Tools] > [Message Template].

Request

1. Check if Kakao Talk is installed: To check if it is possible to share a message through Kakao Talk, first call isKakaoTalkSharingAvailable() to check if Kakao Talk is installed on the user's device.
   • If Kakao Talk is installed: Call ShareClient's shareCustom() to execute sharing.
   • If Kakao Talk is not installed: Call WebSharerClient's makeCustomUrl(). When the request is successful, a Uri is returned that executes web sharing functionality. Execute sharing by calling the launchBrowser() method with the returned Uri.
2. Configure message template: Configure the message template in [Tools] > [Message Template]. For template configuration methods, refer to Custom template.
3. Specify template: When calling shareCustom() or makeCustomUrl(), pass the template ID configured in the message template tool as the templateId parameter.
4. Pass user arguments (optional): To include variable information in a message, add user arguments to the custom template, then pass key-value pairs to the templateArgs parameter. For detailed usage and precautions, see Directly inputting user arguments.

Sample

// Custom template ID
int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';
// Check if Kakao Talk execution is available
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    await ShareClient.instance.shareCustom(templateId: templateId);
    print('Kakao Talk Share completed');
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance.makeCustomUrl(
        templateId: templateId,
        templateArgs: {'key1': 'value1'},
    );
    await launchBrowser(shareUrl);
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
}

Send scrape message

Basic information

Shares messages through Kakao Talk by configuring a scrap message with information from a specified web page.

Request

1. Check if Kakao Talk is installed: To check if it is possible to share a message through Kakao Talk, first call isKakaoTalkSharingAvailable() to check if Kakao Talk is installed on the user's device.
   • If Kakao Talk is installed: Call ShareClient's shareScrap() to execute sharing.
   • If Kakao Talk is not installed: Call WebSharerClient's makeScrapUrl(). When the request is successful, a Uri is returned that executes web sharing functionality. Execute sharing by calling the launchBrowser() method with the returned Uri.
2. Specify web page URL for scraping: When calling shareScrap() or makeScrapUrl(), you must pass the URL of the web page to be scraped as the url parameter. The domain of the web page to be scraped must be registered in [App] > [Product Link] > [Web domain] on the app management page.
3. Apply custom template (optional): If you want to send scrape messages based on service-defined message templates, you must pass the ID of the template configured in [Tools] > [Message Template] as the templateId parameter. For template configuration methods, refer to Custom template.
4. Pass user arguments (optional): To include variable information in a message, add user arguments to the custom template, then pass key-value pairs to the templateArgs parameter. For detailed usage and precautions, see Directly inputting user arguments.

Sample: Using default template

// Web page URL to be scraped
String url = "https://developers.kakao.com";
// Check if Kakao Talk execution is available
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    await ShareClient.instance.shareScrap(url: url);
    print('Kakao Talk Share completed');
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance.makeScrapUrl(
        url: url,
        templateArgs: {'key1': 'value1'},
    );
    await launchBrowser(shareUrl);
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
}

Sample: Using custom template

// Custom template ID
int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';
// Web page URL to be scraped
String url = "https://developers.kakao.com";
// Check if Kakao Talk execution is available
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    await ShareClient.instance.shareScrap(
        url: url,
        templateId: templateId,
    );
    print('Kakao Talk Share completed');
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance.makeScrapUrl(
        url: url,
        templateId: templateId,
        templateArgs: {'key1': 'value1'},
    );
    await launchBrowser(shareUrl);
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
}

Set Kakao Talk Share webhook custom parameters

Kakao Talk Share webhook is a function to send a webhook request to the URL specified on Kakao Developers when a Kakao Talk Share message is successfully sent to friends or a chatroom selected by a user.

Kakao Talk Share webhook can only be used when sending Kakao Talk Share messages and is not supported for Kakao Talk Message transmission. Kakao Talk Share is sent by users through Kakao Talk, so services cannot directly confirm whether the message was sent successfully. Therefore, a webhook function is provided to notify when message transmission is successful.

To use this feature, you need to:

1. Set the webhook URL and request method by referring to Kakao Talk Share webhook setting.
2. Build a server to receive a Kakao Talk Share webhook.
3. Pass custom (Custom) parameters when calling the Kakao Talk Share API.
4. Implement a process to handle the notification delivered to the webhook URL of your service server.

The Kakao Talk Share webhook sent to your service server does not include detailed message transmission information. To figure out additional information needed by the service, such as which message's transmission result it is and what content the user shared, you must use custom (Custom) parameters. Also, Kakao Talk Share messages without custom parameters will not deliver Kakao Talk Share webhooks.

Custom parameters must be passed as the serverCallbackArgs parameter when making Kakao Talk Share requests, and you cannot use system reserved words CHAT_TYPE, HASH_CHAT_ID, and TEMPLATE_ID as keys. These keys are included in the notification with the values defined in the specification of Kakao Talk Share webhook.

Below is an example of a Kakao Talk Share request including custom parameters.

try {
  // Pass custom parameters through serverCallbackArgs parameter
  // If this parameter is not used, Kakao Talk Share webhook will not be delivered
  await ShareClient.instance.defaultTemplate(template: defaultFeed, serverCallbackArgs: {'key1': 'value1'});
  print('Kakao Talk Share completed');
  } catch (error) {
  print('Kakao Talk Share failed $error');
}

Upload image

Basic information

Uploads image files to the Kakao server or scrapes image URLs.

To add an image to a Kakao Talk message, you must use a URL issued by the Kakao server after uploading the image. If you are using a custom template, you can also upload images through the Message Template Tool.

To upload an image file to the Kakao server, call uploadImage(). Pass the image you want to upload using one of the following parameters:

• imagePath: Upload by passing the image file path.
• byteData: Upload by passing the image as ByteData.

If you want to scrape an image from the web to the Kakao server, call scrapImage().

If the request succeeds, an ImageUploadResult object is returned. You can check image information such as the image URL (to use in messages) within the ImageInfo inside this object.

Usage limitations

• Image file size: up to 5 MB.
• Image storage period: stored on the Kakao server for up to 100 days, then automatically deleted.

Sample

Upload image

// Local image file
// This example uses an image file added as a project resource.
// Prepare photo files needed for your service, such as from gallery.
final ByteData byteData = await rootBundle.load('assets/images/cat1.png');

// This example saves project resources as image files using path_provider.
final File tempFile = File('${(await getTemporaryDirectory()).path}/cat1.png');
final File file = await tempFile.writeAsBytes(byteData.buffer.asUint8List(byteData.offsetInBytes, byteData.lengthInBytes));

try {
  // Upload to Kakao image server
  final ImageUploadResult imageUploadResult = await ShareClient.instance.uploadImage(imagePath: file.path);
  print('Image upload successful ${imageUploadResult.infos.original}');
} catch (error) {
  print('Image upload failed $error');
}

// This sample uses file_picker to get image files.
var filePickerResult = await FilePicker.platform.pickFiles();

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

  try {
    // Upload to Kakao image server
    ImageUploadResult imageUploadResult =
        await ShareClient.instance.uploadImage(byteData: byteData);
    print('Image upload successful\n${imageUploadResult.infos.original}');
  } catch (error) {
    print('Failed to upload an image. $error');
  }
}

Scrape image

// Original image URL
String url =
    'https://t1.kakaocdn.net/kakaocorp/Service/KakaoTalk/pc/slide/talkpc_theme_01.jpg';

try {
  // Scrape image to Kakao server
  ImageUploadResult imageUploadResult =
    await ShareClient.instance.scrapImage(imageUrl: url);
  print('Image scraping successful'
        '\n${imageUploadResult.infos.original}');
} catch (error) {
  print('Image scraping failed $error');
}

See more

Message Template Tooloutlink ```