Registering Soups with Configuration Files

Beginning with Mobile SDK 6.0SmartStore lets you define soup structures through configuration files rather than code. Since all platforms and app types use the same configuration files, you can describe all your soups in a single file. You can then compile that file into any project.

To register a soup, you provide a soup name and a list of one or more index specifications.

You index a soup on one or more fields found in its entries. SmartStore makes sure that these indexes reflect any insert, update, and delete operations. Always specify at least one index field when registering a soup. For example, if you are using the soup as a simple key-value store, use a single index specification with a string type.

Overview

SmartStore configuration files use JSON objects to express soup definitions. 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 soups for the default global store, provide a file named globalstore.json.
To define soups for the default user store, provide a file named userstore.json.

Configuration files can define soups only in the default global store and default user store. For named stores, you register soups through code. You can’t use configuration files to set up externally stored soups.

Configuration files are intended for initial setup only. You can't change existing soups by revising the JSON file and reloading it at runtime. Instead, use SmartStore methods such as alterSoup(). See Managing Soups.
If a configuration file defines a soup that exists, Mobile SDK ignores the configuration file. In this case, you can set up and manage your soups only through code.

Note

Configuration File Format

The JSON format is self-evident as illustrated in the following example.

1{  "soups": [
2    {
3      "soupName": "soup1",
4      "indexes": [
5        { "path": "stringField1", "type": "string"},
6        { "path": "integerField1", "type": "integer"},
7        { "path": "floatingField1", "type": "floating"},
8        { "path": "json1Field1", "type": "json1"},
9        { "path": "ftsField1", "type": "full_text"}
10      ]
11    },
12    {
13      "soupName": "soup2",
14      "indexes": [
15        { "path": "stringField2", "type": "string"},
16        { "path": "integerField2", "type": "integer"},
17        { "path": "floatingField2", "type": "floating"},
18        { "path": "json1Field2", "type": "json1"},
19        { "path": "ftsField2", "type": "full_text"}
20      ]
21    }
22  ]
23}

For Mobile Sync compatibility, configuration files also require indexes on some system fields. See Preparing Soups for.

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:

Place the configuration file in the top-level www/ folder.
In the top-level project directory, run: cordova prepare

Loading SmartStore Configuration Files in Native Apps

SmartStore and its companion feature Mobile Sync require a special SDK manager object. For example, to use SmartStore or Mobile Sync in iOS, initialize the SDK by calling MobileSyncSDKManager.initializeSDK() rather than SalesforceSDKManager.initializeSDK().

If you’re not using Mobile Sync, you can call SmartStoreSDKManager.initializeSDK(). However, such cases are rare.

In native and React Native apps, you load your JSON configuration file by calling a loading method. Make this call in your app initialization code after the customer successfully logs in. For example, in iOS, make this call in the block you pass to loginIfRequired. Call these methods only if you’re using a globalstore.json or userstore.json file instead of code to configure SmartStore. Do not call these loading methods more than once. In hybrid apps that include them, SmartStore configuration files are loaded automatically.

To load a soup configuration file, call the loader method for the store you’re targeting. Load this file before calling other SmartStore methods.

iOS (Native and React Native)

Load a soup configuration file by calling the appropriate method on the MobileSyncSDKManager object.

Load a Default User Store

Swift

1// In the AppDelegate class:
2override init() {
3        super.init()
4        MobileSyncSDKManager.initializeSDK()
5...
6
7// Load config files in the block you pass to loginIfRequired()
8func application(_ application: UIApplication, didFinishLaunchingWithOptions 
9    launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
10
11    self.window = UIWindow(frame: UIScreen.main.bounds)
12    self.initializeAppViewState()
13    // ...
14
15    AuthHelper.loginIfRequired {
16        self.setupRootViewController()
17        MobileSyncSDKManager.shared.setupUserStoreFromDefaultConfig()
18    }
19...

Objective-C

1// In the AppDelegate class:
2- (instancetype)init
3{
4    self = [super init];
5    if (self) {
6        [MobileSyncSDKManager initializeSDK];
7...
8
9// Load config files in the block you pass to loginIfRequired()
10- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
11{
12    self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
13    [self initializeAppViewState];
14...
15
16    [SFSDKAuthHelper loginIfRequired:^{
17        [self setupRootViewController];
18        [[MobileSyncSDKManager sharedManager] setupUserStoreFromDefaultConfig];
19    }];
20...

Load a Default Global Store

Swift

1// In the AppDelegate class:
2override init() {
3        super.init()
4        MobileSyncSDKManager.initializeSDK()
5...
6
7// Load config files in the block you pass to loginIfRequired()
8func application(_ application: UIApplication, didFinishLaunchingWithOptions 
9    launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
10    self.window = UIWindow(frame: UIScreen.main.bounds)
11    self.initializeAppViewState()
12    // ...
13
14    AuthHelper.loginIfRequired {
15        self.setupRootViewController()
16        MobileSyncSDKManager.shared.setupGlobalStoreFromDefaultConfig()
17    }
18...

Objective-C

1// In the AppDelegate class:
2- (instancetype)init
3{
4    self = [super init];
5    if (self) {
6        [MobileSyncSDKManager initializeSDK];
7...
8
9// Load config files in the block you pass to loginIfRequired()
10- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
11{
12    self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
13    [self initializeAppViewState];
14...
15
16    [SFSDKAuthHelper loginIfRequired:^{
17        [self setupRootViewController];
18        [[MobileSyncSDKManager sharedManager] setupGlobalStoreFromDefaultConfig];
19    }];
20...

Android (Native and React Native)

Load a soup configuration file by calling the appropriate method on the MobileSyncSDKManager object.

Load a Default User Store

1public class MainApplication extends Application {
2
3    @Override
4    public void onCreate() {
5        super.onCreate();
6        MobileSyncSDKManager.initNative(getApplicationContext(), MainActivity.class);
7        MobileSyncSDKManager.getInstance().setupUserStoreFromDefaultConfig();
8...

Load a Default Global Store

1public class MainApplication extends Application {
2
3    @Override
4    public void onCreate() {
5        super.onCreate();
6        MobileSyncSDKManager.initNative(getApplicationContext(), MainActivity.class);
7        MobileSyncSDKManager.getInstance().setupGlobalStoreFromDefaultConfig();
8...

Hybrid

If SmartStore finds a soup configuration file, it automatically loads the file. To add the file to your project:

Copy the configuration file (userstore.json or globalstore.json) to the top-level www/ directory of your hybrid project directory.
In a command prompt or Terminal window, change to your hybrid project directory and run: cordova prepare

Sample Code

MobileSyncExplorer and MobileSyncExplorerHybrid sample apps use a config file to set up SmartStore soups.

Call the SmartStore loader method only if you are using a userstore.json to define soups. If you set up your soups with code instead of configuration files, don't call the loader method.
Call the loader method after the customer has logged in.
Do not call a loader method more than once.

Note

Example

SmartStore uses the same configuration file—userstore.json—for native and hybrid versions of the MobileSyncExplorer sample. The final five paths in this configuration are required if you’re using Mobile Sync.

1{  "soups": [
2    {
3      "soupName": "contacts",
4      "indexes": [
5        { "path": "Id", "type": "string"},
6        { "path": "FirstName", "type": "string"},
7        { "path": "LastName", "type": "string"},
8        { "path": "__local__", "type": "string"},
9        { "path": "__locally_created__", "type": "string"},
10        { "path": "__locally_updated__", "type": "string"},
11        { "path": "__locally_deleted__", "type": "string"},
12        { "path": "__sync_id__", "type": "integer"}
13      ]
14    }
15  ]
16}

Mobile SDK Development Guide