expo-cxonemobilesdk

Expo module that wraps the native NICE CXoneChat SDKs and exposes a unified TypeScript API for iOS and Android. The package bundles Swift/Kotlin shims, a config-plugin for Swift Package injection, and an example app built with Expo Router.

Highlights

• Explicit Connection.prepare + Connection.connect flow with listener-first state management (chatUpdated, connectionError, etc.).
• Full multithread surface (Threads.* + Thread.*) including attachments, pre-chat surveys, and typing indicators.
• Customer identity, OAuth, visitor IDs, and custom fields scoped either to the visitor or individual threads.
• Analytics helpers (viewPage, conversion, …) so you can capture chat funnel metrics directly from React Native.

Quick start

1. Install the package and its peer tooling:

   yarn add expo-cxonemobilesdk
   npx pod-install

2. Android AARs are vendored in the package (nice-cxone-mobile-sdk-android/) so no additional Maven repositories or GitHub Packages credentials are required. Gradle picks up the local artifacts automatically when the module is installed.

3. Connect and send a message:

   import { Connection, Threads, Thread, Customer, Analytics } from 'expo-cxonemobilesdk';
   
   await Connection.prepare('NA1', 1234, 'chat_channel');
   await Connection.connect();
   const mode = Connection.getChatMode();
   
   const created = await Threads.create();
   await Thread.send(created.id, { text: 'Hello from Expo' });
   await Analytics.chatWindowOpen();

Refer to docs/setup.md for full installation details, optional Swift Package injection via the config-plugin, and example environment variables.

Documentation

All documentation now lives in docs/. Start with:

• docs/overview.md — architecture, design principles, and DTO strategy.
• docs/connection.md — prepare/connect lifecycle, configuration helpers, and logging.
• docs/threads.md — multithread operations, pagination, and attachments.
• docs/customers.md — identity, OAuth, visitor IDs, and custom fields.
• docs/analytics.md — analytics helpers and usage patterns.
• docs/events.md — every native event payload and guidelines for listener-first UIs.
• docs/config-plugin.md — how to wire the Swift Package config plugin into your app config.

Each file spells out the JS helper, native counterpart, and relevant example-app wiring.

Example app

The example/ directory is a runnable Expo Router app that exercises all APIs:

cd example
cp .env.example .env   # fill in your CXone env/brand/channel
yarn
npx expo prebuild -p ios
cd ios && pod install --repo-update
cd ..
yarn ios

Shared UI and hooks live in example/app/components/* so Router screens stay lightweight. Message rendering is event-driven—no optimistic/pending states in JS.

The example expects these environment variables inside example/.env (copied from .env.example):

EXPO_PUBLIC_CHAT_ENV=YOUR_ENV_CODE   # e.g. EU1
EXPO_PUBLIC_CHAT_BRAND_ID=YOUR_BRAND_ID
EXPO_PUBLIC_CHAT_CHANNEL_ID=YOUR_CHANNEL_ID   # e.g. chat_xxx

Platform dissimilarities

• Channel configuration — both platforms return the same JSON shape, but fileRestrictions.allowedFileSize may be a number or { minKb, maxKb } depending on what the SDK reports.
• Customer identity getters — iOS reads the identity from the SDK provider. Android returns the last value set by JS because the SDK lacks a getter.
• Thread pagination — Android’s Thread.loadMore resolves with an updated thread snapshot. iOS triggers pagination internally; call Thread.getDetails (or rely on threadUpdated) for the refreshed messages.
• Custom field lifetime — CXone clears customer and thread custom fields on Connection.signOut(). Persist values externally and reapply them after reconnecting.

Document new differences here (and update the relevant doc file + TypeScript types) whenever the native SDKs diverge.

Contributing

Contributions are welcome! Please follow the Expo contributing guide and keep the docs/ folder updated when you add native/TS APIs.

Formatting

• yarn format / yarn format:check — Prettier for JS/TS.
• brew install swift-format then yarn format:swift / yarn format:swift:check — Apple swift-format for Swift.

Troubleshooting

• After editing Swift files, rerun pod install inside example/ios so Xcode sees the new sources.
• Build errors referencing CXoneChatSDK usually mean the Swift Package reference did not resolve. Re-run the config-plugin via npx expo prebuild -p ios, then cd ios && pod install --repo-update.
• Android manifest merge failures mentioning android:fullBackupContent come from the CXone chat-sdk-core AAR also defining that attribute. Add tools:replace="android:fullBackupContent" to your app’s <application> element (with the tools namespace declared) to keep your existing backup rules.