Mobile SDK Development Guide Developer

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 444

DownloadMobile SDK Development Guide Developer
Open PDF In BrowserView PDF
Mobile SDK Development Guide
Salesforce Mobile SDK 5.1 (Android Native,
iOS Native, and Hybrid)

@salesforcedocs
Last updated: April 27, 2017

© Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,

as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTS
Chapter 1: Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Introduction to Mobile Development . . . . . . . . .
Customize Salesforce1, or Create a Custom App?
About This Guide . . . . . . . . . . . . . . . . . . . . . .
Version . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Feedback . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

2
2
4
4
4

Chapter 2: Introduction to Salesforce Mobile SDK Development . . . . . . . . . . . . . . . . . . 5
About Native, HTML5, and Hybrid Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Enough Talk; I’m Ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 3: What's New in Mobile SDK 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
What Was New in Recent Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 4: Getting Started With Mobile SDK 5.1 for Android and iOS . . . . . . . . . . . . . . 13
Developer Edition or Sandbox Environment? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Development Prerequisites for Android and iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Sign Up for Force.com . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Creating a Connected App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Create a Connected App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Installing Mobile SDK for Android and iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Mobile SDK npm Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Mobile SDK GitHub Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Mobile SDK Sample Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Installing the Sample Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 5: Updating Mobile SDK Apps (5.0 and Later) . . . . . . . . . . . . . . . . . . . . . . . 25
Using Maven to Update Mobile SDK Libraries in Android Apps . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 6: Welcome to Mobile SDK Labs! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
React Native for Salesforce Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Mobile SDK Native Modules for React Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Mobile SDK Sample App Using React Native . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Defer Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Upload Binary Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Mobile UI Elements with Polymer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
force_selector_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
force-selector-relatedlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
force-sobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
force-sobject-collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Contents

force-sobject-layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
force-sobject-relatedlists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
force-sobject-store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
force-ui-app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
force-ui-detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
force-ui-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
force-ui-relatedlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 7: Native iOS Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
iOS Native Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Native iOS Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Creating an iOS Project with forceios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Run the Xcode Project Template App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Using a Custom Template to Create Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Use CocoaPods with Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Refreshing Mobile SDK Pods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Developing a Native iOS App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
About Login and Passcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
About Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Overview of Application Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
SalesforceSDKManager and SalesforceSDKManagerWithSmartStore Classes . . . . . . . . . 54
AppDelegate Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
About View Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
RootViewController Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
About Salesforce REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Handling Authentication Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Using iOS App Extensions with Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Tutorial: Creating a Native iOS Warehouse App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Create a Native iOS App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Customize the List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Create the Detail Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
iOS Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 8: Native Android Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Android Native Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Native Android Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Creating an Android Project with forcedroid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Using a Custom Template to Create Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Setting Up Sample Projects in Android Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Android Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Developing a Native Android App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Android Application Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Native API Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Overview of Native Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Contents

Using Passcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Resource Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Using REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Unauthenticated REST Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Deferring Login in Native Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Android Template App: Deep Dive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Tutorial: Creating a Native Android Warehouse Application . . . . . . . . . . . . . . . . . . . . . . . . 137
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Create a Native Android App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Customize the List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Create the Detail Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Android Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Chapter 9: HTML5 and Hybrid Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Using HTML5 and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
HTML5 Development Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Multi-Device Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
HTML5 Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Delivering HTML5 Content With Visualforce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Accessing Salesforce Data: Controllers vs. APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Hybrid Apps Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Creating Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
About Hybrid Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Building Hybrid Apps With Cordova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Developing Hybrid Remote Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Hybrid Sample Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Running the ContactExplorer Hybrid Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Debugging Hybrid Apps On a Mobile Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Debugging a Hybrid App On an Android Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Debugging a Hybrid App Running On an iOS Device . . . . . . . . . . . . . . . . . . . . . . . . . 183
Controlling the Status Bar in iOS 7 Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
JavaScript Files for Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Versioning and JavaScript Library Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Example: Serving the Appropriate Javascript Libraries . . . . . . . . . . . . . . . . . . . . . . . . 187
Managing Sessions in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Defer Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Remove SmartStore and SmartSync From an Android Hybrid App . . . . . . . . . . . . . . . . . . . . 191

Chapter 10: Offline Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Using SmartStore to Securely Store Offline Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
About SmartStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Enabling SmartStore in Hybrid and Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Adding SmartStore to Existing Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Contents

Creating and Accessing User-based Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Using Global SmartStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Registering a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Using Arrays in Index Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Populating a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Retrieving Data from a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Smart SQL Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Using Full-Text Search Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Working with Query Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Inserting, Updating, and Upserting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Using External Storage for Large Soup Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Removing Soup Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Managing Soups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Managing Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Testing with the SmartStore Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Using the Mock SmartStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Using SmartSync to Access Salesforce Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Using SmartSync in Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Using SmartSync in Hybrid and React Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Chapter 11: Files and Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Downloading Files and Managing Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Uploading Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Encryption and Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Using Files in Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Managing the Request Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Using Files in iOS Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Managing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Using Files in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Chapter 12: Push Notifications and Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
About Push Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Using Push Notifications in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Code Modifications (Hybrid) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Using Push Notifications in Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Configure a Connected App For GCM (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Code Modifications (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Using Push Notifications in iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Configure a Connected App for APNS (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Code Modifications (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Chapter 13: Authentication, Security, and Identity in Mobile Apps . . . . . . . . . . . . . . 332
OAuth Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Contents

OAuth 2.0 Authentication Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
OAuth 2.0 User-Agent Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
OAuth 2.0 Refresh Token Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Scope Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Using Identity URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Setting Custom Login Servers in Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Setting Custom Login Servers in iOS Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Hiding the Settings Icon in iOS Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Revoking OAuth Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Refresh Token Revocation in Android Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Connected Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
About PIN Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Portal Authentication Using OAuth 2.0 and Force.com Sites . . . . . . . . . . . . . . . . . . . . . . . . 347
Customizing the Salesforce Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Using MDM with Salesforce Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Sample Property List Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Chapter 14: Using Communities With Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . 352
Communities and Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Set Up an API-Enabled Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Set Up a Permission Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Grant API Access to Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Configure the Login Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Brand Your Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Customize Login, Self-Registration, and Password Management for Your Community . . . . . . 357
Using External Authentication With Communities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
External Authentication Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Using the Community URL Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Use the Scope Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Configure a Facebook Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Configure a Salesforce Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Configure an OpenID Connect Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . 366
Example: Configure a Community For Mobile SDK App Access . . . . . . . . . . . . . . . . . . . . . 368
Add Permissions to a Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Create a Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Add the API User Profile To Your Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Create a New Contact and User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Test Your New Community Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Example: Configure a Community For Facebook Authentication . . . . . . . . . . . . . . . . . . . . . 371
Create a Facebook App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Define a Salesforce Auth. Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Configure Your Facebook App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Customize the Auth. Provider Apex Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Configure Your Salesforce Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

Contents

Chapter 15: Multi-User Support in Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
About Multi-User Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Implementing Multi-User Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Android Native APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
iOS Native APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Hybrid APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Chapter 16: Migrating from Previous Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Migrate Android Apps from 5.0 to 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Migrate iOS Apps from 5.0 to 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Migrate Hybrid Apps from 5.0 to 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Migrating from Earlier Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Migrate Android Apps from 4.3 to 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Migrate iOS Apps from 4.3 to 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Migrate Hybrid Apps from 4.3 to 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Migrate Android Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Migrate iOS Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Migrate Hybrid Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Migrate Android Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Migrate iOS Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Migrate Hybrid Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Migrate Android Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Migrate iOS Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Migrate Hybrid Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Chapter 17: Instrumentation and Event Collection . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Chapter 18: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
REST API Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
iOS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Native REST API Classes for iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Android Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Android Packages and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Android Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Files API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
FileRequests Methods (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
SFRestAPI (Files) Category—Request Methods (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Files Methods For Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Forceios Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Forcedroid Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

CHAPTER 1
In this chapter ...
•

Introduction to
Mobile Development

•

Customize
Salesforce1, or
Create a Custom
App?

•

About This Guide

•

Sending Feedback

Preface
In less than a decade, mobile devices have profoundly changed our personal and professional lives. From
impromptu videos to mobile geolocation to online shopping, people everywhere use personal mobile
devices to create and consume content. Corporate employees, too, use smart devices to connect with
customers, stay in touch with coworkers, and engage the public on social networks.
For enterprise IT departments, the explosion of mobile interaction requires a quick response in software
services. Salesforce provides the Salesforce App Cloud to address this need. This cloud supports
new-generation mobile operating systems on various form factors—phone, tablet, wearable—with
reliability, availability, and security. Its technologies let you build custom apps, connect to data from any
system, and manage your enterprise from anywhere.

1

Preface

Introduction to Mobile Development

Introduction to Mobile Development
The Salesforce App Cloud offers two ways to build and deploy enterprise-ready mobile applications.
• Salesforce1 Application, available on Apple AppStore and Google Play Store, delivers the fastest way for Force.com administrators
and developers to build and deliver apps for employees. It offers simple point-and-click tools for administrators and the Lightning
web development platform for advanced developers. This trail doesn’t address Salesforce1 application development.
• Salesforce Mobile SDK gives developers the tools to build mobile applications with customized user experiences. Mobile SDK lets
you produce stand-alone custom apps that you distribute through the Apple App Store or Google Play Store. These apps can target
employees, customers, or partners. You can choose native or web technologies to build these apps while enjoying the same grade
of reliability and security found in Salesforce1. This trail teaches you how to get started with Mobile SDK app development.
Mobile SDK harnesses platform technology for a complete mobile development platform. Its modular architecture provides features
and services such as:
Enterprise Identity & Security
Mobile SDK includes a complete implementation of Salesforce Connected App Policy, so that all users can access their data securely
and easily. It supports SAML and advanced authentication flows so that administrators always have full control over data access.
SmartStore Encrypted Database
Mobile databases are useful for building highly responsive apps that also work in any network condition. SmartStore provides an
easy way to store and retrieve data locally while supporting a flexible data model. It also uses AES-256 encryption to ensure that
your data is always protected.
SmartSync Data Synchronization
SmartSync provides a simple API for synchronizing data between your offline database and the Salesforce cloud. With SmartSync,
developers can focus on the UI and business logic of their application while leaving the complex synchronization logic to Mobile
SDK.
Mobile Services
Mobile SDK supports a wide range of platform mobile services, including push notifications, geolocation, analytics, collaboration
tools, and business logic in the cloud. These services can supercharge your mobile application and also reduce development time.
Salesforce Communities
With Salesforce Communities and Mobile SDK, developers can build mobile applications that target your customers and partners.
These applications benefit from the same enterprise features and reliability as employee apps.
Native and Hybrid
Mobile SDK lets you choose any technology (native, React Native, or Cordova-based hybrid apps) on iOS and Android.

Customize Salesforce1, or Create a Custom App?
When it comes to developing functionality for your Salesforce mobile users, you have options. Although this book deals only with Mobile
SDK development, here are some differences between Salesforce1 apps and custom apps built with Mobile SDK.
For more information on Salesforce1, see developer.salesforce.com/docs.

Customizing Salesforce1
• Has a pre-defined user interface.
• Has full access to Salesforce data.
• You can create an integrated experience with functionality developed in the Salesforce App Cloud.

2

Preface

Customize Salesforce1, or Create a Custom App?

• The Action Bar gives you a way to include your own apps/functionality.
• You can customize Salesforce1 with either point-and-click or programmatic customizations.
• Functionality can be added programmatically through Visualforce pages or Force.com Canvas apps.
• Salesforce1 customizations or apps adhere to the Salesforce1 navigation. So, for example, a Visualforce page can be called from the
navigation menu or from the Action Bar.
• You can leverage existing Salesforce development experience, both point-and-click and programmatic.
• Included in all Salesforce editions and supported by Salesforce.

Developing Custom Mobile Apps
Custom apps can be free-standing apps built on Salesforce Mobile SDK, or browser apps using plain HTML5 and JavaScript with Ajax.
With custom apps, you can:
• Define a custom user experience.
• Access Salesforce data using REST APIs in native and hybrid local apps, or with Visualforce in hybrid apps using JavaScript Remoting.
In HTML5 apps, do the same using JQueryMobile and Ajax.
• Brand your user interface for customer-facing exposure.
• Create standalone mobile apps, either with native APIs using Java for Android or Objective-C for iOS, or through a hybrid container
using JavaScript and HTML5 (Mobile SDK only).
• Distribute apps through mobile industry channels, such as the Apple App Store or Google Play (Mobile SDK only).
• Configure and control complex offline behavior (Mobile SDK only).
• Use push notifications.
• Design a custom security container using your own OAuth module (Mobile SDK only).
• Other important Mobile SDK considerations:
– Open-source SDK, downloadable for free through npm installers as well as from GitHub.
– Requires you to develop and compile your apps in an external development environment (Xcode for iOS, Android Studio for
Android).
– Development costs depend on your app and your platform.
Mobile SDK integrates Force.com cloud architecture into Android and iOS apps by providing:
• Implementation of Salesforce Connected App policy.
• Salesforce login and OAuth credentials management, including persistence and refresh capabilities.
• Secure offline storage with SmartStore.
• Syncing between the Salesforce cloud and SmartStore through SmartSync.
• Support for Salesforce Communities.
• Wrappers for Salesforce REST APIs with implicit networking.
• Fast switching between multiple users.
• Cordova-based containers for hybrid apps.

3

Preface

About This Guide

About This Guide
This guide introduces you to Salesforce Mobile SDK and teaches you how to design, develop, and manage mobile applications for the
cloud. The topics cover a wide range of development techniques for various skill sets, beginning with HTML5 and JavaScript, continuing
through hybrid apps, and culminating in native development.
We’ve included tutorials for major features. Most of these tutorials take you through the steps of creating a simple master-detail application
that accesses Salesforce through REST APIs. Tutorials include:
• Running the ContactExplorer Hybrid Sample
• Tutorial: Creating a Native Android Warehouse Application
• Tutorial: Creating a Native iOS Warehouse App
• Tutorial: Creating a Hybrid SmartSync Application
Shorter, less formal tutorials are scattered throughout the book.

Intended Audience
This guide is primarily for developers who are already familiar with mobile technology, OAuth2, and REST APIs, and who probably have
some Force.com experience. But if that doesn’t exactly describe you, don’t worry. We’ve tried to make this guide usable for a wider
audience. For example, you might be a Salesforce admin who’s developing a new mobile app to support your organization, or you might
be a mobile developer who’s entirely new to Force.com. If either of those descriptions fit you, then you should be able to follow along
just fine.

Mobile SDK and Trailhead
You can learn most of the content of this guide interactively in Trailhead. In the Mobile SDK Beginner’s Trail, you study each development
topic online and then earn points and badges through interactive exercises and quizzes. See trailhead.salesforce.com/trail/mobile_sdk_intro.
Note: An online version of this book is available at developer.salesforce.com/docs.

Version
This book is current with Salesforce Mobile SDK 5.1.

Sending Feedback
Questions or comments about this book? Suggestions for topics you'd like to see covered in future versions? You can:
• Join the SalesforceMobileSDK community at plus.google.com/communities
• Post your thoughts on the Salesforce developer discussion forums at developer.salesforce.com/forums
• Email us directly at developerforce@salesforce.com
• Use the Feedback button at the bottom of each page in the online documentation
(developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/)
.

4

CHAPTER 2 Introduction to Salesforce Mobile SDK
Development
In this chapter ...
•

About Native,
HTML5, and Hybrid
Development

•

Enough Talk; I’m
Ready

Salesforce Mobile SDK lets you harness the power of Force.com within stand-alone mobile apps.
Force.com provides a straightforward and productive platform for Salesforce cloud computing. Developers
can use Force.com to define Salesforce application components—custom objects and fields, workflow
rules, Visualforce pages, Apex classes, and triggers. They can then assemble those components into
awesome, browser-based desktop apps.
Unlike a desktop app, a Mobile SDK app accesses Salesforce data through a mobile device’s native
operating system rather than through a browser. To ensure a satisfying and productive mobile user
experience, you can configure Mobile SDK apps to move seamlessly between online and offline states.
Before you dive into Mobile SDK, take a look at how mobile development works, and learn about essential
Salesforce developer resources.

5

Introduction to Salesforce Mobile SDK Development

About Native, HTML5, and Hybrid Development

About Native, HTML5, and Hybrid Development
Salesforce Mobile SDK gives you options for how you’ll develop your app. The option you choose depends on your development skills,
device and technology requirements, goals, and schedule.
Salesforce Mobile SDK offers three ways to create mobile apps:
• Native apps are specific to a given mobile platform (iOS or Android) and use the development tools and language that the respective
platform supports (for example, Xcode and Objective-C with iOS, Android Studio and Java with Android). Native apps look and
perform best but require the most development effort.
• HTML5 apps use standard web technologies—typically HTML5, JavaScript, and CSS—to deliver apps through a mobile web browser.
This “write once, run anywhere” approach to mobile development creates cross-platform mobile applications that work on multiple
devices. While developers can create sophisticated apps with HTML5 and JavaScript alone, some challenges remain, such as session
management, secure offline storage, and access to native device functionality (such as camera, calendar, notifications, and so on).
• Hybrid apps combine the ease of HTML5 web app development with the power of the native platform by wrapping a web app
inside the Salesforce container. This combined approach produces an application that can leverage the device’s native capabilities
and be delivered through the app store. You can also create hybrid apps using Visualforce pages delivered through the Salesforce
hybrid container.

Native Apps
Native apps provide the best usability, the best features, and the best overall mobile experience. There are some things you get only
with native apps:
• Fast graphics API—The native platform gives you the fastest graphics, which might not be a big deal if you’re showing a static
screen with only a few elements, but might be a very big deal if you’re using a lot of data and require a fast refresh.
• Fluid animation—Related to the fast graphics API is the ability to have fluid animation. This is especially important in gaming,
highly interactive reporting, or intensely computational algorithms for transforming photos and sounds.
• Built-in components—The camera, address book, geolocation, and other features native to the device can be seamlessly integrated
into mobile apps. Another important built-in component is encrypted storage, but more about that later.

6

Introduction to Salesforce Mobile SDK Development

About Native, HTML5, and Hybrid Development

• Ease of use—The native platform is what people are accustomed to. When you add that familiarity to the native features they
expect, your app becomes that much easier to use.
Native apps are usually developed using an integrated development environment (IDE). IDEs provide tools for building, debugging,
project management, version control, and other tools professional developers need. You need these tools because native apps are more
difficult to develop. Likewise, the level of experience required is higher than in other development scenarios. If you’re a professional
developer, you don’t have to be sold on proven APIs and frameworks, painless special effects through established components, or the
benefits of having all your code in one place.

HTML5 Apps
An HTML5 mobile app is essentially one or more web pages that are designed to work on a small mobile device screen. As such, HTML5
apps are device agnostic and can be opened with any modern mobile browser. Because your content is on the web, it’s searchable,
which can be a huge benefit for certain types of apps (shopping, for example).
Getting started with HTML5 is easier than with native or hybrid development. Unfortunately, every mobile device seems to have its own
idea of what constitutes usable screen size and resolution. This diversity imposes an additional burden of testing on different devices
and different operating systems.
An important part of the "write once, run anywhere" HTML5 methodology is that distribution and support is much easier than for native
apps. Need to make a bug fix or add features? Done and deployed for all users. For a native app, there are longer development and
testing cycles, after which the consumer typically must log into a store and download a new version to get the latest fix.
If HTML5 apps are easier to develop, easier to support, and can reach the widest range of devices, what are the drawbacks?
• No secure offline storage—HTML5 browsers support offline databases and caching, but with no out-of-the-box encryption
support. You get all three features in Mobile SDK native applications.
• Unfriendly security features—Trivial security measures can pose complex implementation challenges in mobile web apps. They
can also be painful for users. For example, a web app with authentication requires users to enter their credentials every time the app
restarts or returns from a background state.
• Limited native features—The camera, address book, and other native features are accessible on few, if any, browser platforms.
• Lack of native look and feel—HTML5 can only emulate the native look, and customers won’t be able to use familiar compound
gestures.

Hybrid Apps
Hybrid apps are built using HTML5 and JavaScript wrapped inside a thin container that provides access to native platform features. For
the most part, hybrid apps provide the best of both worlds, being almost as easy to develop as HTML5 apps with all the functionality of
native. In addition, hybrid apps can use the SmartSync Data Framework in JavaScript to
• Model, query, search, and edit Salesforce data.
• Securely cache Salesforce data for offline use.
• Synchronize locally cached data with the Salesforce server.
You know that native apps are installed on the device, while HTML5 apps reside on a web server, so you might be wondering whether
hybrid apps store their files on the device or on a server? You can implement a hybrid app locally or remotely.
Locally
You can package HTML and JavaScript code inside the mobile application binary, in a structure similar to a native application. In this
scenario you use REST APIs and Ajax to move data back and forth between the device and the cloud.

7

Introduction to Salesforce Mobile SDK Development

Enough Talk; I’m Ready

Remotely
Alternatively, you can implement the full web application from the server (with optional caching for better performance). Your
container app retrieves the full application from the server and displays it in a browser window.
Both types of hybrid development are covered here.

Native, HTML5, and Hybrid Summary
The following table shows how the three mobile development scenarios stack up.
Native

HTML5

Hybrid

Graphics

Native APIs

HTML, Canvas, SVG

HTML, Canvas, SVG

Performance

Fastest

Fast

Fast

Look and feel

Native

Emulated

Emulated

Distribution

App store

Web

App store

Camera

Yes

Browser dependent

Yes

Notifications

Yes

No

Yes

Contacts, calendar

Yes

No

Yes

Offline storage

Secure file system

Not secure; shared SQL,
Key-Value stores

Secure file system; shared SQL

Geolocation

Yes

Yes

Yes

Swipe

Yes

Yes

Yes

Pinch, spread

Yes

Yes

Yes

Connectivity

Online, offline

Mostly online

Online, offline

Development skills

Objective-C, Java

HTML5, CSS, JavaScript

HTML5, CSS, JavaScript

Enough Talk; I’m Ready
If you’d rather read about the details later, there are Quick Start topics in this guide for each native development scenario.
• Hybrid Apps Quick Start
• iOS Native Quick Start
• Android Native Quick Start

8

CHAPTER 3 What's New in Mobile SDK 5.1
In this chapter ...
•

What Was New in
Recent Releases

The 5.1 release brings Mobile SDK support for recent REST API enhancements. It also includes updates
for SmartSync in native apps. For details on updating your code, see Migrating from Previous Releases.

How to Upgrade Your Apps
To upgrade existing Mobile SDK apps, follow the instructions at Migrating from Previous Releases.

General Updates (All Platforms)
In the Force.com REST API, SOSL search response bodies recently changed. Instead of returning an array
of matching records, SOSL search now returns a dictionary. The array of matching records is in this
dictionary under the key “searchRecords”. Mobile SDK 5.1 has amended all SOSL code in its libraries to
handle the new response format.
Important: If your application uses SOSL, be sure to update your code accordingly!
See Force.com REST API Developer Guide.

What’s New in Mobile SDK 5.1 for Android
To keep up with recent innovations in the Force.com REST API, Mobile SDK adds support for the following
features:
• If-Unmodified-Since conditional requests.
• Use of “Id” as the external ID field for upserts, coupled with null for the external ID. This pattern is
useful if you’re upserting multiple records with different external ID fields.
• SObjectTree requests.
• Batch requests.
• Composite requests.
All API changes occur in the RestRequest class. See RestRequest Class.

What’s New in Mobile SDK 5.1 for iOS
• To keep up with recent innovations in the Force.com REST API, Mobile SDK adds support for the
following features:
– ifUnmodifiedSinceDate conditional requests.
– Use of “Id” as the external ID field for upserts, coupled with null for the external ID. This pattern
is useful if you’re upserting multiple records with different external ID fields.
– SObjectTree requests.

9

What's New in Mobile SDK 5.1

– Batch requests.
– Composite requests.
See Supported Operations for more information.
• Our native network stack now uses NSURLSession directly via the new SFNetwork class.
These classes replace the CSFNetwork and CSFAction classes.

What’s New in Hybrid Apps for Mobile SDK 5.1
We’ve replaced our custom WKWebViewEngine plug-in with Cordova's WKWebViewEngine
plug-in.

What’s New in SmartSync for Mobile SDK 5.1
• Thanks to API refactoring, custom targets can now control SmartSync interaction with SmartStore
databases. See About Sync Targets.
• You can now initialize “sync up” targets with separate field lists for create and update operations.
This configuration can sometimes save you from implementing a custom “sync up” target.
– Native apps and native targets: Defining a Custom Sync Up Target.
– Hybrid apps: SmartSync Plugin Methods.

What’s New in React Native for Mobile SDK 5.1
• Version Update—Mobile SDK is now built with React Native version 0.43.1.
• SmartSync Update—Handling of field lists for “sync up” operations has changed in Mobile SDK
5.1. See SmartSync Plugin Methods.

10

What's New in Mobile SDK 5.1

What Was New in Recent Releases

What Was New in Recent Releases
Here’s an archive of What’s New bulletins from recent Mobile SDK releases.

Mobile SDK 5.0
What Was New in Mobile SDK 5.0 for Android
• We've added a library named SalesforceAnalytics. This library collects non-sensitive data that tells us which Mobile SDK
features are being used. The analytics feature is on by default, but you can turn it off if necessary. See Instrumentation and Event
Collection.
• The forcedroid utility now supports rich app templates. See Using a Custom Template to Create Apps.
• Mobile SDK for Android now requires the following versions of third-party tools.
– Java JDK 8
– Gradle 2.14.1
– Target API version: Android Nougat (API 25)
– Android Studio 2.2
– Cordova Android 6.1.0 (hybrid apps)
– Cordova CLI 6.4.0 (hybrid apps)
• We’ve removed dependencies on the guava library.
What Was New in Mobile SDK 5.0 for iOS
• The forceios utility now supports rich app templates. See Using a Custom Template to Create Apps.
• As a result of refactoring libraries, our CocoaPods pod specs have changed. See Migrate iOS Apps from 4.3 to 5.0 for details.
• iOS app extensions are now fully supported. See the SmartSyncExplorer sample app for an example.
• Salesforce servers are now fully ATS-compliant. As a result, we have removed ATS exceptions from Mobile SDK apps.
Mobile SDK for iOS now requires the following versions of third-party tools.
• iOS 9 (minimum), iOS 10 (fully supported)
• Xcode 8
• CocoaPods 1.10 (minimum)
• Cordova iOS 4.3.0 (hybrid apps)
• Cordova CLI 6.4.0 (hybrid apps)
What Was New in Hybrid Apps for Mobile SDK 5.0
• Mobile SDK upgrades its Cordova requirements as follows:
– iOS: Cordova 4.3.0
– Android: Cordova 6.1.0
– Cordova CLI 6.4.0 or later
• The forceios and forceios utilities now support rich app templates. See Using a Custom Template to Create Apps.
• The forcetk.mobilesdk.js library has been replaced with force.js. This new library handles networking natively
through the com.salesforce.plugin.network plug-in. As a result, you no longer have to refresh session tokens in your
own code.

11

What's New in Mobile SDK 5.1

What Was New in Recent Releases

Note: This update results in breaking changes for hybrid apps. See Migrate Hybrid Apps from 4.3 to 5.0 for details.
• A new JavaScript library, force+promise.js, serves as an alternative to force.js and reimplements force.js using
promises instead of callbacks.
• We’ve changed the way you run hybrid tests and sample apps in a browser.
Note: This update results in breaking changes for hybrid apps. See Migrate Hybrid Apps from 4.3 to 5.0 for details.
See the following SmartStore and SmartSync sections for more JavaScript updates.
What Was New in SmartStore for Mobile SDK 5.0
• We’ve made it easier for hybrid and React Native apps to use multiple named stores, either global or user-based. Hybrid SmartStore
APIs that previously accepted an optional isGlobalStore first argument now give you an extra option. Instead of a Boolean
value, you can provide a StoreConfig object that specifies an optional store name and indicates whether the store you’re using
is global. See Creating and Accessing User-based Stores.
• A new Cordova plug-in, com.salesforce.plugin.smartstore.client, reimplements SmartStore APIs using promises
instead of callbacks.
• The parameter list for moveCursorToNextPage() and moveCursorToPreviousPage() JavaScript functions has
changed. See Migrate Hybrid Apps from 4.3 to 5.0.
What Was New in SmartSync for Mobile SDK 5.0
• SmartSync provides a new “refresh” target that is streamlined for easily importing cloud data into cached SmartStore records.
• SmartSync now lets you specify which fields to include in sync down and refresh operations.
• The smartsync.js library has dropped jQuery and implemented native promises. If you use this library on Android 19, see
Migrate Hybrid Apps from 4.3 to 5.0 for an important instruction.
What Was New in React Native for Mobile SDK 5.0
• Version Update—Mobile SDK is now built with React Native version 0.35.
• Many SmartStore and SmartSync APIs receive non-breaking changes to their prototypes. See What Was New in Hybrid Apps for
Mobile SDK 5.0 for more information.

Mobile SDK 4.3
What Was New in SmartStore for Mobile SDK 4.3
• For Android only, SmartStore upgrades SQLCipher to version 3.5.2 (July 2016). For iOS, SmartStore remains on SQLCipher 3.4.0 (April
2016).
• To enhance performance in certain edge cases, SmartStore adds an option for serializing unusually large soup elements in external
storage. See Using External Storage for Large Soup Elements.
What Was New in Hybrid Apps for Mobile SDK 4.3
• Mobile SDK 4.3 upgrades its Cordova support as follows:
– iOS: Upgraded to Cordova 4.3.0
– Android: No change—remains Cordova 6.1.2
What Was New in React Native for Mobile SDK 4.3
• Version Update—Mobile SDK is now built with React Native version 0.43.1.

12

CHAPTER 4 Getting Started With Mobile SDK 5.1 for
Android and iOS
In this chapter ...
•

Developer Edition or
Sandbox
Environment?

•

Development
Prerequisites for
Android and iOS

•

Sign Up for
Force.com

•

Creating a
Connected App

•

Installing Mobile SDK
for Android and iOS

•

Mobile SDK Sample
Apps

Let’s get started creating custom mobile apps! If you haven’t done so already, begin by signing up for
Force.com and installing Mobile SDK development tools.
In addition to signing up, you need a connected app definition, regardless of which development options
you choose. To install Mobile SDK for Android or iOS (hybrid and native), you use the Mobile SDK npm
packages.

13

Getting Started With Mobile SDK 5.1 for Android and iOS

Developer Edition or Sandbox Environment?

Developer Edition or Sandbox Environment?
Salesforce offers a range of environments for developers. The environment that’s best for you depends on many factors, including:
• The type of application you’re building
• Your audience
• Your company’s resources
Development environments are used strictly for developing and testing apps. These environments contain test data that isn’t
business-critical. Development can be done inside your browser or with the Force.com IDE, which is based on the Eclipse development
tool.

Types of Developer Environments
A Developer Edition environment is a free, fully featured copy of the Enterprise Edition environment, with less storage and users. Developer
Edition is a logically separate environment, ideal as your initial development environment. You can sign up for as many Developer Edition
orgs as you need. This allows you to build an application designed for any of the Salesforce production environments.
A Partner Developer Edition is a licensed version of the free Developer Edition that includes more storage, features, and licenses. Partner
Developer Editions are free to enrolled Salesforce partners.
Sandbox is a nearly identical copy of your production environment available to Professional, Enterprise, Performance, and Unlimited
Edition customers. The sandbox copy can include data, configurations, or both. You can create multiple sandboxes in your production
environments for a variety of purposes without compromising the data and applications in your production environment.

Choosing an Environment
In this book, all exercises assume you’re using a Developer Edition org. However, in reality a sandbox environment can also host your
development efforts. Here’s some information that can help you decide which environment is best for you.
• Developer Edition is ideal if you’re a:
– Partner who intends to build a commercially available Force.com app by creating a managed package for distribution through
AppExchange or Trialforce. Only Developer Edition or Partner Developer Edition environments can create managed packages.
– Salesforce customer with a Group or Personal Edition, and you don’t have access to Sandbox.
– Developer looking to explore the Force.com platform for FREE!
• Partner Developer Edition is ideal if you:
– Are developing in a team and you require a master environment to manage all the source code. In this case, each developer has
a Developer Edition environment and checks code in and out of this master repository environment.
– Expect more than two developers to log in to develop and test.
– Require a larger environment that allows more users to run robust tests against larger data sets.
• Sandbox is ideal if you:
– Are a Salesforce customer with Professional, Enterprise, Performance, Unlimited, or Force.com Edition, which includes Sandbox.
– Are developing a Force.com application specifically for your production environment.
– Aren’t planning to build a Force.com application to be distributed commercially.
– Have no intention to list on the AppExchange or distribute through Trialforce.

14

Getting Started With Mobile SDK 5.1 for Android and iOS

Development Prerequisites for Android and iOS

Development Prerequisites for Android and iOS
We recommend some background knowledge and system setup before you begin building Mobile SDK apps.
It’s helpful to have some experience with Force.com. You also need a Force.com Developer Edition organization.
Familiarity with OAuth, login and passcode flows, and Salesforce connected apps is essential to designing and debugging Mobile SDK
apps. See Authentication, Security, and Identity in Mobile Apps.
The following requirements apply to specific platforms and technologies.

iOS Requirements
• iOS 9 or later.
• Xcode version 8 or later. (We recommend the latest version.)
• CocoaPods version 1.1 or later (cocoapods.org).
• Node Package Manager (npm) version 3.10 or later.
• forceios version 5.1.
• A Salesforce Developer Edition organization with a connected app.

Android Requirements
• Java JDK 8 or later—www.oracle.com/downloads.
• Node Package Manager (npm) 3.10 or later—Must be installed for all Android development scenarios, including direct access to
the SalesforceMobileSDK-Android repo
• Android Studio 2.3 or later—developer.android.com/sdk.
• Android SDK and Android SDK Tools—Install from within Android Studio.
1. In the Android Studio menu, click Tools > Android > SDK Manager.
2. Click the SDK Platforms tab.
3. Install at least the following required SDK levels and all intervening levels:
– Minimum API: Android KitKat (API 19)
– Target API: Android Nougat (API 25)
4. Click the SDK Tools tab.
5. Install the latest Android SDK Tools version.
• Android Virtual Device (AVD)—Install from within Android Studio.
1. In the Android Studio menu, click Tools > Android > AVD Manager.
2. Click Create Virtual Device....
3. Install at least one AVD that targets Android KitKat (API 19) and above. To learn how to set up an AVD in Android Studio, follow
the instructions at developer.android.com/guide/developing/devices/managing-avds.html.

Hybrid Requirements
• All requirements listed in the preceding sections for each mobile platform that you plan to support.

15

Getting Started With Mobile SDK 5.1 for Android and iOS

Sign Up for Force.com

• Proficiency in HTML5 and JavaScript languages.
• For hybrid remote applications:
– A Salesforce organization that has Visualforce.
– A Visualforce start page.

Sign Up for Force.com
To access a wealth of tutorials, blogs, and support forums for all Salesforce developer programs, join Force.com.
1. In your browser go to https://developer.salesforce.com/signup.
2. Fill in the fields about you and your company.
3. In the Email Address field, make sure to use a public address you can easily check from a Web browser.
4. Enter a unique Username. Note that this field is also in the form of an email address, but it does not have to be the same as your
email address, and in fact, it's usually better if they aren't the same. Your username is your login and your identity on
developer.salesforce.com, and so you're often better served by choosing a username that describes the work you're
doing, such as develop@workbook.org, or that describes you, such as firstname@lastname.com.
5. Read and then select the checkbox for the Master Subscription Agreement.
6. Enter the Captcha words shown and click Submit Registration.
7. In a moment you'll receive an email with a login link. Click the link and change your password.

Creating a Connected App
To enable your mobile app to connect to the Salesforce service, you need to create a connected app. The connected app includes a
consumer key, a prerequisite to all development scenarios in this guide.

Create a Connected App
To create a connected app, you use the Salesforce app.
1. Log into your Force.com instance.
2. In Setup, enter Apps in the Quick Find box, then select Apps.
3. Under Connected Apps, click New.
4. Perform steps for Basic Information.
5. Perform steps for API (Enable OAuth Settings).
6. Click Save.
If you plan to support push notifications, see Push Notifications and Mobile SDK for additional connected app settings. You can add
these settings later if you don’t currently have the necessary information.
Note:
• The Callback URL provided for OAuth doesn’t have to be a valid URL; it only has to match what the app expects in this
field. You can use any custom prefix, such as sfdc://.
• The detail page for your connected app displays a consumer key. It’s a good idea to copy this key, as you’ll need it later.
• After you create a new connected app, wait a few minutes for the token to propagate before running your app.

16

Getting Started With Mobile SDK 5.1 for Android and iOS

Create a Connected App

Basic Information
Specify basic information about your app in this section, including the app name, logo, and contact information.
1. Enter the connected app name. This name is displayed in the App Manager and on its App Launcher tile.
Note: The connected app name must be unique for the connected apps in your org. You can reuse the name of a deleted
connected app if the connected app was created using the Spring ’14 release or later.
2. Enter the API name used when referring to your app from a program. It defaults to a version of the name without spaces. Only letters,
numbers, and underscores are allowed, so if the original app name contains any other characters, edit the default name.
3. Enter the contact email for Salesforce to use when contacting you or your support team. This address isn’t given to Salesforce admins
who install the app.
4. Enter the contact phone for Salesforce to use in case we need to contact you. This number isn’t given to Salesforce admins who
install the app.
5. Enter a logo image URL to display your logo on the App Launcher tile. It also appears on the consent page that users see when
authenticating. The URL must use HTTPS. Use a GIF, JPG, or PNG file format and a file size that’s preferably under 20 KB, but at most
100 KB. We resize the image to 128 pixels by 128 pixels, so be sure that you like how it looks. If you don’t supply a logo, Salesforce
generates one for you using the app’s initials.
• You can upload your own logo image by clicking Upload logo image. Select an image from your local file system that meets
the size requirements for the logo. When your upload is successful, the URL to the logo appears in the Logo Image URL field.
Otherwise, make sure that the logo meets the size requirements.
• You can also select a logo from the Salesforce samples by clicking Choose one of our sample logos. The logos include ones
for Salesforce apps, third-party apps, and standards bodies. Click the logo you want, and then copy and paste the URL into the
Logo Image URL field.
• You can use a logo hosted publicly on Salesforce servers by uploading an image as a document from the Documents tab. View
the image to get the URL, and then enter the URL into the Logo Image URL field.
6. Enter an icon URL to display a logo on the OAuth approval page that users see when they first use your app. Use an icon that’s 16
pixels high and wide and on a white background.
You can select an icon from the samples provided by Salesforce. Click Choose one of our sample logos. Click the icon you want,
and then copy and paste the displayed URL into the Icon URL field.
7. If you have a web page with more information about your app, provide an info URL.
8. Enter a description up to 256 characters to display on the connected app’s App Launcher tile. If you don’t supply a description, just
the name appears on the tile.
Note: The App Launcher displays the connected app’s name, description, and logo (if provided) on an App Launcher tile. Make
sure that the text is meaningful and mistake-free.

API (Enable OAuth Settings)
This section controls how your app communicates with Salesforce. Select Enable OAuth Settings to configure authentication settings.
1. Enter the callback URL (endpoint) that Salesforce calls back to your application during OAuth. It’s the OAuth redirect URI. Depending
on which OAuth flow you use, the URL is typically the one that a user’s browser is redirected to after successful authentication.
Because this URL is used for some OAuth flows to pass an access token, the URL must use secure HTTPS or a custom URI scheme. If
you enter multiple callback URLs, at run time Salesforce matches the callback URL value specified by the app with one of the values
in Callback URL. It must match one of the values to pass validation.

17

Getting Started With Mobile SDK 5.1 for Android and iOS

Create a Connected App

2. If you’re using the JWT OAuth flow, select Use Digital Signatures. If the app uses a certificate, click Choose File and select the
certificate file.
3. Add all supported OAuth scopes to Selected OAuth Scopes. These scopes refer to permissions given by the user running the connected
app. The OAuth token name is in parentheses.
Access and manage your Chatter feed (chatter_api)
Allows access to Chatter REST API resources only.
Access and manage your data (api)
Allows access to the logged-in user’s account using APIs, such as REST API and Bulk API. This value also includes chatter_api,
which allows access to Chatter REST API resources.
Access your basic information (id, profile, email, address, phone)
Allows access to the Identity URL service.
Access custom permissions (custom_permissions)
Allows access to the custom permissions in an org associated with the connected app. It shows whether the current user has
each permission enabled.
Allow access to your unique identifier (openid)
Allows access to the logged-in user’s unique identifier for OpenID Connect apps.
Full access (full)
Allows access to the logged-in user’s data, and encompasses all other scopes. full doesn’t return a refresh token. You must
explicitly request the refresh_token scope to get one.
Perform requests on your behalf at any time (refresh_token, offline_access)
Allows a refresh token to be returned if the app is eligible to receive one. This scope lets the app interact with the user’s data
while the user is offline. The refresh_token scope is synonymous with offline_access.
Provide access to custom applications (visualforce)
Allows access to Visualforce pages.
Provide access to your data via the Web (web)
Allows use of the access_token on the web. It includes visualforce, which allows access to Visualforce pages.
4. If you’re setting up OAuth for applications on devices with limited input or display capabilities, such as TVs, appliances, or command-line
applications, select Enable for Device Flow.
Note: When enabled, the value for the callback URL defaults to a placeholder unless you specify your own URL. A callback
URL isn’t used in the device authentication flow. You can specify your own callback URL as needed, such as when this same
consumer is being used for a different flow.
5. If you’re setting up OAuth for a client app that can’t keep the client secret confidential and must use the web server flow because
it can’t use the user-agent flow, deselect Require Secret for Web Server Flow. We still generate a client secret for your app but
this setting instructs the web server flow to not require the client_secret parameter in the access token request. If your app
can use the user-agent flow, we recommend user-agent as a more secure option than web server flow without the secret.
6. Control how the OAuth request handles the ID token. If the OAuth request includes the openid scope, the returned token can
include the ID token.
• To include the ID token in refresh token responses, select Include ID Token. It’s always included in access token responses.
• With the primary ID token setting enabled, configure the secondary settings that control the ID token contents in both access
and refresh token responses. Select at least one of these settings.
Include Standard Claims
Include the standard claims that contain information about the user, such as the user’s name, profile, phone_number, and
address. The OpenID Connect specifications define a set of standard claims to be returned in the ID token.

18

Getting Started With Mobile SDK 5.1 for Android and iOS

Installing Mobile SDK for Android and iOS

Include Custom Attributes
If your app has specified custom attributes, include them in the ID token.
Include Custom Permissions
If your app has specified custom permissions, include them in the ID token.
7. If you’re setting up your app to issue asset tokens for connected devices, configure the asset token settings.
• Select Enable Asset Tokens. Then specify these settings.
Token Valid for
The length of time that the asset token is valid after it’s issued.
Asset Signing Certificate
The self-signed certificate that you’ve already created for signing asset tokens.
Asset Audiences
The intended consumers of the asset token. For example, the backend service for your connected device, such as
https://your_device_backend.com.
Include Custom Attributes
If your app has specified custom attributes, include them in the asset token.
Include Custom Permissions
If your app has specified custom permissions, include them in the asset token.
• Specify the callback URL (endpoint). For example, https://your_device_backend.com/callback.
• Make sure that you add the OAuth scopes that are required for asset tokens.
– Access and manage your data (api)
– Allow access to your unique identifier (openid)
If your org had the No user approval required for users in this organization option selected on your remote access before the Spring
’12 release, users in the org where the app was created are automatically approved for the app. This option is selected to indicate the
automatic approval. For connected apps, the recommended procedure after you’ve created an app is for admins to install the app and
then set Permitted Users to Admin-approved users. If the remote access option wasn’t originally selected, the option doesn’t show
up.
SEE ALSO:
Scope Parameter Values

Installing Mobile SDK for Android and iOS
Salesforce Mobile SDK provides two installation paths.
• (Recommended) You can install the SDK in a ready-made development setup using a Node Packaged Module (npm) script.
• You can download the Mobile SDK open source code from GitHub and set up your own development environment.

Mobile SDK npm Packages
Most mobile developers want to use Mobile SDK as a “black box” and begin creating apps as quickly as possible. For this use case
Salesforce provides two npm packages: forceios for iOS, and forcedroid for Android.

19

Getting Started With Mobile SDK 5.1 for Android and iOS

Mobile SDK npm Packages

Mobile SDK npm packages provide a static snapshot of an SDK release. For iOS, the npm package installs binary modules rather than
uncompiled source code. For Android, the npm package installs a snapshot of the SDK source code rather than binaries. You use the
npm scripts not only to install Mobile SDK, but also to create template projects.
Npm packages for the Salesforce Mobile SDK reside at https://www.npmjs.org.
Note: Npm packages do not support source control, so you can’t update your installation dynamically for new releases. Instead,
you install each release separately. To upgrade to new versions of the SDK, go to the npmjs.org website and download the new
package.

Do This First: Install Node.js and npm
To use the Mobile SDK npm installers, you first install Node.js. The Node.js installer automatically installs npm.
Mobile SDK 5.1 requires the following minimum version:
• npm 3.10
1. Download the Node.js installer from www.nodejs.org.
2. Run the installer, accepting all prompts that ask for permission to install. This module installs both node.js and npm.
3. Test your installation at a command prompt by running the npm command. If you don’t see a page of command usage information,
revisit Step 2 to find out what’s missing.
Now you’re ready to download the npm scripts and install Salesforce Mobile SDK for Android and iOS.

iOS Installation
For the fastest, easiest route to iOS development, use the forceios npm package to install Salesforce Mobile SDK. We’ll install the packages
globally so that you can run them from any directory.
In Mobile SDK 4.0 and later, forceios requires CocoaPods. Apps created with forceios run in a CocoaPod-driven workspace. The CocoaPods
utility enhances debugging by making Mobile SDK source code available in your workspace. Also, with CocoaPods, updating to a new
Mobile SDK version is painless. You merely update the podfile and then run pod update in a terminal window.
1. Install CocoaPods using the Getting Started instructions at guides.cocoapods.org.
2. Install the forceios npm package. Open a terminal window and type sudo npm install -g forceios.
The npm utility installs global packages under /usr/local/lib/node_modules, and links binary modules in
/usr/local/bin. The sudo command is necessary if you lack read-write permissions in /usr/local.

SEE ALSO:
Use CocoaPods with Mobile SDK
Refreshing Mobile SDK Pods

Android Installation
For the fastest, easiest route to Android development, install the forcedroid npm package to create Salesforce Mobile SDK projects for
Android. We’ll install the packages globally so that you can run them from any directory.
• Mac OS X (or other non-Windows environments)—In a terminal window, type:
sudo npm install -g forcedroid

20

Getting Started With Mobile SDK 5.1 for Android and iOS

Mobile SDK npm Packages

The npm utility installs global packages under /usr/local/lib/node_modules, and links binary modules in
/usr/local/bin. The sudo command is necessary if you lack read-write permissions in /usr/local.
• Windows—At the Windows command prompt, type:
npm install -g forcedroid

The npm utility installs global packages in %APPDATA%\npm\node_modules, and links binaries in %APPDATA%\npm.

Uninstalling Mobile SDK npm Packages
If you need to uninstall an npm package, use the npm script.

Uninstalling the Forcedroid Package
The instructions for uninstalling the forcedroid package vary with whether you installed the package globally or locally.
If you installed the package globally, you can run the uninstall command from any folder. Be sure to use the –g option. On a
Unix-based platform such as Mac OS X, use sudo as well.
$ pwd
/Users/joeuser
$ sudo npm uninstall forcedroid -g
$

If you installed the package locally, run the uninstall command from the folder where you installed the package. For example:
cd 
npm uninstall forcedroid

If you try to uninstall a local installation from the wrong directory, you’ll get an error message similar to this:
npm WARN uninstall not installed in /Users/joeuser/node_modules:
"my_projects/my_sdk_folder/node_modules/forcedroid"

Uninstalling the Forceios Package
Instructions for uninstalling the forceios package vary with whether you installed the package globally or locally. If you installed the
package globally, you can run the uninstall command from any folder. Be sure to use sudo and the –g option.
$ pwd
/Users/joeuser
$ sudo npm uninstall forceios -g
$

To uninstall a package that you installed locally, run the uninstall command from the folder where you installed the package. For
example:
$ pwd
/Users/joeuser
cd 
npm uninstall forceios

21

Getting Started With Mobile SDK 5.1 for Android and iOS

Mobile SDK GitHub Repositories

If you try to uninstall a local installation from the wrong directory, you’ll get an error message similar to this:
npm WARN uninstall not installed in /Users/joeuser/node_modules:
"my_projects/my_sdk_folder/node_modules/forceios"

Mobile SDK GitHub Repositories
More adventurous developers can delve into the SDK, keep up with the latest changes, and possibly contribute to SDK development
through GitHub. Using GitHub allows you to monitor source code in public pre-release development branches. In this scenario, your
app includes the SDK source code, which is built along with your app.
You don’t have to sign up for GitHub to access the Mobile SDK, but it’s a good idea to join this social coding community.
https://github.com/forcedotcom
You can always find the latest Mobile SDK releases in our public repositories:
• https://github.com/forcedotcom/SalesforceMobileSDK-iOS
• https://github.com/forcedotcom/SalesforceMobileSDK-Android
Important: To submit pull requests for any Mobile SDK platform, check out the dev branch as the basis for your changes.
If you’re using GitHub only to build source code for the current release, check out the master branch.

Cloning the Mobile SDK for iOS GitHub Repository (Optional)
1. Clone the Mobile SDK for iOS repository to your local file system by issuing the following command at the OS X Terminal app: git
clone git://github.com/forcedotcom/SalesforceMobileSDK-iOS.git

Note: If you have the GitHub app for Mac OS X, click Clone in Mac. In your browser, navigate to the Mobile SDK iOS GitHub
repository: https://github.com/forcedotcom/SalesforceMobileSDK-iOS.
2. In the OS X Terminal app, change to the directory where you installed the cloned repository (SalesforceMobileSDK-iOS
by default).
3. Run the install script from the command line: ./install.sh

Cloning the Mobile SDK for Android GitHub Repository (Optional)
1. In your browser, navigate to the Mobile SDK for Android GitHub repository:
https://github.com/forcedotcom/SalesforceMobileSDK-Android.
2. Clone the repository to your local file system by issuing the following command: git clone
git://github.com/forcedotcom/SalesforceMobileSDK-Android.git

3. Open a terminal prompt or command window in the directory where you installed the cloned repository.
4. Run ./install.sh on Mac, or cscript install.vbs on Windows
Note: After you’ve run cscript install.vbs on Windows, git status returns a list of modified and deleted files.
This output is an unfortunate side effect of resolving symbolic links in the repo. Do not clean or otherwise revert these files.

Creating Android Projects with the Cloned GitHub Repository
To create native and hybrid projects with the cloned SalesforceMobileSDK-Android repository, follow the instructions in
native/README.md and hybrid/README.md files.

22

Getting Started With Mobile SDK 5.1 for Android and iOS

Mobile SDK Sample Apps

Note: Be sure to install npm before building Mobile SDK for Android.

Creating iOS Projects with the Cloned GitHub Repository
To create projects with the cloned SalesforceMobileSDK-iOS repository, follow the instructions in build.md in the
repository’s root directory.
SEE ALSO:
Do This First: Install Node.js and npm

Mobile SDK Sample Apps
Salesforce Mobile SDK includes a wealth of sample applications that demonstrate its major features. You can use the hybrid and native
samples as the basis for your own applications, or just study them for reference.

Installing the Sample Apps
In GitHub, sample apps live in the Mobile SDK repository for the target platform. For hybrid samples, you have the option of using the
Cordova command line with source code from the SalesforceMobileSDK-Shared repository.

Accessing Sample Apps From the GitHub Repositories
When you clone Mobile SDK directly from GitHub, sample files are placed in the hybrid/HybridSampleApps and
native/NativeSampleApps directories.
For Android: After cloning or updating the repository locally, run cscript install.vbs on Windows or ./install.sh
on Mac in the repository root folder. You can then build the Android samples by importing the SalesforceMobileSDK-Android project
into Android Studio. Look for the sample apps in the hybrid/HybridNativeSamples and
native/NativeHybridSamples project folders.
Important: On Windows, be sure to run Android Studio as administrator.
For iOS: After cloning or updating the repository locally, run ./install.sh in the repository root folder. You can then build the
iOS samples by opening the SalesforceMobileSDK-iOS/SalesforceMobileSDK.xcworkspace file in Xcode. Look
for the sample apps in the NativeSamples and HybridSamples workspace folders.

Building Hybrid Sample Apps With Cordova
To build hybrid sample apps using the Cordova command line, see Build Hybrid Sample Apps.

Android Sample Apps
Native
• RestExplorer demonstrates the OAuth and REST API functions of Mobile SDK. It’s also useful for investigating REST API actions from
a tablet.

23

Getting Started With Mobile SDK 5.1 for Android and iOS

Installing the Sample Apps

• SmartSyncExplorer demonstrates the power of the native SmartSync library on Android. It resides in Mobile SDK for Android under
native/NativeSampleApps/SmartSyncExplorer.

Hybrid
• AccountEditor: Demonstrates how to synchronize offline data using the smartsync.js library.
• NoteSync: Demonstrates how to use non-REST APIs to retrieve Salesforce Notes.
• SmartSyncExplorerHybrid: Demonstrates how to synchronize offline data using the SmartSync plugin.

iOS Sample Apps
Native
• RestAPIExplorer exercises all native REST API wrappers. It resides in Mobile SDK for iOS under
native/SampleApps/RestAPIExplorer.
• SmartSyncExplorer demonstrates the power of the native SmartSync library on iOS. It resides in Mobile SDK for iOS under
native/SampleApps/SmartSyncExplorer.

Hybrid
• AccountEditor: Demonstrates how to synchronize offline data using the smartsync.js library.
• NoteSync: Demonstrates how to use non-REST APIs to retrieve Salesforce Notes.
• SmartSyncExplorerHybrid: Demonstrates how to synchronize offline data using the SmartSync plugin.

Hybrid Sample Apps (Source Only)
Mobile SDK provides only the web app source code for most hybrid sample apps. You can build platform-specific versions of these apps
using the Cordova command line. To get the source code, clone the SalesforceMobileSDK-Shared GitHub repository and look in the
samples folder. To build these hybrid apps for specific mobile platforms, follow the instructions at Build Hybrid Sample Apps.
• accounteditor: Uses the SmartSync Data Framework to access Salesforce data.
• contactexplorer: Uses Cordova to retrieve local device contacts. It also uses the force.js toolkit to implement REST transactions
with the Salesforce REST API. The app uses the OAuth2 support in Salesforce SDK to obtain OAuth credentials and then propagates
those credentials to force.js by sending a javascript event.
• fileexplorer: Demonstrates the Files API.
• notesync: Uses non-REST APIs to retrieve Salesforce Notes.
• simplesyncreact:: Demonstrates a React Native app that uses the SmartSync plug-in.
• smartstoreexplorer: Lets you explore SmartStore APIs.
• smartsyncexplorer: Demonstrates using smartsync.js, rather than the SmartSync plug-in, for offline synchronization.
• userandgroupsearch: Lets you search for users in groups.
• userlist: Lists users in an organization. This is the simplest hybrid sample app.
• usersearch: Lets you search for users in an organization.
• vfconnector: Wraps a Visualforce page in a native container. This example assumes that your org has a Visualforce page called
BasicVFTest. The app first obtains OAuth login credentials using the Salesforce SDK OAuth2 support and then uses those
credentials to set appropriate webview cookies for accessing Visualforce pages.

24

CHAPTER 5 Updating Mobile SDK Apps (5.0 and Later)
In this chapter ...
•

Using Maven to
Update Mobile SDK
Libraries in Android
Apps

In Mobile SDK 5.0, native and React native apps get an easier path to future Mobile SDK upgrades. Instead
of creating an app and porting your app’s resources to it, you now update a simple configuration file
and then run a script that regenerates your app with the new SDK libraries.

Updating Native and React Native Apps
Each native and React native app directory contains a package.json file at its root level. This JSON
file contains a “dependencies” object that includes a list of name-value pairs describing Mobile SDK
source paths. You can set these values to any local or network path that points to a valid copy of the
platform’s Mobile SDK. After you’ve updated this file, perform the update by running:
• install.js for Android native, iOS native, and native Swift apps
• installandroid.js for React native apps on Android
• installios.js for React native apps on iOS
You can find the appropriate file in your app’s root folder.
For example, here’s the dependencies section of a native Android package.json file:
"dependencies": {
"salesforcemobilesdk-android":
"https://github.com/forcedotcom/SalesforceMobileSDK-Android.git"
}

This path points to the current release branch of the SalesforceMobileSDK-Android repo.
For iOS, it’s the same idea:
"dependencies": {
"salesforcemobilesdk-ios":
"https://github.com/forcedotcom/SalesforceMobileSDK-iOS.git"
}

For React native, you can set targets for both Android and iOS, as well as React native versions:
"dependencies": {
"react": "15.3.2",
"react-native": "0.35.0",
"salesforcemobilesdk-ios":
"https://github.com/forcedotcom/SalesforceMobileSDK-iOS.git",
"react-native-force":
"https://github.com/forcedotcom/SalesforceMobileSDK-ReactNative.git",
"salesforcemobilesdk-android":
"https://github.com/forcedotcom/SalesforceMobileSDK-Android.git"
}

Important: Remember that your React native version must be paired with compatible Mobile
SDK versions.

25

Updating Mobile SDK Apps (5.0 and Later)

To point to the development branch of any Mobile SDK repo—that is, the branch where the upcoming
release is being developed—append “#dev” to the URL. For example:
"dependencies": {
"salesforcemobilesdk-android":
"https://github.com/forcedotcom/SalesforceMobileSDK-Android.git#dev"
}

Example: The following steps update an Android native app.
1. From your app directory, open package.json for editing.
2. In the “dependencies” section, change the value for “salesforcemobilesdk-android” to point a
different version of the SalesforceMobileSDK-Android repo. You can point to the development
branch or a different tag of the master branch (5.x or later).
3. Run install.js for native apps, or installandroid.js for React native apps.
The steps for iOS are identical. Just replace the Android references with iOS labels.

Updating Hybrid Apps
For hybrid apps, the Mobile SDK libraries are delivered through the Mobile SDK Cordova plug-in. However,
with a major release such as 5.0, we recommend that you start with a new template app.
1. Run: forcedroid create or forceios create
2. Create the same type of hybrid project with the same name as your existing project, but in a different
folder.
3. When the script finishes, cd to your new project folder.
4. Add any third-party Cordova plug-ins that your original app used. For example, if your app uses the
Cordova status bar plug-in, type:
cordova plugin add cordova-plugin-statusbar

5. After you’ve added all your third-party plugins, remove and then re-add the Mobile SDK Cordova
plugin as follows:
cordova plugin remove com.salesforce
cordova plugin add
https://github.com/forcedotcom/SalesforceMobileSDK-CordovaPlugin
--force

6. Copy your web app resources—JavaScript, HTML5, and CSS files, and so on—from the original
project into your new project’s www/ folder. For example, on Mac OS X:
cp -RL ~/MyProjects/MyMobileSDK50Project/www/* www/

7. Run: cordova prepare
Note: For details on required changes for specific releases, see Migrating from Previous Releases.

26

Updating Mobile SDK Apps (5.0 and Later)

Using Maven to Update Mobile SDK Libraries in Android
Apps

Using Maven to Update Mobile SDK Libraries in Android Apps
Beginning with version 5.0, Mobile SDK provides native Android libraries on Bintray’s jCenter Maven repository. As a result, you can now
consume any Mobile SDK library by adding a single line to the dependencies section of your app’s build.gradle file.
To import a library with Gradle, you add a compile statement to the dependencies section of your project’s build.gradle
file. To update a library with Gradle, you simply change its version number in the compile statement to the updated version, and
then resync your libraries.

The Details
Here’s what a typical Gradle dependencies section looks like:
dependencies {
classpath 'com.android.tools.build:gradle:2.2.3'
}

A compile statement takes the form
compile '::'

For Mobile SDK libraries:
• groupID is “com.salesforce.mobilesdk”
• artifactID is “SalesforceSDK”, “SalesforceHybrid”, “SmartStore”, or “SmartSync”
• version is “x.x.x” (for example, “5.0.1”)
The compile statement imports not only the specified library, but also all its dependencies. As a result, you never have to explicitly
compile SalesforceAnalytics, for example, because every other library depends on it. It also means that you can get everything you need
with just one statement.
To import Mobile SDK 5.0.1 libraries, add one of the following lines:
• For the SalesforceSDK library:
compile 'com.salesforce.mobilesdk:SalesforceSDK:5.0.1'

• For the SmartStore library (also imports the SalesforceSDK library):
compile 'com.salesforce.mobilesdk:SmartStore:5.0.1'

• For the SmartSync library (also imports the SalesforceSDK and SmartStore libraries):
compile 'com.salesforce.mobilesdk:SmartSync:5.0.1'

• For the SalesforceHybrid library (also imports the SalesforceSDK, SmartStore, SmartSync, and Apache Cordova libraries):
compile 'com.salesforce.mobilesdk:SalesforceHybrid:5.0.1'

Note:
• The Salesforce React library is not currently available through Maven.
• Mobile SDK enforces a few coding requirements for proper initialization and configuration. To get started, see Android
Application Structure.

27

CHAPTER 6 Welcome to Mobile SDK Labs!
In this chapter ...
•

React Native for
Salesforce Mobile
SDK

•

Mobile UI Elements
with Polymer

Mobile SDK Labs is where we share information on newer technologies that we’re currently testing, or
that could become unstable because they’re rapidly evolving. Check here with each release if you’re
eager to experiment with the cutting edge in your Mobile SDK apps.

Introducing Salesforce Mobile SDK Labs
Salesforce is committed to empowering developers to create mobile apps on their own terms. We hope
to provide you with complete freedom to use the technologies that best serve your needs.
In the mobile development world, innovation moves at breakneck speeds. New tools, frameworks,
libraries, and design patterns emerge almost on a weekly basis. Some of these technologies become
mainstream—stable and secure enough for production apps—while others fade away. The Mobile SDK
team is always testing emerging technologies for use with SDK libraries, samples, and resources. Salesforce
Mobile SDK Labs gives you the opportunity to try out the third-party tools and frameworks as we’re
investigating them.
Because Mobile SDK is a community-assisted effort, we value your feedback and typically incorporate it
into our decision-making process. You can contact us at our Google+ community: SalesforceMobileSDK.
Warning: Salesforce does not officially support the apps and code in Salesforce Mobile SDK Labs.
Use these projects with caution in production apps.

28

Welcome to Mobile SDK Labs!

React Native for Salesforce Mobile SDK

React Native for Salesforce Mobile SDK
React Native is a third-party framework that lets you access native UI elements directly with JavaScript, CSS, and markup. You can combine
this technology with special Mobile SDK native modules for rapid development using native resources.
Since its inception, Mobile SDK has supported two types of mobile apps:
• Native apps provide the best user experience and performance. However, you have to use a different development technology for
each mobile platform you support.
• Hybrid apps let you share your JavaScript and CSS code across platforms, but the generic underlying WebView can compromise
the user experience.
In Mobile SDK 4.0 and later, you have a third option: React Native. React Native couples the cross-platform advantages of JavaScript
development with the platform-specific "look and feel" of a native app. At the same time, the developer experience matches the style
and simplicity of hybrid development.
• You use flexible, widely known web technologies (JavaScript, CSS, and markup) for layout and styling.
• No need to compile. You simply refresh the browser to see your changes.
• To debug, you use your favorite browser’s developer tools.
• All views are rendered natively, so your customers get the user experience of a native app.
Mobile SDK 5.1 uses React Native 0.43.1. You can find React Native 0.43.1 source code and documentation at
github.com/facebook/react-native/releases/ under the 0.43.1 tag.
Note: Although React Native is a fully supported app development option, we present it in Labs because the framework is still
rapidly evolving.

What’s New in React Native for Mobile SDK 5.1
• Version Update—Mobile SDK is now built with React Native version 0.43.1.
• SmartSync Update—Handling of field lists for “sync up” operations has changed in Mobile SDK 5.1. See SmartSync Plugin Methods.

Getting Started on Android
To get ready for React Native on Android:
1. Install the software required by React Native. See "Requirements" and "iOS Setup" under Getting Started at
facebook.github.io/react-native/docs/
2. Install the latest version of forcedroid as described in Android Installation.
To create a React Native project for Android, you use forcedroid with the React Native template. Specify react_native as the project
type. For example, using interactive forcedroid:
$ forcedroid create
Enter your application type (native, react_native, hybrid_remote, or hybrid_local):
react_native
...

Or, using forcedroid command-line parameters:
$ forcedroid create --apptype="react_native" --appname="packagetest"
--packagename="com.acme.mobileapps" --organization=”Acme Widgets, Inc.”
--outputdir="PackageTest"

29

Welcome to Mobile SDK Labs!

Mobile SDK Native Modules for React Native Apps

You’re now ready to begin developing your React Native app.

Getting Started on iOS
To get ready for React Native on iOS:
1. Install the software required by React Native. See "Requirements" and "iOS Setup" under Getting Started at
facebook.github.io/react-native/docs/
2. Install the latest version of forceios as described in iOS Installation.
To create a React Native project for iOS, you use forceios with the React Native template. Specify react_native as the project type.
For example, using interactive forceios:
$ forceios create
Enter your application type (native, native_swift, react_native, hybrid_remote,
hybrid_local): react_native
...

Or, using forceios command-line parameters:
$ forceios create --apptype="react_native" --appname="packagetest"
--packagename="com.acme.mobileapps" --organization="Acme Widgets, Inc."
--outputdir="PackageTest"

You’re now ready to begin developing your React Native app.

Using Mobile SDK Native Components with React Native
React Native apps access Mobile SDK in JavaScript through the following native bridges:
• react.force.oauth.js
• react.force.network.js
• react.force.smartstore.js
• react.force.smartsync.js
These bridges are similar to the Mobile SDK components used in hybrid apps. To use them, add the following import statement in your
JavaScript code:
import {oauth, net, smartstore, smartsync} from 'react-native-force';

React native apps built with forceios or forcedroid specify the react-native-force source path in the package.json file:
"react-native-force": "https://github.com/forcedotcom/SalesforceMobileSDK-ReactNative.git"

Note: You can’t use the force.js library with React Native.

Mobile SDK Native Modules for React Native Apps
Mobile SDK provides native modules for React Native that serve as JavaScript bridges to native Mobile SDK functionality.

OAuth
The OAuth bridge is similar to the OAuth plugin for Cordova.

30

Welcome to Mobile SDK Labs!

Mobile SDK Native Modules for React Native Apps

Usage
import {oauth} from 'react-native-force';

Methods
oauth.getAuthCredentials(success, fail);
oauth.logout();

Network
The Network bridge is similar to the force.js library for hybrid apps.
Usage
import {net} from 'react-native-force';

Methods
net.setApiVersion(version);
net.getApiVersion();
net.versions(callback, error);
net.resources(callback, error);
net.describeGlobal(callback, error);
net.metadata(objtype, callback, error);
net.describe(objtype, callback, error);
net.describeLayout(objtype, recordTypeId, callback, error);
net.create(objtype, fields, callback, error);
net.retrieve(objtype, id, fieldlist, callback, error);
net.upsert(objtype, externalIdField, externalId, fields, callback, error);
net.update(objtype, id, fields, callback, error);
net.del(objtype, id, callback, error);
net.query(soql, callback, error);
net.queryMore( url, callback, error);
net.search(sosl, callback, error);

SmartStore
The SmartStore bridge is similar to the SmartStore plugin for Cordova. Unlike the plugin, however, first arguments are not optional in
React Native.
Usage
import {smartstore} from 'react-native-force';

Methods
smartstore.buildAllQuerySpec(indexPath, order, pageSize,
selectPaths);
smartstore.navigator.smartstore.buildExactQuerySpec(
path, matchKey, pageSize, order, orderPath, selectPaths);
smartstore.navigator.smartstore.buildRangeQuerySpec(
path, beginKey, endKey, order, pageSize, orderPath, selectPaths);
smartstore.navigator.smartstore.buildLikeQuerySpec(
path, likeKey, order, pageSize, orderPath, selectPaths);
smartstore.navigator.smartstore.buildMatchQuerySpec(

31

Welcome to Mobile SDK Labs!

Mobile SDK Native Modules for React Native Apps

path, matchKey, order, pageSize, orderPath, selectPaths);
smartstore.buildSmartQuerySpec(smartSql, pageSize);
smartstore.getDatabaseSize(isGlobalStore, successCB, errorCB);
smartstore.getDatabaseSize(storeConfig, successCB, errorCB);
smartstore.registerSoup(isGlobalStore, soupName, indexSpecs,
successCB, errorCB);
smartstore.registerSoup(storeConfig, soupName, indexSpecs,
successCB, errorCB);
smartstore.removeSoup(isGlobalStore, soupName, successCB, errorCB);
smartstore.removeSoup(storeConfig, soupName, successCB, errorCB);
smartstore.getSoupIndexSpecs(isGlobalStore, soupName, successCB,
errorCB);
smartstore.getSoupIndexSpecs(storeConfig, soupName, successCB,
errorCB);
smartstore.alterSoup(isGlobalStore, soupName, indexSpecs, reIndexData,
successCB, errorCB);
smartstore.alterSoup(storeConfig, soupName, indexSpecs, reIndexData,
successCB, errorCB);smartstore.reIndexSoup(storeConfig, soupName, paths, successCB,
errorCB);
smartstore.clearSoup(isGlobalStore, soupName, successCB, errorCB);
smartstore.clearSoup(storeConfig, soupName, successCB, errorCB);
smartstore.showInspector(isGlobalStore);
smartstore.showInspector(storeConfig);
smartstore.soupExists(isGlobalStore, soupName, successCB, errorCB);
smartstore.soupExists(storeConfig, soupName, successCB, errorCB);
smartstore.querySoup(isGlobalStore, soupName, querySpec,
successCB, errorCB);
smartstore.querySoup(storeConfig, soupName, querySpec,
successCB, errorCB);
smartstore.runSmartQuery(isGlobalStore, querySpec, successCB, errorCB);
smartstore.runSmartQuery(storeConfig, querySpec, successCB, errorCB);
smartstore.retrieveSoupEntries(isGlobalStore, soupName, entryIds,
successCB, errorCB);
smartstore.retrieveSoupEntries(storeConfig, soupName, entryIds,
successCB, errorCB);
smartstore.upsertSoupEntries(isGlobalStore, soupName, entries,
successCB, errorCB);
smartstore.upsertSoupEntries(storeConfig, soupName, entries,
successCB, errorCB);
smartstore.upsertSoupEntriesWithExternalId(isGlobalStore, soupName,

32

Welcome to Mobile SDK Labs!

Mobile SDK Native Modules for React Native Apps

entries, externalIdPath, successCB, errorCB);
smartstore.upsertSoupEntriesWithExternalId(storeConfig, soupName,
entries, externalIdPath, successCB, errorCB);
smartstore.removeFromSoup(isGlobalStore, soupName, entryIds,
successCB, errorCB);
smartstore.removeFromSoup(storeConfig, soupName, entryIds,
successCB, errorCB);
smartstore.moveCursorToPageIndex(isGlobalStore, cursor, newPageIndex,
successCB, errorCB);
smartstore.moveCursorToPageIndex(storeConfig, cursor, newPageIndex,
successCB, errorCB);
smartstore.moveCursorToNextPage(isGlobalStore, cursor, successCB,
errorCB);
smartstore.moveCursorToNextPage(storeConfig, cursor, successCB,
errorCB);
smartstore.moveCursorToPreviousPage(isGlobalStore, cursor, successCB,
errorCB);
smartstore.moveCursorToPreviousPage(storeConfig, cursor, successCB,
errorCB);
smartstore.closeCursor(isGlobalStore, cursor, successCB, errorCB);
smartstore.closeCursor(storeConfig, cursor, successCB, errorCB);

SmartSync
The SmartSync bridge is similar to the SmartSync plugin for Cordova. Unlike the plugin, however, first arguments are not optional in
React Native.
Usage
import {smartsync} from 'react-native-force';

Methods
smartsync.syncDown(isGlobalStore, target, soupName, options, successCB, errorCB);
smartsync.syncDown(storeConfig, target, soupName, options, successCB, errorCB);
smartsync.reSync(isGlobalStore, syncId, successCB, errorCB);
smartsync.reSync(storeConfig, syncId, successCB, errorCB);
smartsync.syncUp(isGlobalStore, target, soupName, options, successCB, errorCB);
smartsync.syncUp(storeConfig, target, soupName, options, successCB, errorCB);
smartsync.getSyncStatus(isGlobalStore, syncId, successCB, errorCB);
smartsync.getSyncStatus(storeConfig, syncId, successCB, errorCB);

Note: Handling of field lists for “sync up” operations has changed in Mobile SDK 5.1. See SmartSync Plugin Methods for a description
of the JavaScript syncUp() method.

33

Welcome to Mobile SDK Labs!

Mobile SDK Sample App Using React Native

Mobile SDK Sample App Using React Native
The best way to get up-to-speed on React Native in Mobile SDK is to study the sample code.
Mobile SDK provides four implementations of the SmartSyncExplorer application:
• Objective-C (for iOS native)
• Java (for Android native)
• HTML/JavaScript (for hybrid on iOS and Android)
• JavaScript with React (for React Native on iOS and Android)
Implementation

iOS

Android

Native (Objective-C/Java)

1. Clone the SalesforceMobileSDK-iOS
GitHub repo.

1. Clone the SalesforceMobileSDK-Android
GitHub repo.

2. Open the SalesforceMobileSDK 2. Import the
SalesforceMobileSDK-Android project
workspace in Xcode.
in Android Studio.
3. Run the SmartSyncExplorer
application (in the NativeSamples
workspace folder).

3. Run the SmartSyncExplorer application
(in the
native/NativeSampleApps

project folder).
Hybrid (HTML/JavaScript)

1. Clone the SalesforceMobileSDK-iOS
GitHub repo.

1. Clone the SalesforceMobileSDK-Android
GitHub repo.

2. Open the SalesforceMobileSDK 2. Import the
SalesforceMobileSDK-Android project
workspace in Xcode.
in Android Studio.
3. Run the
SmartSyncExplorerHybrid

application (in the HybridSamples
workspace folder).

3. Run the “SmartSyncExplorer” application
(in the
hybrid/HybridSampleApps

project folder).
React Native (JavaScript with React)

1. Clone SmartSyncExplorerReactNative
GitHub repo.

1. Clone SmartSyncExplorerReactNative
GitHub repo.

2. In a terminal window or command
2. In a terminal window or command
prompt, run ./install.sh (on
prompt, run ./install.sh (on
Mac) or cscript install.vbs
Mac) or cscript install.vbs
(on Windows)
(on Windows)
3. cd to the app folder and run npm
start

3. cd to the app folder and run npm
start

4. Open the app/ios folder in Xcode.
5. Run the

4. Open the app/android folder in
Android Studio

SmartSyncExplorerReactNative 5. Run the
SmartSyncExplorerReactNative

application

application

34

Welcome to Mobile SDK Labs!

Mobile SDK Sample App Using React Native

A few notes about the SmartSyncExplorer for React Native
Table 1: Key Folder and Files
Path

Description

README.md

Instructions to get started

external

Dependencies (iOS/Android SDKs) They are downloaded when
you run ./install.sh (Mac) or cscript install.vbs
(Windows)

app/ios

The iOS application

app/android

The Android application

app/js

The JavaScript source files for the application

Table 2: React Components
File

Component

Description

app/js/index.android.js

Android starting script

app/js/index.ios.js

iOS starting script

app/js/App.js

SmartSyncExplorerReactNative

Root component (the entire application)
(iOS and Android)

app/js/SearchScreen.js

SearchScreen

Search screen (iOS and Android)

app/jsContactScreen.js

ContactScreen

Used for viewing and editing a single
contact (iOS and Android)

app/js/SearchBar.ios.js

SearchBar

Search bar in the search screen (iOS)

app/js/SearchBar.android.js SearchBar

Search bar in the search screen (Android)

app/js/ContactCell.js

ContactCell

A single row in the list of results in the
search screen (iOS and Android)

app/js/ContactBadge.js

ContactBadge

Colored circle with initials used in the search
results screen (iOS and Android)

app/js/Field.js

Field

A field name and value used in the contact
screen (iOS and Android)

app/js/StoreMgr.js

StoreMgr

Interacts with SmartStore and the server (via
SmartSync).

Note: Most components are shared between iOS and Android. However, some components are platform specific.

35

Welcome to Mobile SDK Labs!

Defer Login

Defer Login
Apps built with early versions of React Native for Mobile SDK always present a Salesforce login screen at startup. Sometimes, however,
these apps can benefit from deferring authentication until some later point. Beginning with React Native for Mobile SDK 4.2, you can
defer login to any logical place in your app.
Deferred login implementation is a two-step process:
1. In your iOS or Android native container app, you call Mobile SDK native methods to disable authentication at startup.
2. In your React code, you call a Mobile SDK JavaScript function at the point where you plan to initiate authentication.
Read on for the implementation details.

Step1: Disable Login at Startup
iOS (Objective-C):
By default, the Salesforce login screen appears at startup. To disable this behavior, set the authenticateAtLaunch property of
SalesforceSDKManager to NO.
1. Edit the AppDelegate.m file.
2. Change this line:
[SalesforceSDKManager sharedManager].authenticateAtLaunch = YES;

to:
[SalesforceSDKManager sharedManager].authenticateAtLaunch = NO;

Android (Java):
By default, the Salesforce login screen appears at startup. To disable this behavior, override the shouldAuthenticate() method
in your MainActivity class (or whichever class subclasses SalesforceReactActivity), as follows:
@Override
public boolean shouldAuthenticate() {
return false;
}

Step 2: Initiate Authentication in React (JavaScript)
To initiate the authentication process, call the following react.force.oauth.js function:
function authenticate(success, fail)

This function takes two arguments: a success callback function and a failure callback function. If authentication fails, your failure callback
is invoked. If authentication succeeds, your success callback is invoked with a dictionary containing the following keys:
• accessToken
• refreshToken
• clientId
• userId
• orgId
• loginUrl

36

Welcome to Mobile SDK Labs!

Upload Binary Content

• instanceUrl
• userAgent
• communityId
• communityUrl

Upload Binary Content
Beginning with Mobile SDK 4.2, you can upload binary content to any force.com endpoint that supports the binary upload feature.
The sendRequest() method in react.force.net.js has a new optional parameter named fileParams.
function sendRequest(endPoint, path, successCB, errorCB, method, payload, headerParams,
fileParams)

This parameter expects the following form:
{
: // value depends on the endpoint
{
fileMimeType:,
fileUrl:, // url to file to upload
fileName:
}
}

For example:
{
fileUpload:
{
fileMimeType:'image/jpeg',
fileUrl:localPhotoUrl,
fileName:'pic.jpg'
}
}

Example: The github.com/wmathurin/MyUserPicReactNative sample app demonstrates binary upload. This sample allows you
to change your profile picture. Binary upload of the new pic happens in the uploadPhoto() function of the UserPic.js
file.
Here’s the sample’s sendRequest() call in the getUserInfo() function:
getUserInfo(callback) {
forceClient.sendRequest('/services/data',
'/v36.0/connect/user-profiles/' + this.state.userId + '/photo',
(response) => {
callback(response);
},
(error) => {
console.log('Failed to upload user photo:' + error);
},
'POST',
{},
{'X-Connect-Bearer-Urls': 'true'},
{fileUpload:

37

Welcome to Mobile SDK Labs!

Mobile UI Elements with Polymer

{
fileUrl:localPhotoUrl,
fileMimeType:'image/jpeg',
fileName:'pic.jpg'
}
}
);
},

Mobile UI Elements with Polymer
Happy mobile app developers spend their time creating innovative functionality—not writing yet another detail page bound to a set
of APIs. The Salesforce Mobile UI Elements library wraps Force.com APIs in Google’s Polymer framework for rapid HTML5 development.
Mobile UI Elements empower HTML and JavaScript developers to build powerful Salesforce mobile apps with technologies they already
know. The open source Mobile UI Elements project provides a pre-built component library that is flexible and surprisingly easy to learn.
You can deploy a Mobile UI Elements app several ways.
• In a Visualforce page
• In a remotely hosted page on www.heroku.com or another third-party service
• As a stand-alone app, using the hybrid container provided by Salesforce Mobile SDK
Mobile UI Elements is an open-source, unsupported library based on Google’s Polymer framework. It provides fundamental building
blocks that you can combine to create fairly complex mobile apps. The component library enables any HTML developer to quickly and
easily build mobile applications without having to dig into complex mobile frameworks and design patterns.
You can find the source code for Mobile UI Elements at github.com/ForceDotComLabs/mobile-ui-elements.

Third-Party Code
The Mobile UI Elements library uses these third-party components:
• Polymer, a JavaScript library for adding new extensions and features to modern HTML5 browsers. It's built on Web Components and
is designed to use the evolving Web platform on modern browsers.
• jQuery, the JavaScript library that makes it easy to write JavaScript.
• Backbone.js, a JavaScript library providing the model–view–presenter (MVP) application design paradigm.
• Underscore.js, a “utility belt” library for JavaScript.
• Ratchet, prototype iPhone apps with simple HTML, CSS, and JavaScript components.
See github.com/ForceDotComLabs/mobile-ui-elements for a catalog of currently available elements.

force_selector_list
The force-selector-list element is an extension of core-selector element and provides a wrapper around the
force-sobject-collection element. force-selector-list acts as a base for any list UI element that needs selector
functionality. It automatically updates the selected attribute when the user taps a row.

38

Welcome to Mobile SDK Labs!

force-selector-relatedlist

Example


force-selector-relatedlist
The force-selector-relatedlist element is an extension of the core-selector element and fetches the records of
related sObjects using a force-sobject-collection element. force-selector-relatedlist is a base element for
UI elementx that render a record’s related list and also require selector functionality.

Example


force-sobject
The force-sobject element wraps the SmartSync Force.SObject in a Polymer element. The force-sobject element:
• Provides automatic management of the offline store for caching
• Provides a simpler DOM-based interface to interact with the SmartSync SObject Model
• Allows other Polymer elements to consume SmartSync easily

Example


force-sobject-collection
The force-sobject-collection element is a low-level Polymer wrapper for the SmartSync Force.SObjectCollection
object. This element:
• Automatically manages the offline data store for caching (when running inside a container)
• Provides a simple DOM-based interface for SmartSync interactions
• Allows other Polymer elements to easily consume SmartSync data

Example


force-sobject-layout
The force-sobject-layout element provides the layout information for a particular sObject record. It wraps the
describeLayout API call. The layout information is cached in memory for the existing session and is stored in SmartStore for offline
consumption. The force-sobject-layout element also provides a base definition for elements that depend on page layouts,
such as force-ui-detail and force-sobject-related.

39

Welcome to Mobile SDK Labs!

force-sobject-relatedlists

Example


force-sobject-relatedlists
The force-sobject-relatedlists element enables the rendering of related lists of a sObject record. It embeds the
force-sobject-layout element to fetch the related lists configuraton from the page layout settings. It parses the related lists
configuration for a particular sObject type. If the recordid attribute is provided, it also generates a SOQL/cache query to fetch the
related record items.

Example


force-sobject-store
The force-sobject-store element wraps the SmartSync Force.StoreCache in a Polymer element. This element:
• Automatically manages the lifecycle of the SmartStore soup for each sObject type
• Automatically creates index specs based on the lookup relationships on the sObject
• Provides a simpler DOM-based interface to interact with the SmartSync SObject model
• Allows other Polymer elements to easily consume SmartStore data
.

Example


force-ui-app
The force-ui-app element is a top-level UI element that provides the basic styling and structure for the application. This element
uses Polymer layout features to enable flexible sections on the page. This is useful in a single-page view with split view panels. All children
of the main section must specify the "content" class to apply the correct styles.

Example
When used in a Visualforce context:


force-ui-detail
The force-ui-detail element enables the rendering of a full view of a Salesforce record. This element uses the
force-sobject-layout element to fetch the page layout for the record. This element also embeds a force-sobject

40

Welcome to Mobile SDK Labs!

force-ui-list

element to allow all the CRUD operations on an sObject. To inherit the default styles, this element should always be a child of
force-ui-app.

Example


force-ui-list
The force-ui-list element enables the rendering of the list of records for any sObject. Using attributes, you can configure this
element to show specific set of records. To inherit the appropriate styles, this element should always be a child of force-ui-app.

Example


force-ui-relatedlist
The force-ui-relatedlist element extends force-selector-relatedlistelement and renders a list of related
records to an sobject record. To inherit the default styles, this element should always be a child of force-ui-app.

Example


41

CHAPTER 7 Native iOS Development
In this chapter ...

Salesforce Mobile SDK delivers libraries and sample Xcode projects for developing mobile apps on iOS.
Two important features that the iOS native SDK provides are:

•

iOS Native Quick Start

•

Native iOS
Requirements

• Automation of the OAuth2 login process, making it easy to integrate OAuth with your app.

•

Creating an iOS
Project with forceios

•

Use CocoaPods with
Mobile SDK

When you create a native app using the forceios application, your project starts as a fully functioning
app. This app allows you to connect to a Salesforce organization and run a simple query. It doesn’t do
much, but it lets you know things are working as designed.

•

Developing a Native
iOS App

•

Using iOS App
Extensions with
Mobile SDK

•

Tutorial: Creating a
Native iOS
Warehouse App

•

iOS Sample
Applications

• Access to the REST API with infrastructure classes that make that access as easy as possible.

42

Native iOS Development

iOS Native Quick Start

iOS Native Quick Start
Use the following procedure to get started quickly.
1. Make sure you meet all of the native iOS requirements.
2. Install Mobile SDK for iOS. If you prefer, you can install Mobile SDK from the Mobile SDK GitHub Repositories instead.
3. Run the template app.

Native iOS Requirements
iOS development with Mobile SDK 5.1 requires the following software.
• iOS 9 or later.
• Xcode version 8 or later. (We recommend the latest version.)
• CocoaPods version 1.1 or later (cocoapods.org).
• Node Package Manager (npm) version 3.10 or later.
• forceios version 5.1.
• A Salesforce Developer Edition organization with a connected app.
Note: As of version 4.0, Mobile SDK for iOS supports Cocoa Touch dynamic frameworks.

SEE ALSO:
iOS Installation
Use CocoaPods with Mobile SDK
Refreshing Mobile SDK Pods

Creating an iOS Project with forceios
To create an app, use forceios in a terminal window. The forceios utility gives you two ways to create your app.
• Specify the type of application you want, along with basic configuration data.
OR
• Use an existing Mobile SDK app as a template. You still provide the basic configuration data.
You can use forceios in interactive mode with command line prompts, or in scripted mode with the parameterized command line version.
Note: Be sure to install CocoaPods before using forceios. See iOS Installation.

Specifying a Project Type
The forceios create command prompts you to choose a project type. These types represent a range of architectures so that
you can use the development environment that you find most productive. Mobile SDK for iOS supports the following types:

43

Native iOS Development

Creating an iOS Project with forceios

App Type

Architecture

Language

native

Native

Objective-C

native_swift

Native

Swift

react_native

React Native

JavaScript with React markup and CSS

hybrid_local

Hybrid

JavaScript, CSS, HTML5

hybrid_remote

Hybrid with Visualforce

JavaScript, CSS, HTML5, Apex

To create a native iOS app, specify either native or native_swift.

Specifying a Template
forceios createWithTemplate is identical to forceios create except that it asks for a GitHub repo URI instead of an

app type. You set this path to point to any repo directory that contains a Mobile SDK app that can be used as a template. Your template
app can be any supported Mobile SDK app type. The force script changes the template’s identifiers and configuration to match the
values you provide for the other parameters.

Using forceios Interactively
To use forceios interactively, open a Terminal window and type forceios create or forceios createWithTemplate.
The forceios utility then prompts you for each configuration value.

Using forceios create with Command Line Arguments
If you prefer, you can specify the forceios options as command line arguments. To see usage information, type forceios without
arguments. The list of available options displays.
$ forceios
Usage:
forceios create
--apptype= (native, native_swift, react_native, hybrid_remote,
hybrid_local)
--appname=
--packagename= (e.g. com.mycompany.myapp)
--organization= (Your company's name)
--outputdir= (Leave empty for current directory)
--startpage= (The start page of your remote app.
Required for hybrid_remote only)

Using this information, type forceios create, followed by your options and values. For example, to create a native app written
in Objective-C:
$ forceios create --apptype="native" --appname="package-test"
--packagename="com.acme.mobile_apps"
--organization="Acme Widgets, Inc." --outputdir="PackageTest"

44

Native iOS Development

Creating an iOS Project with forceios

Or, to create a native app written in Swift:
$ forceios create --apptype="native_swift" --appname="package-test"
--packagename="com.acme.mobile_apps"
--organization="Acme Widgets, Inc." --outputdir="PackageTest"

Using forceios createWithTemplate with Command Line Arguments
Here’s command line usage information for forceios createWithTemplate:
forceios createWithTemplate
--templaterepouri=