Mobile SDK Development Guide Salesforce 6.0(Android Native, I OS React A
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 506
Mobile SDK Development Guide
Salesforce Mobile SDK 6.0 (Android Native,
iOS Native, React Native, and Hybrid)
@salesforcedocs
Last updated: February 7, 2018
© Copyright 2000–2018 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: Introduction to Mobile Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
About Salesforce Mobile Apps . . . . . . . . . . . . . . . . . . .
Customize the Salesforce App, 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 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
What Was New in Recent Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Chapter 4: Getting Started With Mobile SDK 6.0 for Android and iOS . . . . . . . . . . . . . 16
Developer Edition or Sandbox Environment? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Development Prerequisites for Android and iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Sign Up for Lightning Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Creating a Connected App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Create a Connected App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Installing Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Do This First: Install Node.js, npm, and git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Mobile SDK npm Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
iOS Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Android Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Uninstalling Mobile SDK npm Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Mobile SDK GitHub Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Mobile SDK Sample Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Installing the Sample Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 5: Updating Mobile SDK Apps (5.0 and Later) . . . . . . . . . . . . . . . . . . . . . . . . 27
Using Maven to Update Mobile SDK Libraries in Android Apps . . . . . . . . . . . . . . . . . . . . . . 29
Chapter 6: Welcome to Mobile SDK Labs! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Mobile UI Elements with Polymer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
force_selector_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
force-selector-relatedlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
force-sobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
force-sobject-collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
force-sobject-layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Contents
force-sobject-relatedlists
force-sobject-store . . . .
force-ui-app . . . . . . . .
force-ui-detail . . . . . . .
force-ui-list . . . . . . . . .
force-ui-relatedlist . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
32
33
33
33
33
34
Chapter 7: React Native Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Creating a React Native Project with Forcereact . . . . .
Using Mobile SDK Components in React Native Apps
Mobile SDK Native Modules for React Native Apps . .
Mobile SDK Sample App Using React Native . . . . . .
Defer Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Upload Binary Content . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
36
38
38
42
44
45
Chapter 8: Native iOS Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
iOS Native Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Native iOS Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Creating an iOS Project with Forceios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Run the Xcode Project Template App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using a Custom Template to Create Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Use CocoaPods with Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Refreshing Mobile SDK Pods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Developing a Native iOS App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
About Login and Passcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
About Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Overview of Application Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
SDK Manager Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
AppDelegate Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
About View Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
RootViewController Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
About Salesforce REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Handling Authentication Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Using iOS App Extensions with Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Tutorial: Creating a Native iOS Warehouse App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Create a Native iOS App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Customize the List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Create the Detail Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
iOS Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Chapter 9: Native Android Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Android Native Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Native Android Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Creating an Android Project with Forcedroid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Contents
Using a Custom Template to Create Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Setting Up Sample Projects in Android Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Android Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Developing a Native Android App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Android Application Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Native API Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Overview of Native Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Using Passcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Resource Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Using REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Unauthenticated REST Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Deferring Login in Native Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Android Template App: Deep Dive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Tutorial: Creating a Native Android Warehouse Application . . . . . . . . . . . . . . . . . . . . . . . . 145
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Create a Native Android App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Customize the List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Create the Detail Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Android Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Chapter 10: HTML5 and Hybrid Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Using HTML5 and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
HTML5 Development Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Multi-Device Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
HTML5 Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Delivering HTML5 Content With Visualforce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Accessing Salesforce Data: Controllers vs. APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Hybrid Apps Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Creating Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
About Hybrid Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Building Hybrid Apps With Cordova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Developing Hybrid Remote Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Hybrid Sample Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Running the ContactExplorer Hybrid Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Debugging Hybrid Apps On a Mobile Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Debugging a Hybrid App On an Android Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Debugging a Hybrid App Running On an iOS Device . . . . . . . . . . . . . . . . . . . . . . . . . 193
Controlling the Status Bar in iOS 7 Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
JavaScript Files for Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Versioning and JavaScript Library Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Example: Serving the Appropriate Javascript Libraries . . . . . . . . . . . . . . . . . . . . . . . . 197
Managing Sessions in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Defer Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Contents
Chapter 11: Offline Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Using SmartStore to Securely Store Offline Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
About SmartStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Enabling SmartStore in Hybrid and Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Adding SmartStore to Existing Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Creating and Accessing User-based Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Using Global SmartStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Registering a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Using Arrays in Index Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Populating a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Retrieving Data from a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Smart SQL Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Using Full-Text Search Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Working with Query Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Inserting, Updating, and Upserting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Using External Storage for Large Soup Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Removing Soup Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Managing Soups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Managing Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Testing with the SmartStore Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Using the Mock SmartStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Using SmartSync Data Framework to Access Salesforce Objects . . . . . . . . . . . . . . . . . . . . 256
Using SmartSync Data Framework in Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Using SmartSync Data Framework in Hybrid and React Native Apps . . . . . . . . . . . . . . 296
Defining Sync Names and Sync Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Chapter 12: Files and Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Downloading Files and Managing Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Uploading Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Encryption and Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Using Files in Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Managing the Request Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Using Files in iOS Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Managing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Using Files in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Chapter 13: Push Notifications and Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
About Push Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Using Push Notifications in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Code Modifications (Hybrid) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Using Push Notifications in Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Configure a Connected App For GCM (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Code Modifications (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Contents
Using Push Notifications in iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Configure a Connected App for APNS (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Code Modifications (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Chapter 14: Authentication, Security, and Identity in Mobile Apps . . . . . . . . . . . . . . . 367
OAuth Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
OAuth 2.0 Authentication Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
OAuth 2.0 User-Agent Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
OAuth 2.0 Refresh Token Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Scope Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Using Identity URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Setting Custom Login Servers in Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Setting Custom Login Servers in iOS Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Hiding the Settings Icon in iOS Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Revoking OAuth Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Refresh Token Revocation in Android Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Connected Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
About PIN Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Portal Authentication Using OAuth 2.0 and Salesforce Sites . . . . . . . . . . . . . . . . . . . . . . . . 382
Using MDM with Salesforce Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Sample Property List Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Using Advanced Authentication in iOS Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Enabling Browser-Based Authentication in Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . 388
Chapter 15: Customizing the Salesforce Login Page . . . . . . . . . . . . . . . . . . . . . . . . . 391
Chapter 16: Using Mobile SDK Apps as Identity Providers . . . . . . . . . . . . . . . . . . . . 392
Identity Providers: Architecture, Flow, and Connected App Requirements . . . . . . . . . . . . . . 393
Android Architecture and Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Configuring an Android App to Be an Identity Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Configuring an Android App to Be an Identity Provider Client . . . . . . . . . . . . . . . . . . . . . . . 397
Configuring an iOS App to Be An Identity Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Configuring an iOS App to Be An Identity Provider Client . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Chapter 17: Using Communities With Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . 401
Communities and Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Set Up an API-Enabled Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Set Up a Permission Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Grant API Access to Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Configure the Login Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Brand Your Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Customize Login, Self-Registration, and Password Management for Your Community . . . . . . 406
Use Your Branded Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Using External Authentication With Communities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
External Authentication Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Contents
Use the Community URL Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Use the Scope Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Configure a Facebook Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Configure a Salesforce Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Configure an OpenID Connect Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . 415
Example: Configure a Community For Mobile SDK App Access . . . . . . . . . . . . . . . . . . . . . . 417
Add Permissions to a Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Create a Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Add the API User Profile To Your Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Create a New Contact and User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Test Your New Community Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Example: Configure a Community For Facebook Authentication . . . . . . . . . . . . . . . . . . . . . 420
Create a Facebook App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Define a Salesforce Auth. Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Configure Your Facebook App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Customize the Auth. Provider Apex Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Configure Your Salesforce Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Chapter 18: Multi-User Support in Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
About Multi-User Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Implementing Multi-User Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Android Native APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
iOS Native APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Hybrid APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Chapter 19: Mobile SDK Tools for Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
In-App Developer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Chapter 20: Analytics and Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Salesforce Mobile SDK Logging Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Instrumentation and Event Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Chapter 21: Migrating from Previous Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Migrate All Apps from 5.3 to 6.0 . . . . . . . . . . .
Migrating from Earlier Releases . . . . . . . . . . .
Migrate All Apps from 5.2 to 5.3 . . . . . . .
Migrate Android Apps from 5.1 to 5.2 . . . .
Migrate iOS Apps from 5.1 to 5.2 . . . . . . .
Migrate Hybrid Apps from 5.1 to 5.2 . . . . .
Migrate React Native Apps from 5.1 to 5.2 .
Migrate Android Apps from 5.0 to 5.1 . . . .
Migrate iOS Apps from 5.0 to 5.1 . . . . . . .
Migrate Hybrid Apps from 5.0 to 5.1 . . . . .
Migrate Android Apps from 4.3 to 5.0 . . .
Migrate iOS Apps from 4.3 to 5.0 . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
452
452
452
453
453
453
453
453
456
459
459
459
Contents
Migrate Hybrid Apps from 4.3 to 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Migrate Android Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Migrate iOS Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Migrate Hybrid Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Migrate Android Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Migrate iOS Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Migrate Hybrid Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Migrate Android Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Migrate iOS Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Migrate Hybrid Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Chapter 22: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
iOS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Native REST API Classes for iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Android Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Android Packages and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Android Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Files API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
FileRequests Methods (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
SFRestAPI (Files) Category—Request Methods (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Files Methods For Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
Tool and Component Supported Versions for Mobile SDK 6.0 . . . . . . . . . . . . . . . . . . . . . . 486
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
CHAPTER 1
In this chapter ...
•
About Salesforce
Mobile Apps
•
Customize the
Salesforce App, or
Create a Custom
App?
•
About This Guide
•
Sending Feedback
Introduction to Mobile Development
In the twenty-first century, 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 Platform 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
Introduction to Mobile Development
About Salesforce Mobile Apps
About Salesforce Mobile Apps
The Salesforce Platform offers two ways to build and deploy enterprise-ready mobile applications.
• The Salesforce app, available on Apple AppStore and Google Play Store, delivers the fastest way for Salesforce platform 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 Salesforce 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 the Salesforce app.
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 Framework
SmartSync Data Framework provides a simple API for synchronizing data between your offline database and the Salesforce cloud.
With SmartSync Data Framework, 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 their customers and partners.
These applications benefit from the same enterprise features and reliability as employee apps.
Native and Hybrid, iOS and Android
Mobile SDK lets you choose any technology (native, React Native, or Cordova-based hybrid apps) on iOS and Android.
Note: Currently, Lightning components do not support running in Salesforce Mobile SDK apps.
Customize the Salesforce App, or Create a Custom App?
When you’re developing mobile apps for Salesforce org users, you have options. The Salesforce app is the customizable mobile app
developed, built, and distributed by Salesforce. Custom apps are standalone iOS or Android apps built from scratch on Salesforce Mobile
SDK. Although this book deals only with Mobile SDK development, here are some differences between the Salesforce app and custom
apps.
Customizing the Salesforce App
• Has a pre-defined user interface.
• Has full access to Salesforce org data.
• You can create an integrated experience with functionality developed in the Salesforce Platform.
2
Introduction to Mobile Development
Customize the Salesforce App, or Create a Custom App?
• The Action Bar gives you a way to include your own apps/functionality.
• You can customize the Salesforce app with either point-and-click or programmatic customizations.
• Functionality can be added programmatically through Visualforce pages or Canvas apps.
• Salesforce mobile customizations or apps adhere to the Salesforce mobile 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 data from Salesforce orgs 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 Lightning Platform cloud architecture into Android and iOS apps by providing:
• Implementation of Salesforce Connected App policy.
• Salesforce org login and OAuth credentials management, including persistence and refresh capabilities.
• Secure offline storage with SmartStore.
• Syncing between the Salesforce cloud and SmartStore through SmartSync Data Framework.
• Support for Salesforce Communities.
• Wrappers for Salesforce REST APIs with implicit networking.
• Fast switching between multiple users.
• Cordova-based containers for hybrid apps.
3
Introduction to Mobile Development
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 Data Framework 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 Lightning Platform 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 Lightning Platform. 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 6.0.
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 Lightning Platform within stand-alone mobile apps.
Lightning Platform provides a straightforward and productive platform for Salesforce cloud computing.
Developers can use Lightning Platform 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 developing your app. You can choose the options that fit your development skills, device
and technology requirements, goals, and schedule.
Salesforce Mobile SDK supports several platforms for creating mobile apps:
• Native apps are specific to a given mobile platform (iOS or Android). These apps use the development tools and languages that the
respective platform supports. For example, you develop iOS apps in Xcode using Objective-C or Swift. 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. For example,
session management, secure offline storage, and access to native device features can pose problems.
• 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 accesses the device’s native capabilities and
is delivered through the app store. You can also create hybrid apps using Visualforce pages delivered through the Salesforce hybrid
container.
• React Native apps use the React Native framework from Facebook, Inc., to run JavaScript apps as native code. Rather than following
the hybrid paradigm, React Native lets you assemble the native UI building blocks with JavaScript code. This framework provides
direct access to native resources and lets you test without recompiling. In performance terms, React Native runs a close second to
pure native execution.
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. This advantage comes into play, for example, if you’re using
larges quantities of data and require a fast refresh.
• Fluid animation—Related to the fast graphics API is the ability to have fluid animation. This ability 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.
• 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 app development requires 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 required level of experience is higher than in other development scenarios. If you’re a professional developer,
however, you don’t have to be sold on the benefits of
• Proven APIs and frameworks
• Painless special effects through established components
• Maintaining all your code in one place
6
Introduction to Salesforce Mobile SDK Development
About Native, HTML5, and Hybrid Development
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 extra 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 are much easier than for
native apps. Need to make a bug fix or add features? Done and deployed for all users. Native app, on the other hand, require longer
development and testing cycles. Furthermore, customers typically have to log in to an app store to get new versions.
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 can’t 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.
Generally, hybrid apps provide the best of both HTML5 and native worlds. They’re almost as easy to develop as HTML5 apps and can
access all the functionality of native. In addition, hybrid apps can use the Mobile SDK SmartSync Data Framework feature 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. Perhaps you’re wondering whether
hybrid apps store their files on the device or on a server. Great question! The storage location depends on whether your hybrid app is
local or remote.
Local
You can package HTML and JavaScript code inside the mobile application binary, in a structure similar to a native application. You
use REST APIs and Ajax to move data back and forth between the device and the cloud.
Remote
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 native web view.
Both types of hybrid development are covered here.
React Native Apps
React Native apps use specialized scripting languages.
• JavaScript is ES2015.
• CSS is JavaScript code that closely resembles CSS syntax and is typically written inline in your JavaScript app.
7
Introduction to Salesforce Mobile SDK Development
Enough Talk; I’m Ready
• Markup is actually a special flavor of XML named JSX. Unlike HTML, which embeds JavaScript in markup, you embed JSX markup in
JavaScript.
In addition, React Native bridges provide access to standard Mobile SDK features, such as:
• SmartStore
• SmartSync Data Framework
• Salesforce login and authentication
• Salesforce REST API access.
You can even access your own native objects—in Objective-C, Swift, or Java—directly in React Native code.
Mobile Architecture Comparison
The following table shows how the various development scenarios stack up.
Native, React Native
HTML5
Hybrid
Graphics
Native APIs
HTML, Canvas, SVG
HTML, Canvas, SVG
Performance
Fastest
Fast
Moderately 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
(through Cordova plug-ins)
Geolocation
Yes
Yes
Yes
Swipe
Yes
Yes
Yes
Pinch, spread
Yes
Yes
Yes
Connectivity
Online, offline
Mostly online
Online, offline
Development skills
Objective-C, Swift, Java,
Kotlin; JavaScript (React
Native only)
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 6.0
In this chapter ...
•
What Was New in
Recent Releases
The 6.0 release brings a trove of new features that improve everything from cross-platform efficiency to
login enhancements to debugging.
How to Upgrade Your Apps
For information on any necessary code upgrades to existing Mobile SDK apps, follow the instructions at
Migrating from Previous Releases.
General Updates (Android and iOS Native Platforms)
• A new SDK framework lets you easily turn ordinary Mobile SDK apps into identity providers and their
clients. Identity providers help known users avoid reentering their Salesforce credentials every time
they log in to a Mobile SDK app. See Using Mobile SDK Apps as Identity Providers.
• Mobile SDK provides new native app templates for forcedroid and forceios that create identity
provider apps. You can use these templates with the forcedroid createWithTemplate
and forceios createWithTemplate commands. Look for these templates at
https://github.com/forcedotcom/SalesforceMobileSDK-AuthTemplates.
• Mobile SDK 6.0 adds support for a developer settings screen in debug builds. This screen displays
configuration information that is useful during the development cycle.
What’s New in Mobile SDK 6.0 for Android
Version Updates:
• Target Android SDK: Android Oreo (API 27)
• Minimum Android SDK: Lollipop (API 21)
• Android Studio: 3.0
• Gradle: 4.1
• Cordova: 7.0.0
• React Native: 0.50.4
Login Enhancements:
You can now use Chrome custom tabs for authentication instead of the system web view. See Enabling
Browser-Based Authentication in Android Apps.
Forcedroid Changes:
• The forcedroid utility no longer creates hybrid or React Native apps. Instead, install forcehybrid and
forcereact npm packages for those use cases.
• We’ve provided a new template that creates an identity provider app. Use this template with the
forcedroid createWithTemplate command. You can find these templates at
9
What's New in Mobile SDK 6.0
https://github.com/forcedotcom/SalesforceMobi SleSDK-AuthTemplates. See Using a Custom
Template to Create Apps.
What’s New in Mobile SDK 6.0 for iOS
Deprecation:
The SFAuthenticationManager class and its delegates are now deprecated for permanent
removal in Mobile SDK 7.0. In its place, use the SFUserAccountManager class for
authentication-related functionality.
Version Updates:
• iOS SDK: 11
• Minimum iOS SDK supported: 10
• Xcode: 9
• Cordova: 4.5.4
• React Native: 0.50.4
Forceios Changes:
• The forceios utility no longer creates hybrid or React Native apps. Instead, install forcehybrid and
forcereact npm packages for those use cases.
• We’ve provided a new template that creates an identity provider app. Use this template with the
forceios createWithTemplate command. You can find these templates at
https://github.com/forcedotcom/SalesforceMobi SleSDK-AuthTemplates. See Using a Custom
Template to Create Apps.
Miscellaneous Changes:
• The SalesforceSDKManager class welcomes several SDK manager cousins that handle specific
types of apps. This architecture now matches the analogous architecture in Mobile SDK for Android.
See SDK Manager Classes.
• If you’re using the SFLoginViewController class to manage the Settings icon on the login
screen, update your code to use the SFSDKLoginViewControllerConfig class instead.
Import SalesforceSDKCore/SFSDKLoginViewControllerConfig.h and change
this line:
SFLoginViewController *loginViewController =
[SFLoginViewController sharedInstance];
to this one:
SFSDKLoginViewControllerConfig *loginViewConfig =
[[SFSDKLoginViewControllerConfig
alloc] init];
See Hiding the Settings Icon in iOS Apps.
What’s New in Hybrid Apps for Mobile SDK 6.0
Version Updates:
10
What's New in Mobile SDK 6.0
• Android: 7.0.0
• iOS: 4.5.4
Forcehybrid Tool:
Mobile SDK 6.0 introduces a new npm package, forcehybrid, for creating hybrid apps. See Using
Forcehybrid.
iOS Bug Fix:
In iOS hybrid apps on previous releases, oauth.getAuthCredentials() automatically called
authenticate() if the user wasn’t already authenticated. In Mobile SDK 6.0, we’ve changed this
behavior to signal that the user isn’t authenticated rather than directly triggering authentication. This
iOS change matches the existing Android behavior.
What’s New in React Native for Mobile SDK 6.0
Forcereact Tool:
Mobile SDK 6.0 introduces a new npm package, forcereact, for creating React Native apps. See Creating
a React Native Project with Forcereact.
Version Updates:
• React Native: 0.50.4.
What’s New in SmartStore for Mobile SDK 6.0
Mobile SDK 6.0 introduces the ability to define your SmartStore schemas through configuration files
rather than code.
• To define soups for the default global store, provide a file named globalstore.json.
• To define soups for the default user store, provide a file named userstore.json.
See Registering Soups with Configuration Files.
What’s New in SmartSync Data Framework for Mobile
SDK 6.0
Beginning in Mobile SDK 6.0, you can define sync configuration files and assign names to sync
configurations. You can use sync names to run, edit, or delete a saved sync operation.
You can also define “sync down” and “sync up” operations through configuration files rather than code.
• To define sync operations for the default global store, provide a file named globalsyncs.json.
• To define sync operations for the default user store, provide a file named usersyncs.json.
See Defining Sync Names and Sync Configuration Files.
11
What's New in Mobile SDK 6.0
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.3
What Was New in Mobile SDK 5.3 for Android
• OS Version Support: Android Oreo (API 26) is now fully supported.
• Library Upgrades: For Android we've updated SQLCipher to version 3.5.7.
• Kotlin Support: We now support Kotlin in native Android apps. Accordingly, forcedroid provides a new app type: native_kotlin.
What Was New in Mobile SDK 5.3 for iOS
• Deprecations:
– CSFNetwork, CSFAction and all related network classes are deprecated for permanent removal in Mobile SDK 6.0. Instead,
use SFRestAPI and SFNetwork.
– SFLogger is deprecated for permanent removal in Mobile SDK 6.0. Instead, use SFSDKLogger.
• OS Version Support: iOS 11.0 is fully supported in Mobile SDK 5.3.
• Library Upgrades: For iOS we've updated SQLCipher to version 3.4.1.
Mobile SDK 5.2
The 5.2 release brings Mobile SDK support for recent REST API enhancements. It also includes updates for SmartSync Data Framework
in native apps. For details on updating your code, see Migrating from Previous Releases.
General Updates (Android and iOS Native Platforms)
Login Enhancements
We’ve added support for branded community login pages by adding methods for configuring the brand parameter. See Use Your
Branded Login Page.
New Logging Framework
We've added a logging framework. See Salesforce Mobile SDK Logging Framework
What Was New in Mobile SDK 5.2 for iOS
• Mobile SDK now uses SFSafariViewController instead of the Safari browser for advanced authentication. This update
provides a better user experience with no app swizzling.
• IMPORTANT! Deprecations:
– CSFNetwork, CSFAction, and all related network classes are now deprecated and will be removed in Mobile SDK 6.0.
Instead, use SFRestAPI and SFNetwork.
– SFLogger is now deprecated and will be removed in Mobile SDK 6.0. Instead, use SFSDKLogger.
What Was New in Hybrid Apps for Mobile SDK 5.2
We’ve updated our Cordova library versions as follows:
• Android: Cordova 6.2.3
• iOS: Cordova 4.4.0
What Was New in SmartSync Data Framework for Mobile SDK 5.2
12
What's New in Mobile SDK 6.0
What Was New in Recent Releases
We've added sync targets for native Android and iOS that let you sync related records up or down in a single call. See Syncing Related
Records.
Mobile SDK 5.1
General Updates (All Platforms)
In the 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!
What Was New in Mobile SDK 5.1 for Android
To keep up with recent innovations in the 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 Was New in Mobile SDK 5.1 for iOS
• To keep up with recent innovations in the 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.
– 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 Was New in Hybrid Apps for Mobile SDK 5.1
We’ve replaced our custom WKWebViewEngine plug-in with Cordova's WKWebViewEngine plug-in.
What Was New in SmartSync Data Framework for Mobile SDK 5.1
• Thanks to API refactoring, custom targets can now control SmartSync Data Framework interaction with SmartStore databases.
• 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.
What Was New in React Native for Mobile SDK 5.1
• Version Update—Mobile SDK is now built with React Native version 0.50.4.
• SmartSync Data Framework Update—Handling of field lists for “sync up” operations has changed in Mobile SDK 5.1. .
13
What's New in Mobile SDK 6.0
What Was New in Recent 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.
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.
14
What's New in Mobile SDK 6.0
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.
See the following SmartStore and SmartSync Data Framework 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 Data Framework for Mobile SDK 5.0
• SmartSync Data Framework provides a new “refresh” target that is streamlined for easily importing cloud data into cached SmartStore
records.
• SmartSync Data Framework 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 Data Framework APIs receive non-breaking changes to their prototypes. See What Was New in
Hybrid Apps for Mobile SDK 5.0 for more information.
15
CHAPTER 4 Getting Started With Mobile SDK 6.0 for
Android and iOS
In this chapter ...
•
Developer Edition or
Sandbox
Environment?
•
Development
Prerequisites for
Android and iOS
•
Sign Up for Lightning
Platform
•
Creating a
Connected App
•
Installing Mobile SDK
•
Mobile SDK Sample
Apps
Let’s get started creating custom mobile apps! If you haven’t done so already, begin by signing up for
Salesforce 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.
16
Getting Started With Mobile SDK 6.0 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 Salesforce 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 Lightning 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 Lightning Platform Edition, which includes
Sandbox.
– Are developing a Salesforce application specifically for your production environment.
– Aren’t planning to build a Salesforce application to be distributed commercially.
– Have no intention to list on the AppExchange or distribute through Trialforce.
17
Getting Started With Mobile SDK 6.0 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 Lightning Platform. 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.
Note: Have you completed the Mobile SDK Trailhead project, “Set Up Your Mobile SDK Developer Tools”? It’s the easiest route to
a complete Mobile SDK installation.
General Requirements (for All Platforms and Environments)
The following software is required for all Mobile SDK development.
• Node.js
• Npm version 3.10 or later (installed with Node.js).
• A Salesforce Developer Edition organization with a connected app.
iOS Native Requirements
• iOS 10 or later.
• Xcode version 9 or later. (We recommend the latest version.)
• CocoaPods version 1.2 or later (cocoapods.org).
• forceios version 6.0.
Android Native Requirements
• Java JDK 1.8.x or later—www.oracle.com/downloads.
• forcedroid npm package, version 6.0.
• Android Studio 3.0 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 21)
– Target API: Android Oreo (API 27)
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 21) 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.
18
Getting Started With Mobile SDK 6.0 for Android and iOS
Sign Up for Lightning Platform
Hybrid Requirements
• For each mobile platform you support, all native requirements except for forceios and forcedroid npm packages.
• Cordova CLI 7.0.0.
• Forcehybrid npm package, version 6.0.
• Proficiency in HTML5 and JavaScript languages.
• For hybrid remote applications:
– A Salesforce organization that has Visualforce.
– A Visualforce start page.
React Native Requirements
• For each mobile platform you support, all native requirements except for forceios and forcedroid npm packages.
• Forcereact npm package, version 6.0.
• Proficiency in JavaScript (ES2015).
Sign Up for Lightning Platform
To access a wealth of tutorials, blogs, and support forums for all Salesforce developer programs, join the Lightning Platform.
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
A Salesforce administrator creates connected apps on the Salesforce server. Salesforce connected apps include many settings that are
used only by other mobile offerings such as the Salesforce app. The following steps cover the settings that apply to Mobile SDK apps.
To create a connected app:
1. Log into your Lightning Platform instance.
19
Getting Started With Mobile SDK 6.0 for Android and iOS
Create a Connected App
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. If applicable, perform the optional steps for Mobile App Settings.
7. 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.
After you create your connected app, be sure to copy the consumer key and callback URL for safekeeping. You use these values in Mobile
SDK apps for OAuth configuration. To look them up later in Lightning Experience:
1. In Lightning Experience go to Setup.
2. Navigate to Apps > App Manager.
3. Select an unmanaged connected app (where App Type equals Connected).
4. Click the dropdown button at the right end of the row and select View.
Note:
• For basic Mobile SDK apps, the callback URL 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://.
• To support advanced authentication, the callback URL must be a valid endpoint using your custom URI scheme.
• For IdP use cases, the callback URL must be a valid endpoint using the HTTPS protocol.
• 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.
Basic Information
Specify basic information about your Mobile SDK app in this section.
1. Enter a connected app name and press Return. The name you enter must be unique among connected apps in your org and may
contain spaces.
Note: Salesforce automatically fills in the API Name field with a version of the name without spaces.
2. Enter a contact email.
Other basic information fields are optional and are not used by Mobile SDK.
API (Enable OAuth Settings)
1. Select Enable OAuth Settings.
2. Enter the callback URL (endpoint). Mobile SDK uses this URL to call back to your application during authentication. This value must
match the OAuth redirect URI specified in your app’s project configuration.
3. For Selected OAuth Scopes, select Access and manage your data (api), Perform requests on your behalf at any time
(refresh_token, offline_access), and Provide access to your data via the Web (web).
4. To support Mobile SDK apps that perform authentication through the device’s native browser, deselect Require Secret for Web
Server Flow.
20
Getting Started With Mobile SDK 6.0 for Android and iOS
Installing Mobile SDK
Mobile App Settings
Most settings in this section are not used by Mobile SDK. Here are the exceptions.
1. To support PIN protection, select PIN Protect.
2. To support push notifications, select Push Messaging Enabled. You can find instructions for this section at Step 2: Creating a
Connected App in the Salesforce Mobile Push Notifications Implementation Guide.
See Also
Create a Connected App in Salesforce Help.
SEE ALSO:
Scope Parameter Values
Installing Mobile SDK
Salesforce Mobile SDK provides two installation paths.
• (Recommended) Use a Node Packaged Module (npm) script to create and configure ready-to-run Mobile SDK projects.
• Download the Mobile SDK open source code from GitHub and set up your own development environment.
Do This First: Install Node.js, npm, and git
To use the Mobile SDK npm installers, you first install Node.js. The Node.js installer automatically installs npm. You also install the latest
version of the Git command line.
Mobile SDK 6.0 requires the following minimum versions:
• npm 3.10
• Git command line (latest version)
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.
4. Go to https://git-scm.com/ to download and install the latest Git package for your system.
Now you’re ready to download the Salesforce Mobile SDK npm scripts that create Android and iOS apps.
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 a set of npm packages. Each package installs a command line tool that you can use at a Terminal window or in a
Windows command prompt.
Mobile SDK command line tools 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 projects.
Mobile SDK provides the following command line tools:
21
Getting Started With Mobile SDK 6.0 for Android and iOS
iOS Preparation
forcedroid
Creates native Android projects in Java or Kotlin.
forceios
Creates native iOS projects in Objective-C or Swift.
forcehybrid
Creates a hybrid project based on Cordova with build targets for iOS, Android, or both.
forcereact
Creates a React Native project with build targets for iOS, Android, or both.
Npm packages reside at https://www.npmjs.org. We recommend installing Mobile SDK packages globally using the following command:
• On Windows:
–
npm install -g
– To install a package locally, omit -g.
• On Mac OS X:
–
sudo npm install -g
– If you have read-write permissions to /usr/local/bin/, you can omit sudo.
– To install a package locally in a user-owned directory, omit sudo and -g.
• If npm doesn’t exist on your system, install the latest release of Node.js from nodejs.org.
• 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.
iOS Preparation
Before you try to create Mobile SDK apps for iOS—native, hybrid, or React Native—install CocoaPods and the iOS native development
environment.
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.
Follow these instructions to make sure you’re fully prepared for Mobile SDK development on iOS.
• Regardless of the type of iOS app you’re developing, make sure that you’re up to speed with the iOS native requirements listed at
Native iOS Requirements.
• To install CocoaPods, use the Getting Started instructions at guides.cocoapods.org.
• To install forceios, forcehybrid, or forcereact, see Mobile SDK npm Packages.
SEE ALSO:
Use CocoaPods with Mobile SDK
Refreshing Mobile SDK Pods
22
Getting Started With Mobile SDK 6.0 for Android and iOS
Android Preparation
Android Preparation
Before you try to create Mobile SDK apps for Android—native, hybrid, or React Native—install the Android native development
environment.
Follow these instructions to make sure you’re fully prepared for Mobile SDK development on Android.
• Make sure that you’re up to speed with the requirements listed at Native Android Requirements.
• To install forcedroid, forcehybrid, or forcereact, see Mobile SDK npm Packages.
Uninstalling Mobile SDK npm Packages
If you need to uninstall an npm package, use the npm script.
Uninstall Global Installations
For global installations, run the following command from any folder:
• On Mac OS X:
sudo npm uninstall -g
Use sudo if you lack read-write permissions on the /usr/local/bin/ directory.
• On Windows:
npm uninstall -g
where is replaced by one of the following values:
• forcedroid
• forceios
• forcehybrid
• forcereact
Uninstall Local Installations
For local installations, run the following command from the folder where you installed the package:
• On Mac OS X or Windows:
npm uninstall
where is replaced by one of the following values:
• forcedroid
• forceios
• forcehybrid
• forcereact
23
Getting Started With Mobile SDK 6.0 for Android and iOS
Mobile SDK GitHub Repositories
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.
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.
24
Getting Started With Mobile SDK 6.0 for Android and iOS
Mobile SDK Sample Apps
Important: Before building Mobile SDK for Android or iOS, be sure to install npm (nodejs.org).
SEE ALSO:
Do This First: Install Node.js, npm, and git
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
For Android:
• Clone or refresh the SalesforceMobileSDK-Android GitHub repo (https://github.com/forcedotcom/SalesforceMobileSDK-Android).
• In the repo root folder, run the install script:
– Windows: cscript install.vbs
– Mac OS X: ./install.sh
• In Android Studio, import the folder that contains your local SalesforceMobileSDK-Android clone.
• Look for sample apps in the hybrid/HybridNativeSamples and native/NativeHybridSamples project folders.
Important: On Windows, be sure to run Android Studio as administrator.
For iOS:
• Clone or refresh the SalesforceMobileSDK-iOS GitHub repo (https://github.com/forcedotcom/SalesforceMobileSDK-iOS).
• Run ./install.sh in the repository root folder.
• In Xcode, open the SalesforceMobileSDK-iOS/SalesforceMobileSDK.xcworkspace file.
• 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.
25
Getting Started With Mobile SDK 6.0 for Android and iOS
Installing the Sample Apps
• SmartSyncExplorer demonstrates the power of the native SmartSync Data Framework 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 Data Framework 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 Data Framework 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 Data Framework 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 Data Framework plug-in.
• smartstoreexplorer: Lets you explore SmartStore APIs.
• smartsyncexplorer: Demonstrates using smartsync.js, rather than the SmartSync Data Framework 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.
26
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.
27
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: forcehybrid 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.
28
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 Data Framework 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 Data Framework, 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.
29
CHAPTER 6 Welcome to Mobile SDK Labs!
In this chapter ...
•
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.
30
Welcome to Mobile SDK Labs!
Mobile UI Elements with Polymer
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 Lightning Platform 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.
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.
31
Welcome to Mobile SDK Labs!
force-sobject
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 Data Framework SObject Model
• Allows other Polymer elements to consume SmartSync Data Framework 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 Data Framework interactions
• Allows other Polymer elements to easily consume data from SmartSync Data Framework
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.
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.
32
Welcome to Mobile SDK Labs!
force-sobject-store
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 Data Framework 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
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.
33
Welcome to Mobile SDK Labs!
force-ui-relatedlist
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
34
CHAPTER 7 React Native Development
In this chapter ...
•
Creating a React
Native Project with
Forcereact
•
Using Mobile SDK
Components in React
Native Apps
•
Mobile SDK Native
Modules for React
Native Apps
•
Mobile SDK Sample
App Using React
Native
•
Defer Login
•
Upload Binary
Content
React Native is a third-party framework that lets you access native UI elements directly with JavaScript,
style sheets, 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 style sheets code across platforms, but the generic
underlying web view 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, style sheets, and markup) for layout
and styling.
• No need to recompile to check your code updates. 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 6.0 uses React Native 0.50.4. You can find React Native 0.50.4 source code and documentation
at github.com/facebook/react-native/releases/ under the 0.50.4 tag.
What’s New in React Native for Mobile SDK 6.0
Forcereact Tool:
Mobile SDK 6.0 introduces a new npm package, forcereact, for creating React Native apps. See Creating
a React Native Project with Forcereact.
Version Updates:
• React Native: 0.50.4.
Getting Started
React Native requires some common Mobile SDK components and at least one native development
environment—iOS or Android. Your best bet for getting started is the React Native Trailhead module.
See you back here afterwards.
35
React Native Development
Creating a React Native Project with Forcereact
Creating a React Native Project with Forcereact
After you’ve successfully installed a native Mobile SDK environment, you can begin creating React Native apps.
To create an app, use forcereact in a terminal window or at a Windows command prompt. The forcereact 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 forcereact in interactive mode with command-line prompts, or in scripted mode with the parameterized command-line
version.
Using Forcereact Interactively
To enter application options interactively at a command prompt, type forcereact create. The forcereact utility then prompts
you for each configuration option.
Using Forcereact with Command-Line Options
If you prefer, you can specify forcereact parameters directly at the command line. To see usage information, type forcereact without
arguments. The list of available options displays:
$ forcereact
forcereact: tool for building react native mobile applications using Salesforce Mobile SDK
Usage:
# create ios/android react_native mobile application
forcereact create
--platform=Comma separated platforms (ios, android)
--appname=Application Name
--packagename=App Package Identifier (e.g. com.mycompany.myapp)
--organization=Organization Name (Your company's/organization's name)
[--outputdir=Output Directory (Leave empty for current directory)]
Using this information, type forcereact create, followed by your options and values. For example:
$ forcereact create
--platform=ios,android
--appname=CoolReact
--packagename=com.test.my_new_app
--organization="Acme Widgets, Inc."
--outputdir=CoolReact
Specifying a Template
forcereact createWithTemplate is identical to forcereact create except that it also asks for a template repo URI.
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
36
React Native Development
Creating a React Native Project with Forcereact
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.
Here’s command-line usage information for forcereact createWithTemplate:
forcereact createWithTemplate
--platform=Comma separated platforms (ios, android)
--templaterepouri=Template repo URI
--appname=Application Name
--packagename=App Package Identifier (e.g. com.mycompany.myapp)
--organization=Organization Name (Your company's/organization's name)
[--outputdir=Output Directory (Leave empty for current directory)]
For example, consider the following command-line call:
forcereact createWithTemplate
--platform=ios,android
--templaterepouri=https://github.com/forcedotcom/SmartSyncExplorerReactNative
--appname=MyReact
-—packagename=com.mycompany.react
--organization="Acme Software, Inc."
-—outputdir=""
This call creates a React Native app in the current directory that supports both iOS and Android. It uses the same source code and
resources as the SmartSyncExplorerReactNative sample app. However, this call changes the app name from “SmartSyncExplorerReactNative”
to “MyReact”.
Build and Run Your App in Android Studio
1. In a Terminal window or at Windows command prompt, change to your project’s root directory.
cd
2. Run the following command:
• On Mac OS: npm start
• On Windows: npm run-script start-windows
3. Open your project in Android Studio.
• From the Welcome screen, click Import Project (Eclipse ADT, Gradle, etc.).
OR
• From the File menu, click File > New > Import Project....
4. Browse to your /android/ directory and click OK.
Android Studio automatically builds your workspace. This process can take several minutes. When the status bar reports “Gradle
build successful”, you’re ready to run the project.
5. Click Run 'app', or press SHIFT+F10.
Android Studio launches your app in the emulator or on your connected Android device.
37
React Native Development
Using Mobile SDK Components in React Native Apps
Build and Run Your App in Xcode
1. In a Terminal window, change to your project’s root directory.
cd
2. Type npm start, then press Return.
3. In Xcode, open /ios/.xcworkspace.
4. Click Run.
Xcode launches your app in the simulator or on your connected iOS device.
How the Forcereact Script Generates New Apps
• The script downloads templates at runtime from a GitHub repo. For the forcereact create command, the script uses the
default templates in the SalesforceMobileSDK-Templates GitHub repo.
• The script uses npm to download React Native dependencies.
• The script uses git (Android) or CocoaPods (iOS) to download Mobile SDK libraries.
Using Mobile SDK Components in React Native Apps
React Native apps access the same Mobile SDK libraries as Mobile SDK native apps. For React Native, Mobile SDK provides JavaScript
components, or bridges, that execute your JavaScript code as native Mobile SDK instructions.
In React Native, you access Mobile SDK functionality through the following native bridges:
• react.force.oauth.js
• react.force.network.js
• react.force.smartstore.js
• react.force.smartsync.js
To use these bridges, add an import statement in your JavaScript code. The following example imports all four bridges.
import {oauth, net, smartstore, smartsync} from 'react-native-force';
React native apps built with forcereact 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.
38
React Native Development
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);
net.getAttachment(id, 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(
39
React Native Development
Mobile SDK Native Modules for React Native Apps
path, likeKey, order, pageSize, orderPath, selectPaths);
smartstore.navigator.smartstore.buildMatchQuerySpec(
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.registerSoupWithSpec(storeConfig, soupSpec, 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.getSoupSpec(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.alterSoupWithSpec(storeConfig, soupName, soupSpec, 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);
40
React Native Development
Mobile SDK Native Modules for React Native Apps
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,
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);
smartstore.getAllStores(storeConfig, successCB, errorCB);
smartstore.getAllGlobalStores(successCB, errorCB);
smartstore.removeStore(storeConfig, successCB, errorCB);
smartstore.removeAllGlobalStores(successCB, errorCB);
smartstore.removeAllStores(successCB, errorCB);
SmartSync Data Framework
The SmartSync Data Framework bridge is similar to the SmartSync Data Framework plugin for Cordova. Unlike the plugin, however, first
arguments are not optional in React Native.
Usage
import {smartsync} from 'react-native-force';
41
React Native Development
Mobile SDK Sample App Using React Native
Methods
smartsync.syncDown(isGlobalStore, target, soupName, options, syncName, successCB,
errorCB);
smartsync.syncDown(storeConfig, target, soupName, options, syncName, successCB, errorCB);
smartsync.reSync(isGlobalStore, syncIdOrName, successCB, errorCB);
smartsync.reSync(storeConfig, syncIdOrName, successCB, errorCB);
smartsync.cleanResyncGhosts(isGlobalStore, syncId, successCB, errorCB);
smartsync.cleanResyncGhosts(storeConfig, syncId, successCB, errorCB);
smartsync.syncUp(isGlobalStore, target, soupName, options, syncName, successCB,
errorCB);
smartsync.syncUp(storeConfig, target, soupName, options, syncName, successCB,
errorCB);
smartsync.getSyncStatus(isGlobalStore, syncIdOrName, successCB, errorCB);
smartsync.getSyncStatus(storeConfig, syncIdOrName, successCB, errorCB);
smartstore.deleteSync(isGlobalStore, syncIdOrName, successCB, errorCB);
smartstore.deleteSync(storeConfig, syncIdOrName, successCB, errorCB);
Note: Handling of field lists for “sync up” operations has changed in Mobile SDK 5.1. See SmartSync Data Framework Plugin
Methods for a description of the JavaScript syncUp() method.
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).
42
React Native Development
Mobile SDK Sample App Using React Native
Implementation
iOS
Android
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
3. cd to the app folder and run npm
start
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
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
43
React Native Development
Defer Login
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 Data Framework).
Note: Most components are shared between iOS and Android. However, some components are platform specific.
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.
44
React Native Development
Upload Binary Content
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
• 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
{
45
React Native Development
Upload Binary Content
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:
{
fileUrl:localPhotoUrl,
fileMimeType:'image/jpeg',
fileName:'pic.jpg'
}
}
);
},
46
CHAPTER 8 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.
47
Native iOS Development
iOS Native Quick Start
iOS Native Quick Start
Use the following procedure to get started quickly.
1. Make sure you meet the native iOS requirements.
2. Install nodejs (includes npm)—https://nodejs.org
3. Install the current version of CocoaPods—https://www.cocoapods.org.
4. Using npm, install forceios. (npm is automatically installed with nodejs).
sudo npm install -g forceios
5. In a Terminal window, use forceios on page 48 to create an app.
forceios create
Native iOS Requirements
The following software is required for all Mobile SDK development.
• Node.js
• Npm version 3.10 or later (installed with Node.js).
• A Salesforce Developer Edition organization with a connected app.
iOS development with Mobile SDK 6.0 also requires the following software.
• iOS 10 or later.
• Xcode version 9 or later. (We recommend the latest version.)
• CocoaPods version 1.2 or later (cocoapods.org).
• forceios version 6.0.
Note: Mobile SDK for iOS supports Cocoa Touch dynamic frameworks.
SEE ALSO:
iOS Preparation
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 script mode with command-line arguments. To see command
usage information, type forceios without arguments.
48
Native iOS Development
Creating an iOS Project with Forceios
Note: Be sure to install CocoaPods before using forceios. See iOS Preparation.
Forceios Project Types
The forceios create command requires you to specify one of the following project types:
App Type
Architecture
Language
native
Native
Objective-C
native_swift
Native
Swift
To develop a native iOS app in Objective-C, specify native.
Using forceios create Interactively
To use interactive prompts to create an app, open a Terminal window and type forceios create. For example:
$ forceios create
Enter your application type (native, native_swift): native
Enter your application name: testNative
Enter the package name for your app (com.mycompany.myapp): com.bestapps.ios
Enter your organization name (Acme, Inc.): BestApps.com
Enter output directory for your app (leave empty for the current directory): testNative
This command creates a native Objective-C iOS app named “testNative” in the testNative/ subdirectory of your current directory.
Using forceios create in Script Mode
In script mode, you can use forceios without interactive prompts. 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"
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"
Each of these calls creates a native app named “package-test” and places it in the PackageTest/ subdirectory of your current
directory.
Creating an App from a Template
The forceios createWithTemplate command is identical to forceios create except that it asks for a GitHub repo
URI instead of an app type. You set this URI 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 script changes the template’s identifiers and configuration to match
the values you provide for the other parameters.
49
Native iOS Development
Creating an iOS Project with Forceios
Here’s command-line usage information for forceios createWithTemplate:
Usage:
forceios createWithTemplate
--templaterepouri= (e.g.
https://github.com/forcedotcom/SmartSyncExplorerReactNative)]
--appname=
--packagename= (e.g. com.mycompany.myapp)
--organization= (Your company's/organization's name)
--outputdir=