Customerly React Native SDK

Customerly is a customer service platform that helps businesses provide better support to their customers. The React Native SDK allows you to integrate Customerly's features directly into your React Native application, including:

• Live chat support
• Help center articles
• User profiling
• Event tracking
• Lead generation
• Surveys
• Real-time video calls

Installation

Add the SDK to your project:

yarn add react-native-customerly-sdk

Dependencies

This library needs these dependencies to be installed in your project before you can use it:

yarn add react-native-webview react-native-safe-area-context @notifee/react-native react-native-device-info

Using Expo?

npx expo install expo-build-properties react-native-webview react-native-safe-area-context @notifee/react-native react-native-device-info

IMPORTANT

I want to save you a lot of time here: it seems that the @notifee/react-native package is not building correctly with the latest versions of Expo (more info here and here). To ensure it builds correctly, add the following to your app.json:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "extraMavenRepos": ["../../node_modules/@notifee/react-native/android/libs"]
          }
        }
      ]
    ]
  }
}

Before continuing, run the following command to ensure all native code is rebuilt correctly:

npx expo prebuild --clean

This helps avoid build issues, especially after adding or updating native dependencies.

Basic Usage

Wrap your app with CustomerlyProvider (it must be wrapped in a SafeAreaProvider) and use the Customerly API:

import React from "react";
import { CustomerlyProvider, Customerly } from "react-native-customerly-sdk";
import { SafeAreaProvider } from "react-native-safe-area-context";

export default function App() {
  return (
    <SafeAreaProvider>
      <CustomerlyProvider appId="YOUR_APP_ID">
        {/* Your app content */}
      </CustomerlyProvider>
    </SafeAreaProvider>
  );
}

You can then use the Customerly API anywhere in your app:

import { Customerly } from "react-native-customerly-sdk";

Customerly.show();

Customerly.update({
  appId: "YOUR_APP_ID",
  userId: "123",
  email: "[email protected]",
  name: "John Doe",
});

Request Notification Permission

To enable notifications, call:

Customerly.requestNotificationPermissionIfNeeded();

API Reference

Props

| Prop | Type | Required | Description | Default | | ------------------------- | ------------------- | -------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------- | | appId | string | Yes | The Customerly app ID | | | colorScheme | "light" \| "dark" | No | Your app's current color scheme | System color scheme | | notificationChannelId | string | No | The ID of the notification channel to use for notifications (Android only) | customerly-notification-channel | | notificationChannelName | string | No | The name of the notification channel to use for notifications (Android only) | Customerly Notification Channel | | userId | string | No | The user ID | - | | name | string | No | The user name | - | | email | string | No | The user email | - | | accentColor | string | No | The accent color | The messenger accent color configured in your project settings | | contrastColor | string | No | The contrast color | The messenger contrast color configured in your project settings | | attachmentsAvailable | boolean | No | Whether attachments are available | true |

Initialization and Configuration

update

Updates the Customerly SDK settings.

Customerly.update({ appId: "YOUR_APP_ID" });

requestNotificationPermissionIfNeeded

Requests notification permissions if not already granted (uses Notifee).

Customerly.requestNotificationPermissionIfNeeded();

Messenger Control

show

Shows the Customerly chat interface.

Customerly.show(withoutNavigation?: boolean);

hide

Hides the Customerly chat interface.

Customerly.hide();

back

Navigates back in the chat interface.

Customerly.back();

User Management

logout

Logs out the current user.

Customerly.logout();

registerLead

Registers a new lead with the provided email and optional attributes.

Customerly.registerLead("[email protected]", { name: "John Doe" });

Messaging

showNewMessage

Shows the chat interface with a pre-filled message.

Customerly.showNewMessage("Hello, how can I help you?");

sendNewMessage

Sends a new message and shows the chat interface.

Customerly.sendNewMessage("Hello, how can I help you?");

navigateToConversation

Navigates to a specific conversation.

Customerly.navigateToConversation(123);

Help Center

showArticle

Shows an article from the help center.

Customerly.showArticle("collection", "article");

Analytics

event

Tracks a custom event.

Customerly.event("event_name");

attribute

Sets a custom attribute for the current user.

Customerly.attribute("attribute_name", "attribute_value");

Message Counts

getUnreadMessagesCount

Gets the count of unread messages.

await Customerly.getUnreadMessagesCount();

getUnreadConversationsCount

Gets the count of unread conversations.

await Customerly.getUnreadConversationsCount();

Callbacks

The SDK provides various callbacks for different events. Here are the main callback setters:

Customerly.setOnChatClosed(() => {});
Customerly.setOnChatOpened(() => {});
Customerly.setOnHelpCenterArticleOpened((article) => {});
Customerly.setOnLeadGenerated((lead) => {});
Customerly.setOnMessageRead((conversationId, conversationMessageId) => {});
Customerly.setOnMessengerInitialized(() => {});
Customerly.setOnNewConversation((conversationId, attachments) => {});
Customerly.setOnNewMessageReceived((message) => {});
Customerly.setOnNewConversationReceived((conversationId) => {});
Customerly.setOnProfilingQuestionAnswered((question, answer) => {});
Customerly.setOnProfilingQuestionAsked((question) => {});
Customerly.setOnRealtimeVideoAnswered((realtimeCall) => {});
Customerly.setOnRealtimeVideoCanceled(() => {});
Customerly.setOnRealtimeVideoReceived((realtimeCall) => {});
Customerly.setOnRealtimeVideoRejected(() => {});
Customerly.setOnSurveyAnswered(() => {});
Customerly.setOnSurveyPresented((survey) => {});
Customerly.setOnSurveyRejected(() => {});

Each callback has a corresponding remove method:

Customerly.removeOnChatClosed();
Customerly.removeOnChatOpened();
// ... and so on for all callbacks

You can also remove all callbacks at once:

Customerly.removeAllCallbacks();

Example

The repository includes a sample project (example) that demonstrates how to integrate and use the Customerly SDK in a Expo application. The example shows:

• Basic SDK initialization
• Messenger presentation
• User management
• Event tracking
• Message handling
• Notification handling
• Callback usage

To run the example:

1. Run yarn install to install the dependencies
2. Run yarn example:ios to start the iOS simulator
3. Run yarn example:android to start the Android emulator

The sample app provides a complete reference implementation of all SDK features and can be used as a starting point for your integration.

Development

To release a new version of the SDK, you need to:

1. Go to GitHub Actions and run the Release workflow
2. The workflow will build the SDK and release it to npm

License

This SDK is licensed under the GNU GPLv3 License. See the LICENSE file for more details.