From 23e97952b480e8f47cde711522127f660140d62c Mon Sep 17 00:00:00 2001 From: Wolfgang Mathurin Date: Fri, 5 Jun 2026 15:54:55 -0700 Subject: [PATCH 1/3] Add docs/hybrid/README.md New documentation for the iOS-Hybrid repo's role as iOS native bridge: SalesforceHybridSDK pod (plugin class implementations), shared/hybrid/ ObjC bootstrap files copied to CordovaPlugin, Shared submodule usage, SampleApps JS sourcing, podspec publishing model, why AppDelegate.m lives here and how the post-install hook redirects to it, and unit test instructions. --- docs/hybrid/README.md | 103 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/hybrid/README.md diff --git a/docs/hybrid/README.md b/docs/hybrid/README.md new file mode 100644 index 0000000..0e5e120 --- /dev/null +++ b/docs/hybrid/README.md @@ -0,0 +1,103 @@ +# iOS Hybrid SDK — Contributor Guide + +This repository provides the **iOS native bridge** for Salesforce Mobile SDK hybrid (Cordova) apps. It delivers the `SalesforceHybridSDK` CocoaPods pod and contains the Objective-C bootstrap files that are copied into the CordovaPlugin distribution. + +**Minimum iOS deployment target:** 18.0 + +--- + +## SalesforceHybridSDK Pod + +The primary deliverable is the `SalesforceHybridSDK` pod, declared in `SalesforceHybridSDK.podspec` at the repo root. + +| Attribute | Value | +|-----------|-------| +| Pod name | `SalesforceHybridSDK` | +| Current version | 14.0.0 | +| Key dependency | `MobileSync ~> 14.0.0` (pulls the full iOS SDK chain) | +| Cordova dependency | `Cordova 7.1.1` | +| Source files | `libs/SalesforceHybridSDK/SalesforceHybridSDK/Classes/**/*.{h,m,swift}` | + +In **dev builds**, the CordovaPlugin's `plugin.xml` references this pod directly from the GitHub repo on the `dev` branch. In **GA releases**, it references the pod by version tag (e.g., `v14.0.0`). + +--- + +## Plugin Classes + +Located under `libs/SalesforceHybridSDK/SalesforceHybridSDK/Classes/Plugins/`: + +| Plugin | Directory | Header | Purpose | +|--------|-----------|--------|---------| +| `SalesforceOAuthPlugin` | `SFOAuthPlugin/` | `SalesforceOAuthPlugin.h` | OAuth authentication and user management | +| `SFNetworkPlugin` | `SFNetworkPlugin/` | `SFNetworkPlugin.h` | REST API requests to Salesforce | +| `SFSDKInfoPlugin` | `SDKInfo/` | `SFSDKInfoPlugin.h` | SDK version and configuration info | +| `SFSmartStorePlugin` | `SFSmartStore/` | `SFSmartStorePlugin.h` | Encrypted local storage (SmartStore) | +| `SFMobileSyncPlugin` | `SFMobileSyncPlugin/` | `SFMobileSyncPlugin.h` | Data synchronization framework | +| `SFAccountManagerPlugin` | `SFAccountManagerPlugin/` | `SFAccountManagerPlugin.h` | Multi-user account management | +| `SFForcePlugin` | `SFForcePlugin/` | `SFForcePlugin.h` | Base class for Salesforce Cordova plugins | +| `CDVPlugin+SFAdditions` | `SFAdditions/` | `CDVPlugin+SFAdditions.h` | Category adding Salesforce helpers to CDVPlugin | + +Each plugin is an Objective-C subclass of `CDVPlugin` (or `SFForcePlugin`) and exposes methods callable from JavaScript via the Cordova bridge. + +--- + +## `shared/hybrid/` — Bootstrap Files Copied to CordovaPlugin + +The `shared/hybrid/` directory contains Objective-C files that `tools/update.sh` in the CordovaPlugin repo copies to `src/ios/classes/`: + +| File | Role | +|------|------| +| `AppDelegate.m` | Application entry point that bootstraps the Salesforce hybrid runtime (OAuth, SDK initialization, view controller setup) | +| `InitialViewController.h` / `.m` | Root view controller displayed before the Cordova WKWebView loads | +| `UIApplication+SalesforceHybridSDK.h` / `.m` | UIApplication category that tracks last-event timing for passcode inactivity | + +The directory also contains `config.xml` and `cordova_plugins.js`, but only the Objective-C files are copied to the CordovaPlugin. + +### Why `AppDelegate.m` lives here + +When `cordova platform add ios` runs, Cordova generates its own `AppDelegate.m`. The CordovaPlugin's `postinstall-ios.js` hook patches `project.pbxproj` to redirect the AppDelegate reference to `Plugins/com.salesforce/AppDelegate.m` — the SDK version that initializes the Salesforce hybrid runtime (OAuth, SDK manager, hybrid view controller). Without this patch, none of the Salesforce Cordova plugins would function. + +--- + +## `external/shared/` — Shared JavaScript Submodule + +SalesforceMobileSDK-Shared is included as a git submodule at `external/shared/`. The hybrid sample apps reference JavaScript libraries (force.js, smartstore.js, mobilesync.js) from this submodule. + +Other submodules: + +| Path | Repository | +|------|------------| +| `external/SalesforceMobileSDK-iOS` | iOS native SDK | +| `external/cordova` | Apache Cordova iOS | +| `external/CocoaLumberjack` | Logging library | + +--- + +## Sample Apps + +Located under `hybrid/SampleApps/`: + +- **AccountEditor** — Basic CRUD operations on Account records using Cordova plugins +- **MobileSyncExplorerHybrid** — Full MobileSync demo with offline sync and conflict resolution + +Their JavaScript source comes from the `external/shared/` submodule. + +--- + +## Running Unit Tests + +Open the workspace and run the `SalesforceHybridSDK` scheme tests: + +```bash +# Setup (first time) +./install.sh + +# Run tests +xcodebuild test \ + -workspace SalesforceMobileSDK-Hybrid.xcworkspace \ + -scheme SalesforceHybridSDK \ + -sdk iphonesimulator \ + -destination 'platform=iOS Simulator,name=iPhone 16' +``` + +Always open `SalesforceMobileSDK-Hybrid.xcworkspace` (not individual `.xcodeproj` files) to ensure CocoaPods dependencies resolve correctly. From 6580339337cfc62fdba6b2a4b03acdec1fa7a133 Mon Sep 17 00:00:00 2001 From: Wolfgang Mathurin Date: Fri, 5 Jun 2026 18:45:39 -0700 Subject: [PATCH 2/3] =?UTF-8?q?Document=20setversion.sh=20=E2=80=94=20upda?= =?UTF-8?q?tes=20both=20podspecs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/hybrid/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/hybrid/README.md b/docs/hybrid/README.md index 0e5e120..7e8c16f 100644 --- a/docs/hybrid/README.md +++ b/docs/hybrid/README.md @@ -84,6 +84,18 @@ Their JavaScript source comes from the `external/shared/` submodule. --- +## Version Management + +`setversion.sh` updates the SDK version in both podspecs: + +```bash +./setversion.sh -v 14.0.0 +``` + +This updates `s.version` in `SalesforceHybridSDK.podspec` and `SalesforceFileLogger.podspec`. This script has no `-d` flag — the dev/GA distinction for iOS is controlled by CordovaPlugin's `plugin.xml` (which references the pod by `branch="dev"` or `tag="v14.0.0"` depending on the build type). + +--- + ## Running Unit Tests Open the workspace and run the `SalesforceHybridSDK` scheme tests: From bdbb5d06f7bc69c8e0cf4fde51bdf9899cab31f8 Mon Sep 17 00:00:00 2001 From: Wolfgang Mathurin Date: Fri, 5 Jun 2026 18:50:07 -0700 Subject: [PATCH 3/3] Document test_credentials.json requirement for SalesforceHybridSDK tests --- docs/hybrid/README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/hybrid/README.md b/docs/hybrid/README.md index 7e8c16f..ac2de8d 100644 --- a/docs/hybrid/README.md +++ b/docs/hybrid/README.md @@ -113,3 +113,25 @@ xcodebuild test \ ``` Always open `SalesforceMobileSDK-Hybrid.xcworkspace` (not individual `.xcodeproj` files) to ensure CocoaPods dependencies resolve correctly. + +Most tests require a `test_credentials.json` file at `shared/test/test_credentials.json`. Without it, only tests that do not make authenticated Salesforce API calls will pass. Copy the sample and fill in your org details: + +```bash +cp shared/test/test_credentials.json.sample shared/test/test_credentials.json +# then edit with your Connected App credentials and org details +``` + +The file must contain: + +```json +{ + "test_client_id": "", + "test_login_domain": "", + "test_redirect_uri": "", + "refresh_token": "", + "instance_url": "", + "identity_url": "" +} +``` + +`test_credentials.json` is gitignored — never commit real credentials.