How to integrate React Native SDK for chat? : Freshsales

Pre Requisites

RN v0.60 and above will be supported from Chat SDK v2.0.0.

Get your APP ID and APP Key

Your Chat account is associated with a unique APP ID and APP key which is used to integrate your mobile SDK with Chat.

Go to Admin Settings > Channels > Chat & Messaging > Mobile SDK. You can find your APP ID and APP Key here.

1. Add Chat SDK to your project

Chat node package name is ‘react-native-freshchat-sdk’.
In your react native project’s Package.json file, under dependencies add ”react-native-freshchat-sdk”: “{{latest-version}}”

For the latest SDK version please refer the following link: https://www.npmjs.com/package/react-native-freshchat-sdk

1.1. iOS Setup

RN Version	Chat Version	Steps
0.60+	2.0.0+	Run the below command to autolink the SDK cd ios pod install
< 0.60	2.0.0+	1. Make sure Podfile exists inside your ios project directory. If not, initialize pod inside your ios project directory and add the React dependency in your podfile. React dependencies are available below this table. 2. Then link the React native Chat SDK using the following command, react-native link react-native-freshchat-sdk
< 0.60	< 2.0.0	1. Link the React native Chat SDK using the following command, react-native link react-native-freshchat-sdk 2. Go to ios folder of your react native project. 3. Add an entry for FreshchatSDK as shown below in Podfile, target 'ProjectName' do pod 'FreshchatSDK', :path=> '../node_modules/react-native-freshchat-sdk/ios/FreshchatSDK.podspec' end 4. Run pod install from iOS directory
0.60+	< 2.0.0	Only Chat SDK 2.0.0+ will be compatible with RN v0.60+.

React dependencies when RN < 0.60 & Chat SDK 2.0.0+

# React Native requirements

pod 'React', :path => '../node_modules/react-native', :subspecs => [

'Core',

'CxxBridge', # Include this for RN >= 0.47

'DevSupport', # Include this to enable In-App Devmenu if RN >= 0.43

'RCTText',

'RCTNetwork',

'RCTWebSocket', # Needed for debugging

'RCTAnimation', # Needed for FlatList and animations running on native UI thread

# Add any other subspecs you want to use in your project

]

# Explicitly include Yoga if you are using RN >= 0.42.0

pod 'yoga', :path => '../node_modules/react-native/ReactCommon/yoga'

pod 'DoubleConversion', :podspec => '../node_modules/react-native/third-party-podspecs/DoubleConversion.podspec'

pod 'glog', :podspec => '../node_modules/react-native/third-party-podspecs/glog.podspec'

pod 'Folly', :podspec => '../node_modules/react-native/third-party-podspecs/Folly.podspec'

Migrating an existing Chat integration to Chat SDK 2.0.0+

Unlink React native Chat SDK from your react project using the following command.

react-native unlink react-native-freshchat-sdk

Remove the following line from Podfile inside your iOS project. pod 'FreshchatSDK', :path=> '../node_modules/react-native-freshchat-sdk/ios/FreshchatSDK.podspec'

Refer above tabular column and choose steps as per your requirement.

1.2. Android Setup

Add maven { url "https://jitpack.io" } to your project level build.gradle file.

allprojects {

repositories {

.....

maven { url "https://jitpack.io" }

}

}If you are using RN version < 0.60, please run below command. react-native link react-native-freshchat-sdk

2. Initialization of SDK

Invoke Freshchat.init() with your app id and app key before invoking/ attempting to use any other features of Chat SDK. We highly recommend invoking init() from your app's launcher / support screen launch. Chat SDK checks for presence of its components during init() and will warn about missing components when it detects the components are missing or their manifest entries are missing. Replace the YOUR-APP-ID and YOUR-APP-KEY in the following code snippet with the actual app ID and app key.import { Freshchat, FreshchatConfig } from 'react-native-freshchat-sdk';var freshchatConfig = new FreshchatConfig(APP_ID, APP_KEY);Freshchat.init(freshchatConfig);

Note: If your Freshchat account is not part of Freshchat US servers, you must specify domain based on your server location. Please contact our support team to know your account's server location.

Following are the server location to domain mapping details
US2 - "https://msdk.us2.freshchat.com"
EU - "https://msdk.eu.freshchat.com"
AU - "https://msdk.au.freshchat.com"
IN - "https://msdk.in.freshchat.com"

Sample Code:
freshchatConfig.setDomain("msdk.in.freshchat.com");

2.1 Initialization Config Options

Enable or disable features like camera capture by specifying it in the config before initialization.

var freshchatConfig = new FreshchatConfig(APP_ID, APP_KEY);

freshchatConfig.teamMemberInfoVisible = true;

freshchatConfig.cameraCaptureEnabled = true;

freshchatConfig.gallerySelectionEnabled = true;

freshchatConfig.responseExpectationEnabled = true;

freshchatConfig.showNotificationBanner = true; //iOS only

freshchatConfig.notificationSoundEnabled = true; //iOS only

freshchatConfig.themeName = "CustomTheme.plist"; //iOS only

freshchatConfig.stringsBundle = "FCCustomLocalizable"; //iOS only

Freshchat.init(freshchatConfig);

3. User Information

3.1 Updating User Information

You can send basic user information at any point to give you more context on the user when your support agents are messaging back and forth with them.

import { FreshchatUser } from 'react-native-freshchat-sdk';

var freshchatUser = new FreshchatUser();

freshchatUser.firstName = "John";

freshchatUser.lastName = "Doe";

freshchatUser.email = "[email protected]";

freshchatUser.phoneCountryCode = "+91";

freshchatUser.phone = "1234234123";

Freshchat.setUser(freshchatUser, (error) => {

console.log(error);

});

3.2 Updating User Properties (Meta Data)

You can capture and send additional metadata about the user and the events in the app, all of which also becomes a way to segment your users to later push messages to them.

/var userPropertiesJson = {

"user_type": "Paid",

"plan": "Gold"

}

Freshchat.setUserProperties(userPropertiesJson, (error) => {

console.log(error);

});

3.3 Reset User Data

Reset user data at logout or when deemed appropriate based on user action in the app by invoking the resetUser API.

Freshchat.resetUser();

3.4 Restore user

For retaining the chat messages across devices/sessions/platforms, the mobile app needs to pass the same external id and restore id combination for the user. This will allow users to seamlessly pick up the conversation from any of the supported platforms - Android, iOS and Web.

External Id - This should (ideally) be a unique identifier for the user from your system like a user id or email id etc and is set using the Freshchat.identifyUser() API. This cannot be changed once set for the user
Restore Id - This is generated by Chat for the current user, given an external id was set and can be retrieved anytime using the Freshchat.getUser().getRestoreId() API. The app is responsible for storing and later present the combination of external id and restore id to the Chat SDK to continue the chat conversations across sessions on same device or across devices and platforms.

Note: 1. Restore Id for a user is typically generated only when user has sent a message.
          2. Notifications are supported in only one mobile device at any point in time and is currently the last           restored device or device with last updated push token

To set external id

Freshchat.identifyUser("EXTERNAL_ID", null, (error) => {

console.log(error);

});

To retrieve the restore id

Freshchat.getUser((user) => {

var restoreId = user.restoreId;

console.log("restoreId: " + restoreId);

})

To lookup and restore user by external id and restore id

Freshchat.identifyUser("EXTERNAL_ID", "RESTORE_ID", (error) => {

console.log(error);

});

To listen to restore id generated event

Restore Id generation is an asynchronous process. You need to listen to this event throughout your application lifecycle. Usually generation happens after user initiates a conversation.

Register for restore id generated event

Freshchat.addEventListener(

Freshchat.EVENT_USER_RESTORE_ID_GENERATED,

() => {

console.log("onRestoreIdUpdated triggered");

Freshchat.getUser((user) => {

var restoreId = user.restoreId;

var externalId = user.externalId;

console.log("externalId: " + externalId);

console.log("restoreId: " + restoreId);

})

}

);

3.5 Get Chat User ID

You can get your user's unique identifier using getFreshchatUserId() API.

Freshchat.getFreshchatUserId((data) => {

console.log(data);

});

4. Launching the Support Solution

Use the snippets below to launch into the FAQ or Conversation based support experience from a call to action in your app. Your call to action or entry point could be an on-screen button or a menu item.

4.1 Conversations

In response to a specific UI events like a menu selection or button on click event, invoke the showConversations() API to launch the Conversation Flow. If the app has multiple channels configured, the user will see the channel list. Channel list is ordered as specified in the Dashboard (link to channel list in dashboard) when there are no messages. When messages are present, the order is based on most recently used first

Note: Only Message Channels with visibility set to "Visible to all users" will be displayed when using showConversations() API

Launching Conversation List from click of a button in your app's screen

Freshchat.showConversations();

4.1.1 Filtering Conversation Channels

To filter and display only Message Channels tagged with a specific term, use the filterByTags API in ConversationOptions instance passed to showConversations() API as below.

Eg: To link and display only specific Message Channels from say orders page in your app, those specific Message Channels can be tagged with the term "order_queries".

import { ConversationOptions } from 'react-native-freshchat-sdk';

var conversationOptions = new ConversationOptions();

conversationOptions.tags = ["premium"];

conversationOptions.filteredViewTitle = "Premium Support";

Freshchat.showConversations(conversationOptions);

4.1.2 Unread Count

Note: 1. If no matching channel is found, the user will be redirected to the default channel.
           2. Message Channels which are normally not visible when using showConversations() API, will also            be displayed when tagged and the specific tag is passed to filterByTags API of                                            ConversationOptions instance passed to showConversations() API.

4.1.2 Unread Count

If you would like to obtain the number of unread messages for the user at app launch or any other specific event, use the getUnreadCountAsync API and display the count.

Freshchat.getUnreadCountAsync((data) => {

console.log(data);

});

The app can also choose to listen to changes to unread count when the app is open.

Listen for unread message count event

Freshchat.addEventListener(

Freshchat.EVENT_UNREAD_MESSAGE_COUNT_CHANGED,

() => {

console.log("onUnreadMessageCountChanged triggered");

Freshchat.getUnreadCountAsync((data) => {

var count = data.count;

var status = data.status;

if (status) {

console.log("Message count: " + count);

} else {

console.log("getUnreadCountAsync unsuccessful");

}

});

}

);

4.2. FAQ

In response to specific UI events like a menu selection or button on click event, invoke the showFAQs() API to launch the FAQ screen.By default the FAQ Categories is displayed as a grid with a “Contact Us” button at the bottom. For customising this, check the FAQ Options.

Freshchat.showFAQs();

4.2.1 FAQs Options

Customizations to the FAQ Flow can be achieved by specifying the relevant options in the FaqOptions instance passed to the showFAQs() API.

import { FaqOptions } from 'react-native-freshchat-sdk';

var faqOptions = new FaqOptions();

faqOptions.tags = ["premium"];

faqOptions.filteredViewTitle = "Tags";

faqOptions.filterType = FaqOptions.FilterType.ARTICLE;

Freshchat.showFAQs(faqOptions);

filteredViewTitle - title given to the result list page of the filter applied.

tags - name of the tags based on which filter gets applied.

filterType - Category/Article. Category - combination of articles and sub categories. Article - contains only articles.

Note: When there is no match on the filter applied, it will display all the FAQ categories by default.

4.2.2 Filtering FAQ categories by tags

To filter and display only FAQ Categories tagged with a specific term, use the filterByTags API with Filter Type as Category in FAQOptions instance passed to showFAQs() API as below.

Eg: To display FAQ Categories related to specific user type, those specific FAQ Categories can be tagged with the term "premium".

import { FaqOptions } from 'react-native-freshchat-sdk';

var faqOptions = new FaqOptions();

faqOptions.tags = ["premium"];

faqOptions.filteredViewTitle = "Tags";

faqOptions.filterType = FaqOptions.FilterType.CATEGORY;

Freshchat.showFAQs(faqOptions);

4.2.3 Filtering FAQ articles by tags

To filter and display only FAQs tagged with a specific term, use the filterByTags API with Filter Type as Article in FAQOptions instance passed to showFAQs() API as below.

Note: FAQs also inherit the tags from the parent FAQ category.

Eg: To link to FAQs related to payment failure, those specific FAQs can be tagged with the term "payment_failure" and can be linked to from Payments page in the app.

import { FaqOptions } from 'react-native-freshchat-sdk';

var faqOptions = new FaqOptions();

faqOptions.tags = ["premium"];

faqOptions.filteredViewTitle = "Tags";

faqOptions.filterType = FaqOptions.FilterType.ARTICLE;

Freshchat.showFAQs(faqOptions);

4.2.4 Filter Message Channels displayed on clicking "Contact Us" in FAQs by tags

To filter and display only Message Channels tagged with a specific term when user clicks "Contact Us"in FAQ screens, use the filterContactUsByTags API in FAQOptions instance passed to showFAQs() API as below.

Note: The default behaviour for "Contact Us" from within FAQ flow is same as invoking showConversations() i.e it will display all channels that are marked "Visible to all users", except when filtering of channels is enabled by passing tags to filterContactUsByTags API.

Eg: To display Message Channels related to specific section of FAQ show, those specific Message Channels can be tagged with the term "payment_failure".

import { FaqOptions } from 'react-native-freshchat-sdk';

var faqOptions = new FaqOptions();

faqOptions.tags = ["payment_failure"];

faqOptions.filteredViewTitle = "Payments";

faqOptions.filterType = FaqOptions.FilterType.ARTICLE;

faqOptions.showFaqCategoriesAsGrid = true;

faqOptions.showContactUsOnFaqScreens = true;

faqOptions.showContactUsOnFaqNotHelpful = true;

faqOptions.contactusFilterTags = ["payments"];

Freshchat.showFAQs(faqOptions);

5. Send message API

The app can send a message on behalf of the user using the sendMessage() API.

Note: This API would silently send a message and not launch the Chat SDK UI

Eg: To send a message on a channel tagged "premium", the API can be invoked as below.

import { FreshchatMessage } from 'react-native-freshchat-sdk';

var freshchatMessage = new FreshchatMessage();

freshchatMessage.tag = "premium";

freshchatMessage.message = "text message";

Freshchat.sendMessage(freshchatMessage);

6. Push Notifications

Integrating Chat push notification in your application will help users receive your support messages quicker.

6.1.1 Server side integration

Android

In Firebase Console Under your project go to cloud messaging tab and you will see your Server Key, copy that. If you do not have a Firebase account for your application. Refer https://firebase.google.com/docs/android/setup

Save this FCM server key in Chat web portal under Settings -> Mobile SDK

iOS

Refer here for generating .p12 file and uploading it to Chat.

6.1.2 Client side integration

Please follow the below steps to integration push notifications in you mobile app. Below steps are under the assumption that your app is handing other push notifications.

Steps

1. Saving push token: Each application will have a push token. Chat needs this token to send push notification to user. You can use below snippet to send token to Chat SDK.

Freshchat.setPushRegistrationToken(token);

2. Passing received push notification payload to Chat SDK.

Freshchat.isFreshchatNotification(notification, (freshchatNotification) => {

if (freshchatNotification) {

Freshchat.handlePushNotification(notification);

} else {

// handle your app notification

}

})

6.2 Customising Notifications (Android only)

Add the below code in index.js

var freshchatNotificationConfig = new FreshchatNotificationConfig();

freshchatNotificationConfig.priority = FreshchatNotificationConfig.NotificationPriority.PRIORITY_HIGH;

freshchatNotificationConfig.notificationSoundEnabled = true;

freshchatNotificationConfig.largeIcon = "notif"; // Drawable name

freshchatNotificationConfig.smallIcon = "notif"; // Drawable name

Freshchat.setNotificationConfig(freshchatNotificationConfig);

6.3 Push Notification Checklist

We have identified some potential areas where problem happens. So we consolidated those into checklists, check if you have done everything.

iOS

1. Make sure you have uploaded correct push certificate in Freschat portal.

2. Make sure that you are checking in development or production environment and upload the respective certificate in Freschat portal.

3.Don’t check in iOS simulator, since it did not have push notification capability. Check in real device.

4.Push notification capability should be enabled in your Xcode project.

5.Make sure you gave permission to push notification for your application. If not go to settings -> under your application, enable push notification.

6.Confirm you are passing on device token to the Chat using the following method,

Freshchat.setPushRegistrationToken(device.pushToken);

7. Under Appdelegate class make sure you have either UNUserNotificationCenter delegate methods or [UIApplicationDelegate application:didReceiveRemoteNotification:fetchCompletionHandler:] is implemented. And if UNUserNotificationCenter framework is being used, make sure delegate has been set for that.

8. Add respective react bridging codes on the push notification delegate methods.

9. Refer the codes here for plugin implementation, confirm you have implemented all the recommendations.

10. If you have Notification extension in your app, make sure its not blocking the notification.

Android

1. Make sure you have added correct FCM key of your application in Chat portal

2. Don’t check in emulator, which don’t have google play service enabled. Check in real device.

3. Confirm you are passing on device token to the Chat using the following method,

Freshchat.setPushRegistrationToken(device.pushToken);

4. Make sure you are receiving notification from FCM.

5. Refer the codes here for plugin implementation, confirm you have implemented all the recommendations

If the problem persists, try the following URL,

https://web.freshchat.com/app/api/notif_debug?convId=CONV_ID where,

CONV_ID is the conversation id of the conversation for which you did not receive notification. CONV_ID is the last numeric part of the url when you open the conversation in the browser.

Ensure that you are logged in as Admin while opening this url. It will give you the reason behind the push notification failure.

7. Other Notes

For Localisation, UI customisation, RTL support and more refer our platform specific documentation for Android and iOS.