Merge branch 'main' into update-intercom-sdks-20251004-090258

Author: jasonpraful

README.md

@@ -45,7 +45,7 @@
 ## Installation
 
 ```sh
-$ npm install @intercom/intercom-react-native
+npm install @intercom/intercom-react-native
 ```
 
 or
@@ -61,7 +61,7 @@ If you're using React Native v0.60 or above, the library will be linked automati
 #### Android: Automatic linking with React Native v0.59 and below
 
 ```
-$ react-native link @intercom/intercom-react-native
+react-native link @intercom/intercom-react-native
 ```
 
 #### Android: Manual linking with React Native v0.59 and below
@@ -81,6 +81,16 @@ implementation project(':intercom-react-native')
 
 #### Android: Setup
 
+You have two options for initializing Intercom:
+
+**Option 1: Native Initialization (Recommended)**
+Initialize at app startup in your native code for the best user experience.
+
+**Option 2: JavaScript Initialization**
+Initialize manually from JavaScript for more control over timing. If you choose this option, skip the native initialization code below and see the [`initialize` method documentation](#intercomintializeapikey-appid) for implementation details.
+
+**For Native Initialization:**
+
 - Add below lines to `android/app/src/main/java/com/YOUR_APP/app/MainApplication.java` inside `onCreate` method, replacing `apiKey` and `appId` which can be found in your [workspace settings](https://app.intercom.com/a/apps/_/settings/android).
 
 ```java
@@ -340,6 +350,16 @@ See [How to manually link IOS Intercom SDK](docs/IOS-MANUAL-LINKING.md)
 
 #### iOS: Setup
 
+You have two options for initializing Intercom:
+
+**Option 1: Native Initialization (Recommended)**
+Initialize at app startup in your native code for the best user experience.
+
+**Option 2: JavaScript Initialization**
+Initialize manually from JavaScript for more control over timing. If you choose this option, skip the native initialization code below and see the [`initialize` method documentation](#intercomintializeapikey-appid) for implementation details with platform-specific API key handling.
+
+**For Native Initialization:**
+
 - Open `ios/AppDelegate.m` then add below code:
 
 - At the top of file add the following:
@@ -359,7 +379,7 @@ See [How to manually link IOS Intercom SDK](docs/IOS-MANUAL-LINKING.md)
   // ...
   self.window.rootViewController = rootViewController;
 
-  [IntercomModule initialize:@"apiKey" withAppId:@"appId"]; // <-- Add this (Remember to replace strings with your api keys)
+  [IntercomModule initialize:@"apiKey" withAppId:@"appId"]; // <-- Add this
 
   return YES;
   }
@@ -383,8 +403,8 @@ func application(_ application: UIApplication, didFinishLaunchingWithOptions lau
      Intercom.setApiKey("<Your iOS API Key>", forAppId: "<Your App ID>")
   ....
 }
- 
- ```
+
+```
 
 #### iOS: Permissions
 
@@ -518,6 +538,7 @@ The plugin provides props for extra customization. Every time you change the pro
 - `androidApiKey` (_string_): Android API Key from Intercom.
 - `iosApiKey` (_string_): iOS API Key from Intercom.
 - `intercomRegion` (_string_): Region for Intercom `US`, `EU`, `AU`. Optional. Defaults to `US`.
+- `useManualInit` (_boolean_): Set to `true` to manually initialize Intercom from JavaScript instead of at app startup. Optional. Defaults to `false`.
 
 ```json
 {
@@ -537,6 +558,41 @@ The plugin provides props for extra customization. Every time you change the pro
 }
 ```
 
+#### Manual Initialization with Expo
+
+If you want to delay Intercom initialization and manually initialize it from JavaScript, you set the `useManualInit` option to `true`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@intercom/intercom-react-native",
+        {
+          "useManualInit": true
+        }
+      ]
+    ]
+  }
+}
+```
+
+Then initialize Intercom manually in your JavaScript code with the platform-specific API keys:
+
+```javascript
+import Intercom from '@intercom/intercom-react-native';
+import { Platform } from 'react-native';
+
+// You can find your API keys in your Intercom workspace settings
+// https://app.intercom.com/a/apps/<your-app-id>/settings/channels/messenger/install?tab=ios
+const apiKey = Platform.select({
+  ios: 'ios_sdk-abc123',
+  android: 'android_sdk-abc123',
+});
+
+await Intercom.initialize(apiKey, 'abc123');
+```
+
 #### Expo: Push notifications
 
 Add the following configurations into your `app.json` or `app.config.js`:
@@ -697,6 +753,38 @@ Sets the user hash necessary for validation when Identity Verification is enable
 
 ---
 
+### `Intercom.initialize(apiKey, appId)`
+
+Initialize the Intercom SDK manually. This is useful when you want to delay initialization until after your app has started, or when using Expo with the `useManualInit` plugin option.
+
+**Important:** This method configures the SDK but does NOT validate your credentials with Intercom's servers. Invalid API keys or App IDs will only be detected when you attempt to use Intercom features (e.g., login, show messenger). The method will return `true` if the SDK is successfully configured, regardless of credential validity.
+
+### Options
+
+| Name   | Type   | Required | Description                             |
+| ------ | ------ | -------- | --------------------------------------- |
+| apiKey | string | yes      | Your Platform-specific Intercom API key |
+| appId  | string | yes      | Your Intercom App ID                    |
+
+### Examples
+
+```javascript
+import { Platform } from 'react-native';
+
+const apiKey = Platform.select({
+  ios: 'ios_sdk-abc123',
+  android: 'android_sdk-xyz789',
+});
+
+await Intercom.initialize(apiKey, 'your_app_id');
+```
+
+### Returns
+
+`Promise<boolean>`
+
+---
+
 ### `Intercom.loginUnidentifiedUser()`
 
 Login a unidentified user.
@@ -1206,6 +1294,39 @@ This should be called before any user login takes place.
 
 ---
 
+### `Intercom.setAuthTokens(authTokens)`
+
+Provide Intercom with your auth tokens which can be used for functionality such as Custom Actions with Data Connectors. You can provide multiple
+tokens at once. To create tokens:
+1. Go to Settings > Integrations > Authentication in your Intercom workspace
+2. Create a new token with "User" type
+3. Configure the token prefix and header as needed
+
+Learn more: https://www.intercom.com/help/en/articles/6615543-setting-up-data-connectors-authentication
+
+This should be called after any user login takes place.
+
+**Note:** This is separate from `setUserJwt()` which is for Messenger Security. `setAuthTokens()` passes JWT tokens to
+Data Connectors (e.g., Fin Actions), which use these in `Authorization: Bearer <token>` headers for API requests.
+
+### Options
+
+| Name       | Type                        | Required | Description                                                  |
+| ---------- | --------------------------- | -------- | ------------------------------------------------------------ |
+| authTokens | `{ [key: string]: string }` | yes      | An object with token names as keys and JWT strings as values |
+
+### Example
+
+```typescript
+Intercom.setAuthTokens({ security_token: "jwt_here" });
+```
+
+### Returns
+
+`Promise<boolean>`
+
+---
+
 ## Author
 
 👤 **Intercom (https://www.intercom.com/)**

android/src/main/java/com/intercom/reactnative/IntercomErrorCodes.java

@@ -10,6 +10,8 @@ public class IntercomErrorCodes {
   public static final String SET_LOG_LEVEL = "107";
   public static final String GET_UNREAD_CONVERSATION = "108";
   public static final String SET_USER_JWT = "109";
+  public static final String SET_AUTH_TOKENS = "110";
+  public static final String INITIALIZE_ERROR = "111";
   public static final String DISPLAY_MESSENGER = "201";
   public static final String DISPLAY_MESSENGER_COMPOSER = "202";
   public static final String DISPLAY_CONTENT = "203";

android/src/main/java/com/intercom/reactnative/IntercomHelpers.java

@@ -15,6 +15,7 @@
 import java.util.List;
 import java.util.Map;
 
+import io.intercom.android.sdk.AuthToken;
 import io.intercom.android.sdk.Company;
 import io.intercom.android.sdk.Intercom;
 import io.intercom.android.sdk.UserAttributes;
@@ -255,4 +256,23 @@ public static WritableMap deconstructRegistration(Registration registration) {
     }
     return registrationMap;
   }
+
+  public static List<AuthToken> buildAuthTokensList(ReadableMap readableMap) {
+    List<AuthToken> authTokens = new ArrayList<>();
+    ReadableMapKeySetIterator iterator = readableMap.keySetIterator();
+
+    while (iterator.hasNextKey()) {
+      String key = iterator.nextKey();
+      ReadableType type = readableMap.getType(key);
+
+      if (type == ReadableType.String) {
+        String value = readableMap.getString(key);
+        if (key != null && value != null && !key.isEmpty() && !value.isEmpty()) {
+          authTokens.add(new AuthToken(key, value));
+        }
+      }
+    }
+
+    return authTokens;
+  }
 }

android/src/newarch/IntercomModule.java

@@ -603,6 +603,46 @@ public void setUserJwt(String jwt, Promise promise) {
     }
   }
 
+  @ReactMethod
+  public void setAuthTokens(ReadableMap authTokens, Promise promise) {
+    try {
+      List<io.intercom.android.sdk.AuthToken> authTokensList = IntercomHelpers.buildAuthTokensList(authTokens);
+      Intercom.client().setAuthTokens(authTokensList, new IntercomStatusCallback() {
+        @Override
+        public void onSuccess() {
+          promise.resolve(true);
+        }
+
+        @Override
+        public void onFailure(@NonNull IntercomError intercomError) {
+          Log.e("ERROR", intercomError.getErrorMessage());
+          promise.reject(String.valueOf(intercomError.getErrorCode()), intercomError.getErrorMessage());
+        }
+      });
+    } catch (Exception err) {
+      Log.e(NAME, "setAuthTokens error:");
+      Log.e(NAME, err.toString());
+      promise.reject(IntercomErrorCodes.SET_AUTH_TOKENS, err.toString());
+    }
+  }
+
+  @ReactMethod
+  public void initialize(String apiKey, String appId, Promise promise) {
+    try {
+      Activity activity = getCurrentActivity();
+      if (activity != null && activity.getApplication() != null) {
+        IntercomModule.initialize(activity.getApplication(), apiKey, appId);
+        promise.resolve(true);
+      } else {
+        promise.reject(IntercomErrorCodes.INITIALIZE_ERROR, "Activity is null");
+      }
+    } catch (Exception err) {
+      Log.e(NAME, "initialize error:");
+      Log.e(NAME, err.toString());
+      promise.reject(IntercomErrorCodes.INITIALIZE_ERROR, err.toString());
+    }
+  }
+
   @ReactMethod
   public void setNeedsStatusBarAppearanceUpdate(Promise promise) {
     // iOS-only method, no-op on Android

android/src/oldarch/IntercomModule.java

@@ -580,6 +580,46 @@ public void setUserJwt(String jwt, Promise promise) {
     }
   }
 
+  @ReactMethod
+  public void setAuthTokens(ReadableMap authTokens, Promise promise) {
+    try {
+      List<io.intercom.android.sdk.AuthToken> authTokensList = IntercomHelpers.buildAuthTokensList(authTokens);
+      Intercom.client().setAuthTokens(authTokensList, new IntercomStatusCallback() {
+        @Override
+        public void onSuccess() {
+          promise.resolve(true);
+        }
+
+        @Override
+        public void onFailure(@NonNull IntercomError intercomError) {
+          Log.e("ERROR", intercomError.getErrorMessage());
+          promise.reject(String.valueOf(intercomError.getErrorCode()), intercomError.getErrorMessage());
+        }
+      });
+    } catch (Exception err) {
+      Log.e(NAME, "setAuthTokens error:");
+      Log.e(NAME, err.toString());
+      promise.reject(IntercomErrorCodes.SET_AUTH_TOKENS, err.toString());
+    }
+  }
+
+  @ReactMethod
+  public void initialize(String apiKey, String appId, Promise promise) {
+    try {
+      Activity activity = getCurrentActivity();
+      if (activity != null && activity.getApplication() != null) {
+        IntercomModule.initialize(activity.getApplication(), apiKey, appId);
+        promise.resolve(true);
+      } else {
+        promise.reject(IntercomErrorCodes.INITIALIZE_ERROR, "Activity is null");
+      }
+    } catch (Exception err) {
+      Log.e(NAME, "initialize error:");
+      Log.e(NAME, err.toString());
+      promise.reject(IntercomErrorCodes.INITIALIZE_ERROR, err.toString());
+    }
+  }
+
   public static synchronized void initialize(Application application, String apiKey, String appId) {
     String sdkVersion = BuildConfig.INTERCOM_VERSION_NAME;
     ReactNativeHeaderInterceptor.setReactNativeVersion(application.getApplicationContext(), sdkVersion);

examples/expo-example/app.json

@@ -39,9 +39,7 @@
       [
         "@intercom/intercom-react-native",
         {
-          "appId": "YOUR_APP_ID",
-          "androidApiKey": "android_sdk-YOUR_ANDROID_API_KEY",
-          "iosApiKey": "ios_sdk-YOUR_IOS_API_KEY"
+          "useManualInit": true
         }
       ],
       "expo-router",