# 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` |