# Freshdesk React Native SDK — Troubleshooting

Build and launch fixes for `@freshworks/react-native-freshdesk-sdk` with React Native **0.75.x**.

**Related:** [integration-faq.md](integration-faq.md) · [integration-knowledge-base.md](integration-knowledge-base.md) · [platform-apis.md](platform-apis.md)

---

## Quick setup (npm 2.0.0+)

Shipped in the npm package — apply once after install:

### Android — Kotlin metadata mismatch

**`android/build.gradle`** (after `apply plugin: "com.facebook.react.rootproject"`):

```gradle
apply from: file("../../node_modules/@freshworks/react-native-freshdesk-sdk/android/freshdesk-consumer.gradle")
```

**`android/app/build.gradle`** — ensure JDK 17 and kotlinOptions on the app module:

```gradle
android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
        freeCompilerArgs += ["-Xskip-metadata-version-check"]
    }
}
```

Keep `kotlinVersion = "1.9.24"` in root `build.gradle` (match React Native 0.75). **Do not** bump to Kotlin 2.1 — it breaks the RN Gradle plugin.

> **On React Native 0.79+** (which runs Kotlin 2.1.x by default): use wrapper **2.0.1+**.
> Earlier wrapper builds fail to compile `FreshdeskModule.kt` against RN 0.79's nullable
> `ReadableMap.toHashMap()` — see [Issue 5](#issue-5--android-freshdeskmodulekt-hashmap-type-mismatch-rn-079--kotlin-21).

### iOS — nothing extra needed (2.0.0+)

The native SDK ships as a vendored, statically-linked `FreshdeskSDK.xcframework`
as of **2.0.0** — no Swift Package Manager, `use_frameworks!`, or
`post_install` hook of its own required:

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

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

**Only if the target app is still pinned to `@freshworks/react-native-freshdesk-sdk@~1.4.x`**
(pre-2.0.0) does the old SPM path below (Issue 2, Issue 3) apply — check
`package.json` before reaching for it.

---

## Issue 1 — Android: Kotlin metadata version mismatch

### Symptom

`:app:compileDebugKotlin` fails:

```text
Module was compiled with an incompatible version of Kotlin.
The binary version of its metadata is 2.1.0, expected version is 1.9.0.
```

### Root cause

Freshdesk Android native SDK **2.2.x** uses Kotlin **2.1** metadata. React Native **0.75.x** uses Kotlin **1.9.x**. The host `:app` module compiles against Freshdesk transitively without `-Xskip-metadata-version-check`.

### Fix

Use **`android/freshdesk-consumer.gradle`** from the npm package (see [Quick setup](#quick-setup-npm-200) above).

### Do not

```gradle
kotlinVersion = "2.1.21"  // Breaks React Native Gradle plugin on 0.75.x
```

---

## Issue 2 (legacy, pre-2.0.0 only) — iOS: crash on launch — Library not loaded FreshdeskSDK.framework

**Only applies if `package.json` pins `@freshworks/react-native-freshdesk-sdk@~1.4.x`.**
2.0.0+ doesn't use SPM at all — skip this on a current install.

### Symptom

App builds but crashes on launch:

```text
dyld: Library not loaded: @rpath/FreshdeskSDK.framework/FreshdeskSDK
Reason: tried: '.../YourApp.app/Frameworks/FreshdeskSDK.framework/FreshdeskSDK' (no such file)
```

### Root cause

On the 1.4.x SPM path, `spm_dependency` links `FreshdeskSDK.framework` into `FreshdeskReactNative.framework` but CocoaPods **Embed Pods Frameworks** does not copy the SPM product into the app bundle.

### Fix

Use **`ios/freshdesk_post_install.rb`** from the 1.4.x npm package. On 2.0.0+, upgrade instead — this class of problem doesn't exist once the vendored xcframework is the only path (no SPM product to fail to embed).

---

## Other common issues

| Symptom | Fix |
|---------|-----|
| `FRESHDESK_INVALID_CONFIG` | Non-empty `FRESHDESK_TOKEN`, `FRESHDESK_HOST`, `FRESHDESK_SDK_ID` in `.env`; restart Metro |
| `FRESHDESK_NOT_INITIALIZED` / `FRESHDESK_NOT_READY` | Await `initialize()` before other SDK calls |
| iOS: `openSupport()`/`trackEvent()`/`setUserProperties()` silently fail or no-op right after `initialize()` resolves | See [Issue 4](#issue-4--ios-support-widget-or-trackevent-setuserproperties-silently-fail-right-after-initialize) below |
| `openSupport` spinner forever (Android) | Double init (MainApplication + JS); invalid JWT; bad credentials — run `runDiagnostics()` |
| `config.hostScheme` warn | Bare host — auto-normalized on SDK 1.2.2+; prefer `https://` in `.env` |
| `runtime.doubleInit` warn (Android) | Remove native init from `MainApplication.onCreate()`; JS init for in-app, FCM service for headless push |
| `pod install` — `native-versions.json` missing | Upgrade to SDK **1.2.2+** |
| Metro ECONNREFUSED | Start Metro; `adb reverse tcp:8081 tcp:8081` for USB Android |
| Native module not found | `pod install`, Gradle clean, rebuild native app (not JS reload only) |
| Android: `FreshdeskModule.kt` "Argument type mismatch … `HashMap<String, Any?>` … `Map<String, Any>`" (RN 0.79+ / Kotlin 2.1) | Wrapper bug ≤ 2.0.0 — upgrade to **2.0.1+**. See [Issue 5](#issue-5--android-freshdeskmodulekt-hashmap-type-mismatch-rn-079--kotlin-21) |

See [integration-knowledge-base.md](integration-knowledge-base.md) for full Q&A.

---

## Issue 3 (legacy, pre-2.0.0 only) — Firebase / Google Maps / Expo conflict with global dynamic frameworks

**Only applies on `~1.4.x`.** 2.0.0+ never forces `use_frameworks!` for
Freshdesk in the first place, so this class of conflict cannot occur — the
fix on a current install is simply to upgrade.

### Symptom (1.4.x)

`pod install` succeeds without `use_frameworks!`, but Xcode fails after adding Freshdesk — linker errors, `no such module 'Expo'`, or CocoaPods static/dynamic mixing errors when you enable global dynamic frameworks for Freshdesk.

### Fix (1.4.x)

Use **vendored compatibility mode** instead of dropping Freshdesk or forcing every pod to dynamic:

```ruby
ENV['FRESHDESK_IOS_USE_VENDORED'] = '1'
```

Set at the top of your `Podfile` before `use_native_modules!`, then `pod install`.

---

## Issue 4 — iOS: support widget or `trackEvent`/`setUserProperties` silently fail right after `initialize()`

### Symptom

`initialize()` resolves without error, but the very next call —
`openSupport()`, `trackEvent()`, `setUserProperties()`, or
`setTicketProperties()` — appears to do nothing (no UI opens, no error
thrown, no data reaches the Freshdesk dashboard). Intermittent: works
sometimes, especially on a slower device/network, or on a retry a few
seconds later. The native SDK may log:

```text
⚠️ [Freshdesk Warning] Tasks will be executed once the SDK is loaded, Check
whether the SDK is initialised with proper configuration.
```

### Root cause

The native iOS SDK's `Freshdesk.initialize(with:)` has no completion
callback, `async` variant, or any readiness signal — confirmed by inspecting
the vendored xcframework's own `.swiftinterface`. It does its own async
internal loading after `initialize()` returns; any call made before that
finishes is silently queued/dropped by the native SDK itself. On SDK
versions before the fix below, the wrapper resolved `initialize()`'s promise
the instant the native call *returned*, not when the SDK was actually ready
— so any call issued right after `await initialize()` (completely normal
usage) could race the real load and lose.

### Fix

Upgrade to an SDK version with the `initialize()` settle-delay fix (see
`CHANGELOG.md`'s "iOS `initialize()` settle delay" entry) — `initialize()`
now resolves only once the SDK has had time to actually finish loading, so
normal `await initialize()` usage becomes safe on its own. No app code
change needed.

**On a version without the fix, or as a belt-and-braces measure:** add a
short delay (1–2s) after `initialize()` resolves before making the first
other SDK call, or gate the first `openSupport()`/`trackEvent()`/etc. behind
a "ready" flag set on a short timer rather than immediately on
`initialize()`'s resolution.

---

## Issue 5 — Android: `FreshdeskModule.kt` HashMap type mismatch (RN 0.79+ / Kotlin 2.1)

### Symptom

Build fails inside the wrapper's own native module (not the host `:app`):

```text
e: .../@freshworks/react-native-freshdesk-sdk/android/src/main/java/com/freshworks/freshdesk/reactnative/FreshdeskModule.kt:253:43
   Argument type mismatch: actual type is 'java.util.HashMap<kotlin.String, kotlin.Any?>',
   but 'kotlin.collections.Map<kotlin.String, kotlin.Any>' was expected.
```

Lines 253 / 268 / 283 — `trackEvent()`, `setUserProperties()`, `setTicketProperties()`.
Seen on **React Native 0.79.5 + Kotlin 2.1.20**; any RN ≥ 0.79 with Kotlin 2.1.x is affected.

### Root cause

React Native changed `ReadableMap.toHashMap()` to return `HashMap<String, Any?>` on **RN ≥ 0.79**
(it was `HashMap<String, Any>` on RN 0.75). Wrapper versions **≤ 2.0.0** fed that straight into
the Freshdesk Android SDK's `Map<String, Any>` parameter; Kotlin 2.1 rejects the nullable-value
map as an argument-type mismatch instead of warning. A **wrapper bug**, not an app misconfiguration.

Distinct from [Issue 1](#issue-1--android-kotlin-metadata-version-mismatch): that is about the
native SDK's *binary metadata* version; this is a *source* type error in the wrapper.

### Fix

Upgrade `@freshworks/react-native-freshdesk-sdk` to **2.0.1+** (adds a null-stripping
`toNonNullMap()` helper that returns `Map<String, Any>` on every supported RN/Kotlin combo).

```bash
npm install @freshworks/react-native-freshdesk-sdk@latest
cd android && ./gradlew clean
```

No change to app code, Gradle config, or `kotlinVersion`. Do **not** hand-patch files under
`node_modules/`.

---

## SDK maintainer checklist (before npm publish)

- [ ] `android/freshdesk-consumer.gradle` in tarball
- [ ] `ios/freshdesk_post_install.rb` in tarball (legacy 1.4.x SPM path — still shipped for pinned-old consumers, not used by the 2.0.0+ default setup)
- [ ] `native-versions.json` in tarball
- [ ] `docs/integration/installation.md` documents the current vendored-only iOS setup
- [ ] Sample app builds on RN 0.75 + Kotlin 1.9.24, old **and** new architecture
- [ ] Wrapper Android module compiles against **RN ≥ 0.79 + Kotlin 2.1** (nullable
      `ReadableMap.toHashMap()`) — not covered by `sample_app`; see
      `docs/wiki/toolchain_compatibility.md`
- [ ] `./gradlew :freshworks_react-native-freshdesk-sdk:compileDebugKotlin lintDebug` — 0
      warnings, 0 errors, for `newArchEnabled` true and false
- [ ] Sample app iOS cold launch — no `Library not loaded FreshdeskSDK.framework`
- [ ] `ai-integration-kit/.../troubleshooting.md` synced; SKILL links to this file