Mobile SDK Development Guide

Introduction to Mobile Development
Introduction to Salesforce Mobile SDK Development
What’s New in Mobile SDK 11.1
Getting Started With Mobile SDK 11.1 for iOS and Android
Updating Apps (5.0 and Later) Apps (5.0 and Later)
Native iOS Development
Native Android Development
HTML5 and Hybrid Development
Using Lightning Web Components in Hybrid Apps
React Native Development
Offline Management
Using SmartStore to Securely Store Offline Data
Using Mobile Sync to Access Salesforce Objects
Using Mobile Sync in Native Apps
Creating Native Apps with
Adding Mobile Sync to Existing Android Apps
Adding to Existing iOS Apps
About Sync Targets
Defining Sync Names and Sync Configuration Files
Using Sync Names
Syncing Data
Using Standard Targets
Using Custom Sync Down Targets
Using Custom Sync Up Targets
Syncing Related Records
Using Mobile Sync in Hybrid and React Native Apps
Validating Configuration Files
Files and Networking
Push Notifications and
Authentication, Security, and Identity in Mobile Apps
Login Screen Customization
Identity Provider Apps
Using Key-Value Stores for Secure Data Storage
Dark Mode and Dark Theme Settings
Using Experience Cloud Sites With Mobile SDK Apps
Multi-User Support in Mobile SDK
Mobile SDK Tools for Developers
Logging and Analytics
Migrating from the Previous Release
Reference
iOS Current Deprecations
iOS APIs Removed in Mobile SDK 11.0
Android Current Deprecations
Android APIs Removed in Mobile SDK 11.0
Trademark Attributions
Removing UIWebView from iOS Hybrid Apps
PDF

Defining Sync Names and Sync Configuration Files

Beginning in Mobile SDK 6.0, you can define sync configuration files and assign names to sync configurations. You can use sync names to run, edit, or delete a saved sync operation. Since all platforms and app types use the same configuration files, you can describe all your syncs in a single file. You can then compile that file into any Mobile SDK project.
Mobile Sync configuration files use JSON objects to express sync definitions. You can provide these files to avoid coding sync down and sync up configurations. The JSON schema for configuration files is the same for all app types and platforms. Hybrid apps load the configuration files automatically, while other apps load them with a single line of code. To keep the mechanism simple, Mobile SDK enforces the following file naming conventions:
  • To define sync operations for the default global store, provide a file named globalsyncs.json.
  • To define sync operations for the default user store, provide a file named usersyncs.json.
Configuration files can define syncs only in the default global store and default user store. For named stores, you define syncs through code.

In native and React Native apps, you load your JSON configuration file by calling a sync loading method. Call this method in your app initialization code after the customer successfully logs in. For example, in iOS, call this method in the block you pass to loginIfRequired. Call these methods only if you’re using a globalsyncs.json or usersyncs.json file instead of code to configure your syncs. Don’t call sync loading methods more than one time.

In hybrid apps that include them, sync configuration files are loaded automatically. To see loader examples, study the MobileSyncExplorer and MobileSyncExplorerHybrid sample apps. These apps use configuration files to set up their sync operations.

  • Configuration files are intended for initial setup only. You can't change existing syncs by revising the JSON file and reloading it at runtime. Instead, you can use a syncUp or syncDown method to define the sync inline.
  • If the name that a configuration file assigns to a sync operation exists, Mobile SDK ignores the configuration file. In this case, you can set up and manage your sync only through code.

Note

Configuration File Format

The following example demonstrates the configuration file format.

1{
2    "syncs": [
3        {
4            "syncName": "sync1",
5            "syncType": "syncDown",
6            "soupName": "accounts",
7            "target": {"type":"soql", 
8                       "query":"SELECT Id, Name, LastModifiedDate 
9                                FROM Account", 
10                       "maxBatchSize":200},
11            "options": {"mergeMode":"OVERWRITE"}
12        },
13        {
14            "syncName": "sync2",
15            "syncType": "syncUp",
16            "soupName": "accounts",
17            "target": {"createFieldlist":["Name"]},
18            "options": {"fieldlist":["Id", "Name", "LastModifiedDate"], 
19                        "mergeMode":"LEAVE_IF_CHANGED"}
20        }
21    ]
22}

For sync down, the "target" property’s "type" property accepts any one of the following values:

  • "soql"
    Uses a SOQL query for sync down.
    Properties:
    • "type":"soql"
    • "query": <string>
    • "idFieldName": <string>
    • "modificationDateFieldName": <string>
    • "maxBatchSize": <integer>, any value from 200 and 2,000 (default value is 2,000)

    Required: "type", "query"

  • "sosl"
    Uses a SOSL query for sync down.
    Properties:
    • "type":"sosl"
    • "query": <string>
    • "idFieldName": <string>
    • "modificationDateFieldName": <string>
    • "maxBatchSize": <integer>, any value from 200 and 2,000 (default value is 2,000)

    Required: "type", "query"

  • "briefcase"
    Uses a briefcase for sync down.
    Properties:
    • "type":"briefcase"
    • "infos": array of <BriefcaseObjectInfo> items

    Required: "type", "infos"

    See Using the Briefcase Sync Down Target

  • "mru"
    Syncs most recently used records for the given object.
    Properties:
    • "type":"mru"
    • "sobjectType": <string>
    • "fieldlist": array of <string> items
    • "idFieldName": <string>
    • "modificationDateFieldName": <string>

    Required: "type", "sobjectType", "fieldlist"

  • "refresh"
    Refreshes a sync of the given object and fields in the given soup.
    Properties:
    • "type":"refresh"
    • "sobjectType": <string>
    • "fieldlist": array of <string> items
    • "soupName": <string>
    • "idFieldName": <string>
    • "modificationDateFieldName": <string>

    Required: "type", "sobjectType", "fieldlist", "soupName"

  • "layout"
    Syncs layouts for the given object.
    Properties:
    • "type":"layout"
    • "sobjectType": <string>
    • "formFactor": Choice: <"Large" | "Medium" | "Small">
    • "layoutType": Choice: <"Compact" | "Full">
    • "mode": Choice: <"Create" | "Edit" | "View">
    • "recordTypeId": <string>
    • "idFieldName": <string>
    • "modificationDateFieldName": <string>

    Required: "type", "sobjectType", "layoutType"

  • "metadata"
    Syncs metadata for the given object.
    Properties:
    • "type":"metadata"
    • "sobjectType": <string>
    • "idFieldName": <string>
    • "modificationDateFieldName": <string>

    Required: "type", "sobjectType"

  • "parent_children"
    Syncs related records for the given parent object.
    Properties: See Syncing Related Records.
  • "custom"
    Syncs using your custom sync down target. Assign the names of your native target sync down classes for iOS and Android the "iOSImpl" and "androidImpl" properties.
    Properties:
    • "type":"custom"
    • "iOSImpl": <string>
    • "androidImpl": <string>
    • "idFieldName": <string>
    • "modificationDateFieldName": <string>

    Required: "type", "iOSImpl", "androidImpl"

By default, sync up targets defined in sync config files use batch APIs. In addition, all sync up targets:
  • Can define a "createFieldList" property.
  • Can define an "updateFieldList" property.
  • Don’t define a "type" property.

Here are the specific settings for the various types of sync up targets.

  • sObject Collection
    Standard sync up target type for Mobile SDK 10.1 and later.
    Properties:
    • "createFieldlist": array of <string> items
    • "updateFieldlist": array of <string> items
    • "externalIdFieldName": <string>

    Required: none

  • Batch
    Similar to the standard target, but uses smaller batch operations. Standard target for Mobile SDK 7.1 to 10.0.
    Properties:
    • "createFieldlist": array of <string> items
    • "updateFieldlist": array of <string> items
    • "externalIdFieldName": <string>

    Required: none

  • Non-batch
    Similar to the standard target, but doesn’t use batch or collection operations.
    Properties:
    • "iOSImpl":"SFSyncUpTarget"
    • "androidImpl":"com.salesforce.androidsdk.mobilesync.target.SyncUpTarget"
    • "createFieldlist": array of <string> items
    • "updateFieldlist": array of <string> items
    • "externalIdFieldName": <string>

    Required: "iOSImpl", "androidImpl"

  • Parent-child
    Syncs related records for the given parent object.
    Properties: See Syncing Related Records.
  • Custom
    Syncs using your custom sync up target. Assign the names of your native sync up target classes for iOS and Android to the "iOSImpl" and "androidImpl" properties.
    Properties:
    • "iOSImpl": <string>
    • "androidImpl": <string>
    • "createFieldlist": array of <string> items
    • "updateFieldlist": array of <string> items

    Required: "iOSImpl", "androidImpl"

Target JSON definitions are specified in the Mobile Sync JSON schema.

Configuration File Locations

Configuration file placement varies according to app type and platform. Mobile SDK looks for configuration files in the following locations:
iOS (Native and React Native)
Under / in the Resources bundle
Android (Native and React Native)
In the /res/raw project folder
Hybrid
In your Cordova project, do the following:
  1. Place the configuration file in the top-level www/ folder.
  2. In the top-level project directory, run: cordova prepare

Loading Sync Definitions from Configuration Files (iOS Native Apps)

Loading methods are defined on the MobileSyncSDKManager class.

User store
Swift
1MobileSyncSDKManager.sharedManager.setupUserSyncsFromDefaultConfig()
Objective-C
1[[MobileSyncSDKManager sharedManager] setupUserSyncsFromDefaultConfig];
Global store
Swift
1MobileSyncSDKManager.sharedManager.setupGlobalSyncsFromDefaultConfig()
Objective-C
[[MobileSyncSDKManager sharedManager] setupGlobalSyncsFromDefaultConfig];

Loading Sync Definitions from Configuration Files (Android Native Apps)

Loading methods are defined on the MobileSyncSDKManager. You can call these loaders from anywhere in your app. Make sure that the call occurs before you call any sync or resync functions.

User store
MobileSyncSDKManager.getInstance().setupUserSyncsFromDefaultConfig();
Global store
MobileSyncSDKManager.getInstance().setupGlobalSyncsFromDefaultConfig();