@freshworks/react-native-freshdesk-sdk/README.md

React Native wrapper for Freshdesk Android and iOS SDKs

# Freshdesk React Native SDK

"Modern ticketing software that your sales and customer engagement teams will love." React Native
wrapper for the native Freshdesk [iOS](https://github.com/freshworks-oss/freshdesk-ios-sdk) and
[Android](https://github.com/freshworks-oss/freshdesk-android-sdk) SDKs — customer support, live
chat, and knowledge base for your React Native app.

## Features

- Live chat and support home
- Knowledge base / FAQ
- Open a specific topic
- Unread message count (one-shot and real-time)
- User and ticket properties
- JWT user authentication
- User event tracking
- Content configuration / localisation
- Custom link handling
- Push notifications (configured natively in the host app)

## Requirements

- **React Native >= 0.75** (`peerDependencies.react-native` is `>=0.75.0`). On
  RN < 0.75, stay on `~1.4.3` — that is where 1.4.x already sat in practice.
- **New Architecture supported.** The module is backward-compatible: a TurboModule
  when the New Architecture is enabled, the classic bridge module otherwise. No
  JavaScript API or code changes are required either way.
- iOS 15.0+ — the native SDK ships as a vendored `FreshdeskSDK.xcframework`
  (no Swift Package Manager / `use_frameworks!` requirement).
- Android API 26+ (`minSdkVersion 26`, `compileSdkVersion 35`, Android Gradle Plugin 8.6+)
- CocoaPods 1.12+ (iOS)

> Upgrading from 1.4.x? See [`MIGRATION.md`](./MIGRATION.md) — the iOS Podfile /
> Gemfile changes are the main step.

> A handful of methods (`resetUser`, `enableDebugLogs`, `getUnreadCount`) behave
> slightly differently on Android vs iOS because the two native SDKs don't
> expose the same capability — see [`PLATFORM_DIFFERENCES.md`](./PLATFORM_DIFFERENCES.md)
> before relying on their exact runtime behavior.

## Installation

```bash
npm install @freshworks/react-native-freshdesk-sdk
# or
yarn add @freshworks/react-native-freshdesk-sdk
```

The library uses autolinking — no manual linking is required for React Native 0.60+.

### iOS

Set the deployment target in your `Podfile` and install pods — no
`use_frameworks!` is required (the native SDK ships as a vendored xcframework and
the podspec builds it as a static framework):

```ruby
platform :ios, '15.0'
```

```bash
cd ios && pod install
```

Keep `use_frameworks!` only if your *other* dependencies need it — prefer
`:linkage => :static`. Upgrading from 1.4.x? The 1.4.x Podfile / Gemfile needs
the SPM lines removed first — see [`MIGRATION.md`](./MIGRATION.md).

The full guide (deployment-target pinning, embedding the framework in your app bundle, push
notification setup, and troubleshooting) ships with the package — see `docs/integration/installation.md`
(i.e. `node_modules/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md` once
installed), or browse it without installing at
[unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md).

### Android

Ensure `mavenCentral()` is in your repositories and `minSdkVersion` is 26+. The native dependency
(`com.freshworks.sdk:freshdesk`) is included automatically.

```groovy
allprojects {
  repositories {
    google()
    mavenCentral()
  }
}
```

## Documentation

You get your credentials from the Freshdesk portal: **Admin Settings → Mobile Chat SDK → your SDK**
(`token`, `host`, `sdkId`). For JWT-enforced SDKs you also need a per-user `jwt`.

### Initialization

Initialize once, as early as possible in your app lifecycle. All other methods require
initialization first.

**Required:** `token`, `host`, and `sdkId` from the Freshdesk portal. **Optional:** `locale`,
`jwt` (JWT-enforced widgets only), `debugMode` (Android). Push notification setup (Firebase,
APNs, portal push keys) is **not** part of initialization — the SDK works for in-app support
without push; configure push separately when you need tray notifications.

The wrapper sets `hostPlatform` to `reactnative` internally for SDK telemetry headers
(`x-fd-mobile-sdk`); apps do not pass or configure this.

```typescript
import FreshdeskSDK from '@freshworks/react-native-freshdesk-sdk';

await FreshdeskSDK.initialize({
  token: 'your-account-token',
  host: 'your-host.freshdesk.com',
  sdkId: 'your-sdk-id',
  locale: 'en',        // optional, default 'en' (applied at init only)
  jwt: 'your-jwt',     // required only for JWT-enforced SDKs
  debugMode: false,    // optional, Android only
});
```

> Push notifications are optional. For push, the SDK must also be initialized **natively** at app
> startup because the device token arrives before the JS layer runs. See
> [Push notifications](#push-notifications). In-app support works without push wiring.

### Launch the support experience

```typescript
// Support home
await FreshdeskSDK.openSupport();

// Knowledge base / FAQ
await FreshdeskSDK.openKnowledgeBase();

// A specific topic (topicId is optional)
await FreshdeskSDK.openTopic({ topicName: 'Orders', topicId: '12345' });

// Dismiss any open Freshdesk view
await FreshdeskSDK.dismiss();
```

### Unread count

```typescript
// One-shot value
const count = await FreshdeskSDK.getUnreadCount();

// Real-time updates
const sub = FreshdeskSDK.addUnreadCountListener((event) => {
  console.log('Unread count:', event.count);
});

// Clean up when done
sub?.remove();
```

### User and ticket properties

For non-JWT-enforced SDKs, set user properties after initialization. (Properties must be
whitelisted under the linked widget's Contact/Ticket fields.)

```typescript
await FreshdeskSDK.setUserProperties({
  name: 'Jane Doe',
  email: 'jane@example.com',
  phone: '+1234567890',
});

await FreshdeskSDK.setTicketProperties({
  subject: 'Product Enquiry',
  priority: 3,
});

// Read current user
const user = await FreshdeskSDK.getUser();
```

For JWT-enforced SDKs, user properties are updated through the JWT payload — see below.

### JWT authentication

Freshdesk uses JSON Web Tokens to allow only authenticated users to start a conversation.

1. Pass the `jwt` during `initialize()` (mandatory for JWT-enforced SDKs).
2. Listen for user state changes.
3. Update/refresh the token with `authenticateAndUpdate`.

```typescript
const sub = FreshdeskSDK.addUserStateListener((event) => {
  // States: 'authenticated', 'authExpired', 'notAuthenticated',
  //         'identifierUpdated', 'jwtNotPresent', 'undefined'
  console.log('User state:', event.state);
});

// Refresh or update the user with a new JWT (also updates user/ticket properties from payload)
await FreshdeskSDK.authenticateAndUpdate('new-jwt-token');
```

### Reset user

Call on logout (or before switching accounts) to clear the user's session and data.

```typescript
const result = await FreshdeskSDK.resetUser();
// { success: boolean; message?: string; error?: string }
```

### Tracking user events

Track events to use as engagement context, triggered messages, or segmentation.

```typescript
await FreshdeskSDK.trackEvent('add_to_cart', { productId: '12345', quantity: 2 });
```

### Content configuration / localisation

Override static widget text (headers, placeholders, ticket form, privacy policy, response-time
copy). Any field you omit keeps the widget default; pass `{}` to reset to defaults. Changes persist
and take effect immediately.

```typescript
await FreshdeskSDK.setContentConfiguration({
  headers: {
    chat: 'Talk to our team',
    faq: 'Help Centre',
    ticketForm: { title: 'Raise a ticket', submitBtnTitle: 'Submit' },
  },
  placeholders: {
    replyField: 'Type your reply...',
    searchField: 'Search articles...',
  },
  privacyPolicySetting: {
    privacyPolicyMessage: 'We respect your privacy',
    privacyPolicyLinkText: 'Privacy Policy',
    privacyPolicyLink: 'https://example.com/privacy',
  },
});
```

### Custom link handler

Take control of links pressed inside the SDK (e.g. deep links).

```typescript
import { Linking } from 'react-native';

const sub = FreshdeskSDK.setLinkHandler((event) => {
  if (event.url.startsWith('myapp://')) {
    // handle deep link
    return;
  }
  Linking.openURL(event.url);
});

sub?.remove();
```

### Events and cleanup

```typescript
import FreshdeskSDK, { FreshdeskEvents } from '@freshworks/react-native-freshdesk-sdk';

FreshdeskSDK.addUnreadCountListener(/* ... */);
FreshdeskSDK.addUserStateListener(/* ... */);
FreshdeskSDK.addUserCreatedListener(/* ... */); // iOS only

// Remove every listener (e.g. on unmount)
FreshdeskSDK.removeAllListeners();

// Event name constants
FreshdeskEvents.UNREAD_COUNT_CHANGED; // 'unreadCountChanged'
FreshdeskEvents.USER_STATE_CHANGED;   // 'userStateChanged'
FreshdeskEvents.USER_CREATED;         // 'userCreated'
FreshdeskEvents.ON_LINK_PRESSED;      // 'onLinkPressed'
```

### Push notifications

Push is handled **natively** — there is no JavaScript push API. The host app must initialize the
SDK natively at startup and forward the device token / incoming messages:

- **iOS** — APNs `.p8` auth key, Push Notifications + Background Modes capabilities, and native
  init in `AppDelegate`.
- **Android** — Firebase (`google-services.json`), the Google Services plugin, and native init in
  `MainApplication.onCreate()` plus a `FirebaseMessagingService`.

The sample app in the SDK's source repository is the reference wiring (Freshworks GitHub access
required: [sample_app](https://github.com/freshworks/freshdesk_react_native_sdk_dev/tree/main/sample_app)).
Full steps ship with the package — see `docs/integration/installation.md#push-notifications`, or
browse it at
[unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md#push-notifications).

### SDK information

```typescript
const version = await FreshdeskSDK.getSDKVersion();
```

### Diagnostics

Verify or debug your integration:

```typescript
await FreshdeskSDK.enableDebugLogs(true);
const report = await FreshdeskSDK.runDiagnostics();
console.log(report.prettyPrinted);
```

On iOS this runs native structured diagnostics (FreshdeskSDK 1.3+). On Android the wrapper
returns integration checks until native diagnostics parity lands — use `debugMode: true` and
Logcat for deeper signal.

## AI Integration Kit

The npm package ships an **AI Integration Kit** that teaches coding agents (Cursor, Claude,
Copilot, Codex, Kiro) how to integrate and debug the SDK in your React Native app.

After install:

```bash
cp -R node_modules/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/. /path/to/your-app/
```

Then ask your AI tool: "Use the freshdesk-react-native-integration skill and wire up Freshdesk
support."

Canonical skill (for SDK maintainers): `ai-integration-kit/ai/skills/freshdesk-react-native-integration/SKILL.md`.
Regenerate tool copies with `npm run sync:ai-kit`.

The full tool mapping and usage guide ships with the package — see
`ai-integration-kit/README.md` (i.e. `node_modules/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/README.md`
once installed), or browse it without installing at
[unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/README.md](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/README.md).

## Error handling

All methods return promises. Common error codes:

| Code | Meaning |
|------|---------|
| `FRESHDESK_INVALID_CONFIG` | Missing `token` / `host` / `sdkId` |
| `FRESHDESK_NOT_INITIALIZED` | A method was called before `initialize()` |
| `FRESHDESK_INIT_ERROR` | Initialization failed (credentials/network) |
| `FRESHDESK_NO_ACTIVITY` / `FRESHDESK_NO_VIEW_CONTROLLER` | App not foregrounded |
| `FRESHDESK_AUTH_ERROR` | JWT authentication failed |

## Full documentation

These guides ship with the package under `docs/integration/` (i.e.
`node_modules/@freshworks/react-native-freshdesk-sdk/docs/integration/` once installed). You can
also browse them without installing, via unpkg:

- [Installation](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md)
- [Initialization](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/initialization.md)
- [API Reference](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/api_reference.md)
- [Troubleshooting](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/troubleshooting.md)

## License

MIT

## Support

- Email: [support@freshdesk.com](mailto:support@freshdesk.com)
- [Support Portal](https://support.freshdesk.com)
- [Report an issue](https://github.com/freshworks/freshdesk_react_native_sdk_dev/issues) (Freshworks GitHub access required; use the Support Portal above otherwise)