Skip to content

Commit 381a7bf

Browse files
wmathurinwmathurin
authored
Merge pull request #308 from wmathurin/W-22864424-hybrid-docs
W-22864424: Add docs/hybrid/README.md
2 parents 2b7b9bd + bdbb5d0 commit 381a7bf

1 file changed

Lines changed: 137 additions & 0 deletions

File tree

‎docs/hybrid/README.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# iOS Hybrid SDK — Contributor Guide
2+
3+
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.
4+
5+
**Minimum iOS deployment target:** 18.0
6+
7+
---
8+
9+
## SalesforceHybridSDK Pod
10+
11+
The primary deliverable is the `SalesforceHybridSDK` pod, declared in `SalesforceHybridSDK.podspec` at the repo root.
12+
13+
| Attribute | Value |
14+
|-----------|-------|
15+
| Pod name | `SalesforceHybridSDK` |
16+
| Current version | 14.0.0 |
17+
| Key dependency | `MobileSync ~> 14.0.0` (pulls the full iOS SDK chain) |
18+
| Cordova dependency | `Cordova 7.1.1` |
19+
| Source files | `libs/SalesforceHybridSDK/SalesforceHybridSDK/Classes/**/*.{h,m,swift}` |
20+
21+
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`).
22+
23+
---
24+
25+
## Plugin Classes
26+
27+
Located under `libs/SalesforceHybridSDK/SalesforceHybridSDK/Classes/Plugins/`:
28+
29+
| Plugin | Directory | Header | Purpose |
30+
|--------|-----------|--------|---------|
31+
| `SalesforceOAuthPlugin` | `SFOAuthPlugin/` | `SalesforceOAuthPlugin.h` | OAuth authentication and user management |
32+
| `SFNetworkPlugin` | `SFNetworkPlugin/` | `SFNetworkPlugin.h` | REST API requests to Salesforce |
33+
| `SFSDKInfoPlugin` | `SDKInfo/` | `SFSDKInfoPlugin.h` | SDK version and configuration info |
34+
| `SFSmartStorePlugin` | `SFSmartStore/` | `SFSmartStorePlugin.h` | Encrypted local storage (SmartStore) |
35+
| `SFMobileSyncPlugin` | `SFMobileSyncPlugin/` | `SFMobileSyncPlugin.h` | Data synchronization framework |
36+
| `SFAccountManagerPlugin` | `SFAccountManagerPlugin/` | `SFAccountManagerPlugin.h` | Multi-user account management |
37+
| `SFForcePlugin` | `SFForcePlugin/` | `SFForcePlugin.h` | Base class for Salesforce Cordova plugins |
38+
| `CDVPlugin+SFAdditions` | `SFAdditions/` | `CDVPlugin+SFAdditions.h` | Category adding Salesforce helpers to CDVPlugin |
39+
40+
Each plugin is an Objective-C subclass of `CDVPlugin` (or `SFForcePlugin`) and exposes methods callable from JavaScript via the Cordova bridge.
41+
42+
---
43+
44+
## `shared/hybrid/` — Bootstrap Files Copied to CordovaPlugin
45+
46+
The `shared/hybrid/` directory contains Objective-C files that `tools/update.sh` in the CordovaPlugin repo copies to `src/ios/classes/`:
47+
48+
| File | Role |
49+
|------|------|
50+
| `AppDelegate.m` | Application entry point that bootstraps the Salesforce hybrid runtime (OAuth, SDK initialization, view controller setup) |
51+
| `InitialViewController.h` / `.m` | Root view controller displayed before the Cordova WKWebView loads |
52+
| `UIApplication+SalesforceHybridSDK.h` / `.m` | UIApplication category that tracks last-event timing for passcode inactivity |
53+
54+
The directory also contains `config.xml` and `cordova_plugins.js`, but only the Objective-C files are copied to the CordovaPlugin.
55+
56+
### Why `AppDelegate.m` lives here
57+
58+
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.
59+
60+
---
61+
62+
## `external/shared/` — Shared JavaScript Submodule
63+
64+
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.
65+
66+
Other submodules:
67+
68+
| Path | Repository |
69+
|------|------------|
70+
| `external/SalesforceMobileSDK-iOS` | iOS native SDK |
71+
| `external/cordova` | Apache Cordova iOS |
72+
| `external/CocoaLumberjack` | Logging library |
73+
74+
---
75+
76+
## Sample Apps
77+
78+
Located under `hybrid/SampleApps/`:
79+
80+
- **AccountEditor** — Basic CRUD operations on Account records using Cordova plugins
81+
- **MobileSyncExplorerHybrid** — Full MobileSync demo with offline sync and conflict resolution
82+
83+
Their JavaScript source comes from the `external/shared/` submodule.
84+
85+
---
86+
87+
## Version Management
88+
89+
`setversion.sh` updates the SDK version in both podspecs:
90+
91+
```bash
92+
./setversion.sh -v 14.0.0
93+
```
94+
95+
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).
96+
97+
---
98+
99+
## Running Unit Tests
100+
101+
Open the workspace and run the `SalesforceHybridSDK` scheme tests:
102+
103+
```bash
104+
# Setup (first time)
105+
./install.sh
106+
107+
# Run tests
108+
xcodebuild test \
109+
-workspace SalesforceMobileSDK-Hybrid.xcworkspace \
110+
-scheme SalesforceHybridSDK \
111+
-sdk iphonesimulator \
112+
-destination 'platform=iOS Simulator,name=iPhone 16'
113+
```
114+
115+
Always open `SalesforceMobileSDK-Hybrid.xcworkspace` (not individual `.xcodeproj` files) to ensure CocoaPods dependencies resolve correctly.
116+
117+
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:
118+
119+
```bash
120+
cp shared/test/test_credentials.json.sample shared/test/test_credentials.json
121+
# then edit with your Connected App credentials and org details
122+
```
123+
124+
The file must contain:
125+
126+
```json
127+
{
128+
"test_client_id": "<Connected App consumer key>",
129+
"test_login_domain": "<login URL, e.g. test.salesforce.com>",
130+
"test_redirect_uri": "<Connected App callback URL>",
131+
"refresh_token": "<valid refresh token>",
132+
"instance_url": "<org instance URL>",
133+
"identity_url": "<identity URL>"
134+
}
135+
```
136+
137+
`test_credentials.json` is gitignored — never commit real credentials.

0 commit comments

Comments
 (0)