@freshworks/react-native-freshdesk-sdk
Version:
React Native wrapper for Freshdesk Android and iOS SDKs
303 lines (217 loc) • 11.9 kB
Markdown
# Freshdesk React Native SDK — Integration FAQ
Everything you may need before, during, and after integrating `@freshworks/react-native-freshdesk-sdk`. Share this file with your team after AI-assisted integration.
**Also see:** [integration-knowledge-base.md](integration-knowledge-base.md) (detailed Q&A) · [platform-apis.md](platform-apis.md) (Android vs iOS, including the iOS `initialize()` settle delay) · `PLATFORM_DIFFERENCES.md` (ships in the npm package root)
---
## Before you integrate
### What do I need from the Freshdesk portal?
Go to **Admin Settings → Mobile Chat SDK → your SDK**:
| Item | Used for |
|------|----------|
| **Account token** | `FRESHDESK_TOKEN` |
| **Host URL** | `FRESHDESK_HOST` — `yourcompany.freshdesk.com` or `https://yourcompany.freshdesk.com` (both work) |
| **SDK ID** | `FRESHDESK_SDK_ID` |
| **JWT encryption key** | Only if JWT is enforced — server-side signing |
| **FCM / APNs upload** | Only if push notifications are enabled |
### What are the app requirements?
| Requirement | Minimum |
|-------------|---------|
| React Native | **0.75.0+** |
| iOS deployment target | **15.0+** |
| Android minSdk | **26** |
| Android compileSdk | Inherited from your app's own `ext.compileSdkVersion`; wrapper falls back to **35** if unset |
| Android Gradle Plugin | **8.6+** (or **8.9.1+** if your app pins `compileSdkVersion` to 36) |
| CocoaPods (iOS) | **1.12+** |
| JDK (Android builds) | **17–21** (JDK 26 breaks Gradle 8.x) |
### Do I need push notifications to use chat/support?
**No.** In-app support, chat, and knowledge base work with JavaScript `FreshdeskSDK.initialize()` only. Push is optional and requires extra native wiring (Firebase on Android, APNs on iOS).
### Do I need the AI Integration Kit?
Optional but recommended. After `npm install`, copy the kit into your app root:
```bash
cp -R node_modules/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/. .
```
Then ask your AI tool to use the `freshdesk-react-native-integration` skill. The kit includes this FAQ, a knowledge base, and platform reference docs.
### Where should credentials be stored?
| File | Purpose | Commit to git? |
|------|---------|----------------|
| `.env` | JS layer (`FRESHDESK_*` keys) | **No** — add to `.gitignore` |
| `android/app/build.gradle` | Android `BuildConfig` for push | Yes (no secret values hardcoded — read from `.env`) |
| `ios/<App>/Info.plist` | iOS native keys for push | Yes (same — sync from `.env`) |
| `google-services.json` | Firebase (Android push) | **No** if it contains project secrets |
| APNs `.p8` key | Apple push | **Never** — upload to Freshdesk portal only |
**Never paste tokens or JWTs in chat** when using an AI agent — edit the files above directly.
---
## What changes in my app after integration
After a typical integration, expect changes in these areas. Your AI agent should list the exact files in the **Integration Summary** at the end of the session.
### 1. Dependencies
| Change | Typical file |
|--------|--------------|
| SDK npm package added | `package.json`, `package-lock.json` / `yarn.lock` |
```bash
npm install @freshworks/react-native-freshdesk-sdk
```
### 2. Environment & credentials
| Change | Typical file |
|--------|--------------|
| Freshdesk env vars | `.env` (new or updated) |
| TypeScript env declarations | `src/types/env.d.ts` |
| Babel dotenv plugin | `babel.config.js` |
### 3. JavaScript / React Native
| Change | Typical file |
|--------|--------------|
| SDK init provider or root `useEffect` | `App.tsx`, `FreshdeskProvider.tsx`, or similar |
| Support / Help button | Settings screen, tab bar, profile, etc. |
| Event listeners (unread count, user state) | Provider or screen component |
| JWT auth hooks (if enforced) | Auth context / login flow |
| Content configuration (optional) | After init in provider |
### 4. Android native
| Change | Typical file | When |
|--------|--------------|------|
| `mavenCentral()`, minSdk 26 | `android/build.gradle` | Always |
| `freshdesk-consumer.gradle` apply | `android/build.gradle` | Always (RN 0.75 + Kotlin 1.9) |
| App module `kotlinOptions` skip flag | `android/app/build.gradle` | Always (RN 0.75) |
| BuildConfig Freshdesk fields | `android/app/build.gradle` | Push or native credentials |
| Firebase messaging service | `FreshdeskMessagingService.kt` | Push only |
| FCM service in manifest | `AndroidManifest.xml` | Push only |
| `google-services.json` | `android/app/` | Push only |
| Google Services plugin | `android/build.gradle`, `android/app/build.gradle` | Push only |
| **Do not** add init to `MainApplication.onCreate()` | — | Conflicts with JS init |
### 5. iOS native
| Change | Typical file | When |
|--------|--------------|------|
| `platform :ios, '15.0'` | `Podfile` | Always |
| Freshdesk keys in plist | `ios/<App>/Info.plist` | Push |
| Native init + push forwarding | `AppDelegate.mm` / `.swift` | Push |
| Push + Background Modes | Xcode Signing & Capabilities | Push |
On `@freshworks/react-native-freshdesk-sdk@2.0.0+` nothing else is needed for
iOS — the native SDK is a vendored static xcframework, no
`use_frameworks!`/SPM/`post_install` hook. Only apps still pinned to `~1.4.x`
need those (see [troubleshooting.md](troubleshooting.md)); upgrading is
simpler than adding them.
### 6. AI Integration Kit (optional)
| Change | Location |
|--------|----------|
| Skill + FAQ + knowledge base copied | `.cursor/skills/`, `CLAUDE.md`, `ai/skills/`, etc. |
---
## After integration — checklist
Run through this list before considering integration complete:
- [ ] `.env` filled with portal credentials (token, host, sdkId)
- [ ] `.env` is in `.gitignore`
- [ ] Metro restarted after `.env` changes
- [ ] iOS: `cd ios && pod install` completed
- [ ] App builds on target platforms (Android + iOS)
- [ ] `FreshdeskSDK.initialize()` runs once at app start
- [ ] Support entry point opens the widget (`openSupport()` or KB)
- [ ] Diagnostics run clean:
```typescript
await FreshdeskSDK.enableDebugLogs(true);
const report = await FreshdeskSDK.runDiagnostics();
console.log(report.prettyPrinted);
```
- [ ] `runtime.sdkInitialized: pass`
- [ ] Push tested on real device (if enabled)
- [ ] JWT flow tested login → open support → logout (if enforced)
---
## Frequently asked questions
### How do I open support vs knowledge base?
```typescript
await FreshdeskSDK.openSupport(); // Support home / chat entry
await FreshdeskSDK.openKnowledgeBase(); // FAQ / articles directly
await FreshdeskSDK.openTopic({ topicName: 'Billing' });
```
### Can I use host without `https://`?
**Yes** (SDK 1.2.2+). Both `yourcompany.freshdesk.com` and `https://yourcompany.freshdesk.com` work. The SDK auto-prefixes `https://`.
### Why does the widget show a spinner on Android?
Common causes:
1. **Double initialization** — native init in `MainApplication.onCreate()` **and** JS init. Fix: JS init only for in-app; native init only in FCM service for headless push.
2. **Missing or invalid JWT** when widget enforces JWT.
3. **Invalid credentials** — run diagnostics.
### Why does `openSupport()`/`trackEvent()`/`setUserProperties()` silently do nothing on iOS right after `initialize()`?
The native iOS SDK has no readiness signal of its own — it keeps loading
asynchronously after `initialize()` returns, and a call issued too early is
silently dropped by the native SDK. The wrapper's `initialize()` now waits
out a fixed settle delay (~2s) before resolving specifically so `await
initialize()` is safe to follow immediately with other calls — if you're
still seeing this, confirm the SDK version includes that fix (`CHANGELOG.md`)
and see [platform-apis.md](platform-apis.md) for the full explanation.
### Why does `pod install` fail with `native-versions.json`?
Upgrade to `@freshworks/react-native-freshdesk-sdk@1.2.2` or later. Older npm packages omitted this file required by the podspec.
### Do I initialize in MainApplication on Android?
**No** (for React Native bridge apps). Use:
- **JS** `FreshdeskSDK.initialize()` for in-app support
- **Native** init inside `FirebaseMessagingService` only for headless/killed push delivery
### How do I set the widget language?
Pass `locale` at init: `locale: 'en'`, `locale: 'fr'`, etc. Set `FRESHDESK_LOCALE` in `.env`.
### How do I customize widget text?
```typescript
await FreshdeskSDK.setContentConfiguration({
headers: { chat: 'Talk to us', faq: 'Help Centre' },
placeholders: { replyField: 'Type here...' },
});
```
### How does JWT work?
1. Generate JWT server-side per logged-in user.
2. Pass `jwt` in `initialize({ ..., jwt })`.
3. Listen for `authExpired` → call `authenticateAndUpdate(newJwt)`.
4. Call `resetUser()` on logout.
5. Do **not** use `setUserProperties` for identity when JWT is enforced.
### How do I show unread message badge?
```typescript
FreshdeskSDK.addUnreadCountListener(({ count }) => {
// update tab badge / UI
});
```
### How do I debug integration issues?
1. Enable logs: `await FreshdeskSDK.enableDebugLogs(true)`
2. Run diagnostics: `const report = await FreshdeskSDK.runDiagnostics()`
3. Apply each non-pass check's `fixHint` verbatim
4. Android: also use `debugMode: true` in init + Logcat
### What must I configure in the Freshdesk portal for push?
| Platform | Portal setup |
|----------|--------------|
| Android | Upload FCM service account / credentials |
| iOS | Upload APNs `.p8` (Key ID, Team ID, bundle ID) |
### Can I commit `.env` or `google-services.json`?
**No** for production secrets. Add to `.gitignore`. Use CI secrets or local-only files for credentials.
### Where is the sample app?
In the SDK GitHub repo: `sample_app/` — reference for init, push, JWT, diagnostics, and native wiring.
### Where is the full API reference?
- In repo: `docs/integration/api_reference.md`
- Online: https://github.com/freshworks/freshdesk_react_native_sdk/blob/main/docs/integration/api_reference.md
---
## Integration Summary template (for AI agents)
After completing integration, the agent **must** output a summary like this so you know exactly what changed:
```markdown
## Freshdesk integration complete
### Credentials (you fill manually)
- `.env` — FRESHDESK_HOST, FRESHDESK_LOCALE set; TOKEN / SDK_ID / JWT placeholders for you to fill from portal
### Files changed
| Area | File | Change |
|------|------|--------|
| npm | package.json | Added @freshworks/react-native-freshdesk-sdk |
| JS | src/providers/FreshdeskProvider.tsx | Created — init + listeners |
| JS | App.tsx | Wrapped with FreshdeskProvider |
| JS | src/screens/SettingsScreen.tsx | Added Help button → openSupport() |
| Android | android/app/build.gradle | BuildConfig Freshdesk fields |
| iOS | ios/Podfile | platform 15.0 |
| ... | ... | ... |
### Wired APIs
- initialize, openSupport, addUnreadCountListener
- (push / JWT / content config — if applicable)
### Your manual steps
1. Fill token and sdkId in `.env`
2. cd ios && pod install
3. Rebuild app, open Help, run diagnostics
### FAQ & docs
- [Integration FAQ](ai/skills/freshdesk-react-native-integration/integration-faq.md)
- [Knowledge base](ai/skills/freshdesk-react-native-integration/integration-knowledge-base.md)
- [Platform APIs](ai/skills/freshdesk-react-native-integration/platform-apis.md)
```
---
## Quick links (in your app repo after copying the kit)
| Document | Path |
|----------|------|
| **This FAQ** | `ai/skills/freshdesk-react-native-integration/integration-faq.md` |
| Knowledge base (Q&A) | `ai/skills/freshdesk-react-native-integration/integration-knowledge-base.md` |
| Platform differences | `ai/skills/freshdesk-react-native-integration/platform-apis.md` |
| Integration skill | `ai/skills/freshdesk-react-native-integration/SKILL.md` |
| Worked examples | `ai/skills/freshdesk-react-native-integration/examples.md` |