@W-21447618: [React Native Bridge - iOS] Add hiddenPreChatFieldDelegate support

Author: tsaarva

AgentforceSDK-ReactNative-Bridge/android/src/main/java/com/salesforce/android/reactagentforce/AgentforceModule.kt

@@ -74,6 +74,9 @@ class AgentforceModule(reactContext: ReactApplicationContext) :
     // Bridge view provider for delegating native SDK views to React Native components
     private val bridgeViewProvider = BridgeViewProvider(reactContext)
 
+    // Bridge hidden prechat fields (Service Agent only)
+    private val bridgeHiddenPreChat = BridgeHiddenPreChat()
+
     // Coroutine scope for async operations
     private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
 
@@ -616,6 +619,7 @@ class AgentforceModule(reactContext: ReactApplicationContext) :
         currentMode = null
         credentialProvider.reset()
         bridgeViewProvider.reset()
+        bridgeHiddenPreChat.setFields(emptyMap())
         employeePrefs.edit().remove(KEY_EMPLOYEE_AGENT_ID).apply()
         promise.resolve(Arguments.createMap().apply {
             putBoolean("success", true)
@@ -627,6 +631,38 @@ class AgentforceModule(reactContext: ReactApplicationContext) :
     // region Event Emitter Support
     // endregion
 
+    // region Hidden PreChat Fields
+
+    /**
+     * Pre-register hidden prechat field values for the next Service Agent session.
+     *
+     * TODO: Implement AgentforceHiddenPreChatFieldDelegate on BridgeHiddenPreChat
+     * and pass to client.init(hiddenPreChatFieldDelegate = bridgeHiddenPreChat).
+     * See iOS BridgeHiddenPreChat.swift for reference. Until then, fields are
+     * stored but not sent to the SDK.
+     */
+    @ReactMethod
+    fun registerHiddenPreChatFields(fields: ReadableMap, promise: Promise) {
+        val map = mutableMapOf<String, String>()
+        val iterator = fields.keySetIterator()
+        while (iterator.hasNextKey()) {
+            val key = iterator.nextKey()
+            fields.getString(key)?.let { map[key] = it }
+        }
+        bridgeHiddenPreChat.setFields(map)
+        promise.resolve(null)
+    }
+
+    @ReactMethod
+    fun getHiddenPreChatFields(promise: Promise) {
+        val result = Arguments.createMap()
+        for ((key, value) in bridgeHiddenPreChat.getFields()) {
+            result.putString(key, value)
+        }
+        promise.resolve(result)
+    }
+    // endregion
+
     // region Additional Context
 
     /**

AgentforceSDK-ReactNative-Bridge/android/src/main/java/com/salesforce/android/reactagentforce/BridgeHiddenPreChat.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2026-present, salesforce.com, inc. All rights reserved.
+ *
+ * React Native bridge for hidden prechat field delegate
+ *
+ * TODO: Implement AgentforceHiddenPreChatFieldDelegate interface.
+ * See BridgeHiddenPreChat.swift (iOS) for the reference implementation.
+ *
+ * Expected behavior:
+ * - Store fields set via setFields()
+ * - Implement AgentforceHiddenPreChatFieldDelegate.agentforce() to return
+ *   only values for fields the SDK requests (filter stored map by requested field names)
+ * - Return null when no fields are stored or no requested fields match
+ * - Use @Volatile for thread-safe reads (matches BridgeLogger pattern)
+ */
+package com.salesforce.android.reactagentforce
+
+class BridgeHiddenPreChat {
+
+    @Volatile
+    private var fields: Map<String, String> = emptyMap()
+
+    fun setFields(fields: Map<String, String>) {
+        this.fields = fields
+    }
+
+    fun getFields(): Map<String, String> = fields
+}

AgentforceSDK-ReactNative-Bridge/ios/Agentforce/AgentforceModule.m

@@ -71,6 +71,15 @@ @interface RCT_EXTERN_MODULE(AgentforceModule, RCTEventEmitter)
 RCT_EXTERN_METHOD(startNewConversation:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 
+// MARK: - Hidden PreChat Fields
+
+RCT_EXTERN_METHOD(registerHiddenPreChatFields:(NSDictionary *)fields
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getHiddenPreChatFields:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
 // MARK: - Additional Context
 
 RCT_EXTERN_METHOD(setAdditionalContext:(NSDictionary *)contextDict

AgentforceSDK-ReactNative-Bridge/ios/Agentforce/AgentforceModule.swift

@@ -42,6 +42,12 @@ class AgentforceModule: RCTEventEmitter {
     private let listenerLock = NSLock()
     private var _hasListeners = false
 
+    // MARK: - Hidden PreChat Fields
+
+    /// Bridge delegate for hidden prechat fields (Service Agent only).
+    /// Strongly retained here because AgentforceClient holds it as a weak reference.
+    private let bridgeHiddenPreChat = BridgeHiddenPreChat()
+
     // MARK: - Logging
 
     /// Bridge logger for forwarding SDK logs to JavaScript.
@@ -180,6 +186,7 @@ class AgentforceModule: RCTEventEmitter {
             mode: .fullConfig(fullConfiguration),
             viewProvider: bridgeViewProvider
         )
+        agentforceClient?.hiddenPreChatFieldDelegate = bridgeHiddenPreChat
     }
 
     // MARK: - Employee Agent Configuration
@@ -813,6 +820,7 @@ class AgentforceModule: RCTEventEmitter {
     private func cleanupClient() {
         currentConversation = nil
         agentforceClient = nil
+        bridgeHiddenPreChat.setFields([:])
     }
 
     /// Close the conversation
@@ -829,6 +837,36 @@ class AgentforceModule: RCTEventEmitter {
         }
     }
 
+    // MARK: - Hidden PreChat Fields
+
+    /// Pre-register hidden prechat field values for the next Service Agent session.
+    @objc
+    func registerHiddenPreChatFields(
+        _ fields: NSDictionary,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let dict = fields as? [String: String] else {
+            reject(
+                "INVALID_FIELDS",
+                "Hidden prechat fields must be a map of string keys to string values",
+                nil
+            )
+            return
+        }
+        bridgeHiddenPreChat.setFields(dict)
+        resolve(nil)
+    }
+
+    /// Get the currently registered hidden prechat field values.
+    @objc
+    func getHiddenPreChatFields(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        resolve(bridgeHiddenPreChat.getFields())
+    }
+
     // MARK: - Additional Context
 
     /// Helper function to recursively convert Any value to JSEncodableValue

AgentforceSDK-ReactNative-Bridge/ios/Agentforce/BridgeHiddenPreChat.swift

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2026-present, salesforce.com, inc. All rights reserved.
+ *
+ * React Native bridge for hidden prechat field delegate
+ */
+
+import Foundation
+import AgentforceSDK
+import AgentforceService
+
+/// Bridge delegate that returns pre-registered hidden prechat field values
+/// to the native Agentforce SDK during Service Agent session initialization.
+///
+/// JavaScript calls `registerHiddenPreChatFields({ key: value })` to store
+/// field values. When the SDK calls the delegate, only values for fields the
+/// SDK actually requests are returned; absent fields are omitted.
+///
+/// Must be strongly retained on the module because `AgentforceClient` holds
+/// `hiddenPreChatFieldDelegate` as a weak reference.
+class BridgeHiddenPreChat: NSObject, AgentforceHiddenPreChatFieldDelegate {
+
+    // MARK: - Properties
+
+    private let lock = NSLock()
+    private var _fields: [String: String] = [:]
+
+    // MARK: - Public API
+
+    /// Replace the stored field values. Pass an empty dictionary to clear.
+    func setFields(_ fields: [String: String]) {
+        lock.withLock { _fields = fields }
+    }
+
+    /// Return a snapshot of the current field values.
+    func getFields() -> [String: String] {
+        lock.withLock { _fields }
+    }
+
+    // MARK: - AgentforceHiddenPreChatFieldDelegate
+
+    func agentforce(
+        didRequestHiddenPreChatValues requestedFields: [AgentforceHiddenPreChatField]
+    ) async -> [String: String]? {
+        let stored = lock.withLock { _fields }
+        guard !stored.isEmpty else { return nil }
+
+        var result: [String: String] = [:]
+        for field in requestedFields {
+            if let value = stored[field.name] {
+                result[field.name] = value
+            }
+        }
+        return result.isEmpty ? nil : result
+    }
+}

AgentforceSDK-ReactNative-Bridge/src/index.ts

@@ -17,7 +17,7 @@ export {
 } from './services/EmployeeAgentAuth';
 export type { AuthCredentials } from './services/EmployeeAgentAuth';
 
-export type { ServiceAgentConfig, EmployeeAgentConfig, AgentConfig, FeatureFlags, LegacyServiceAgentConfig, ConfigurationResult, ConfigurationInfo, LoggerDelegate, LogLevel, NavigationDelegate, NavigationRequest, AgentforceAdditionalContext, AgentforceContextVariable, AgentforceContextVariableType, ViewProviderDelegate, ViewProviderComponentData } from './types';
+export type { ServiceAgentConfig, EmployeeAgentConfig, AgentConfig, FeatureFlags, LegacyServiceAgentConfig, ConfigurationResult, ConfigurationInfo, LoggerDelegate, LogLevel, NavigationDelegate, NavigationRequest, AgentforceAdditionalContext, AgentforceContextVariable, AgentforceContextVariableType, ViewProviderDelegate, ViewProviderComponentData, HiddenPreChatFields } from './types';
 export { isServiceAgentConfig, isEmployeeAgentConfig, isLegacyConfig } from './types';
 
 export {

AgentforceSDK-ReactNative-Bridge/src/services/AgentforceService.ts

@@ -33,6 +33,7 @@ import type {
   AgentforceContextVariableType,
 } from '../types/AgentforceContext';
 import { ViewProviderDelegate } from '../types/ViewProviderDelegate';
+import type { HiddenPreChatFields } from '../types/HiddenPreChatFields';
 
 const { AgentforceModule } = NativeModules;
 
@@ -42,6 +43,7 @@ export type { LoggerDelegate, LogLevel };
 export type { NavigationDelegate, NavigationRequest };
 export type { AgentforceAdditionalContext, AgentforceContextVariable };
 export type { ViewProviderDelegate };
+export type { HiddenPreChatFields };
 
 /**
  * Native module event names
@@ -838,6 +840,86 @@ class AgentforceService {
     }
   }
 
+  /**
+   * Pre-register hidden prechat field values for Service Agent conversations.
+   *
+   * Call this before `launchConversation()` to supply values for prechat fields
+   * hidden from the end user (e.g. ContactId, AccountId, session tokens).
+   * When the SDK initializes a Service Agent session, these values are returned
+   * to the native delegate automatically.
+   *
+   * Fields not present in the provided map are omitted (not sent as empty strings),
+   * so the SDK treats them as unset.
+   *
+   * @remarks Service Agent only. Has no effect for Employee Agent conversations.
+   *
+   * @param fields - Map of field developer names to string values
+   *
+   * @example
+   * ```typescript
+   * await AgentforceService.registerHiddenPreChatFields({
+   *   ContactId: '003xx0000001234',
+   *   AccountId: '001xx0000005678',
+   * });
+   * await AgentforceService.launchConversation();
+   * ```
+   */
+  async registerHiddenPreChatFields(fields: HiddenPreChatFields): Promise<void> {
+    if (Platform.OS !== 'android' && Platform.OS !== 'ios') {
+      return;
+    }
+
+    if (!AgentforceModule) {
+      console.warn('[AgentforceService] Native module not available');
+      return;
+    }
+
+    try {
+      await AgentforceModule.registerHiddenPreChatFields(fields);
+      const count = Object.keys(fields).length;
+      console.log(
+        `[AgentforceService] Hidden prechat fields registered: ${count} field(s)`,
+      );
+    } catch (error) {
+      console.error(
+        '[AgentforceService] Failed to register hidden prechat fields:',
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Clear all pre-registered hidden prechat field values.
+   *
+   * @remarks Service Agent only.
+   */
+  async clearHiddenPreChatFields(): Promise<void> {
+    await this.registerHiddenPreChatFields({});
+  }
+
+  /**
+   * Get the currently registered hidden prechat field values.
+   *
+   * @returns The stored field map, or an empty object if none registered.
+   */
+  async getHiddenPreChatFields(): Promise<HiddenPreChatFields> {
+    if (Platform.OS !== 'android' && Platform.OS !== 'ios') {
+      return {};
+    }
+
+    if (!AgentforceModule?.getHiddenPreChatFields) {
+      return {};
+    }
+
+    try {
+      const fields = await AgentforceModule.getHiddenPreChatFields();
+      return (fields as HiddenPreChatFields) ?? {};
+    } catch {
+      return {};
+    }
+  }
+
   /**
    * Reset all settings and clear the SDK state.
    *

AgentforceSDK-ReactNative-Bridge/src/types/HiddenPreChatFields.ts

@@ -0,0 +1,18 @@
+/**
+ * Hidden prechat field values for Service Agent conversations.
+ *
+ * Maps field developer names to their string values. These values are
+ * submitted with the prechat form but are not visible to the end user.
+ *
+ * @remarks Service Agent only. Has no effect for Employee Agent conversations.
+ *
+ * @example
+ * ```typescript
+ * const fields: HiddenPreChatFields = {
+ *   ContactId: '003xx0000001234',
+ *   AccountId: '001xx0000005678',
+ *   Subject: 'Mobile App Support',
+ * };
+ * ```
+ */
+export type HiddenPreChatFields = Record<string, string>;

AgentforceSDK-ReactNative-Bridge/src/types/index.ts

@@ -33,3 +33,6 @@ export {
 
 // View provider delegate types
 export { ViewProviderDelegate, ViewProviderComponentData } from './ViewProviderDelegate';
+
+// Hidden prechat field types
+export type { HiddenPreChatFields } from './HiddenPreChatFields';