Mobile SDK Development Guide Salesforce Mobile SDK 5.2 (Android Native, iOS Native, and Hybrid)

@salesforcedocs Last updated: July 20, 2017

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

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

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

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

2 2 4 4 4

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

Chapter 3: What's New in Mobile SDK 5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 What Was New in Recent Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

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

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

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

Contents

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

Chapter 7: Native iOS Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 iOS Native Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Native iOS Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Creating an iOS Project with forceios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Run the Xcode Project Template App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Using a Custom Template to Create Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Use CocoaPods with Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Refreshing Mobile SDK Pods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Developing a Native iOS App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 About Login and Passcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 About Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Overview of Application Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 SalesforceSDKManager and SalesforceSDKManagerWithSmartStore Classes . . . . . . . . . 55 AppDelegate Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 About View Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 RootViewController Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 About Salesforce REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Handling Authentication Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Using iOS App Extensions with Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Tutorial: Creating a Native iOS Warehouse App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Create a Native iOS App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Customize the List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Create the Detail Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 iOS Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

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

Contents

Using Passcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Resource Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Using REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Unauthenticated REST Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Deferring Login in Native Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Android Template App: Deep Dive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Tutorial: Creating a Native Android Warehouse Application . . . . . . . . . . . . . . . . . . . . . . . . 138 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Create a Native Android App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Customize the List Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Create the Detail Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Android Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Chapter 9: HTML5 and Hybrid Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Using HTML5 and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 HTML5 Development Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Multi-Device Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 HTML5 Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Delivering HTML5 Content With Visualforce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Accessing Salesforce Data: Controllers vs. APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Hybrid Apps Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Creating Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 About Hybrid Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Building Hybrid Apps With Cordova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Developing Hybrid Remote Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Hybrid Sample Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Running the ContactExplorer Hybrid Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Debugging Hybrid Apps On a Mobile Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Debugging a Hybrid App On an Android Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Debugging a Hybrid App Running On an iOS Device . . . . . . . . . . . . . . . . . . . . . . . . . 185 Controlling the Status Bar in iOS 7 Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 JavaScript Files for Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Versioning and JavaScript Library Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Example: Serving the Appropriate Javascript Libraries . . . . . . . . . . . . . . . . . . . . . . . . 189 Managing Sessions in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Defer Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Remove SmartStore and SmartSync From an Android Hybrid App . . . . . . . . . . . . . . . . . . . . 193

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

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

195 196 199 199

Contents

Creating and Accessing User-based Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Using Global SmartStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Registering a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Using Arrays in Index Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Populating a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Retrieving Data from a Soup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Smart SQL Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Using Full-Text Search Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Working with Query Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Inserting, Updating, and Upserting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Using External Storage for Large Soup Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Removing Soup Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Managing Soups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Managing Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Testing with the SmartStore Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Using the Mock SmartStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Using SmartSync to Access Salesforce Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Using SmartSync in Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Using SmartSync in Hybrid and React Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Chapter 11: Files and Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Downloading Files and Managing Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Uploading Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Encryption and Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Using Files in Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Managing the Request Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Using Files in iOS Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Managing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Using Files in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Chapter 12: Push Notifications and Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 About Push Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Using Push Notifications in Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Code Modifications (Hybrid) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Using Push Notifications in Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Configure a Connected App For GCM (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Code Modifications (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Using Push Notifications in iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Configure a Connected App for APNS (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Code Modifications (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Chapter 13: Authentication, Security, and Identity in Mobile Apps . . . . . . . . . . . . . . 348 OAuth Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Contents

OAuth 2.0 Authentication Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 OAuth 2.0 User-Agent Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 OAuth 2.0 Refresh Token Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Scope Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Using Identity URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 Setting Custom Login Servers in Android Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 Setting Custom Login Servers in iOS Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 Hiding the Settings Icon in iOS Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Revoking OAuth Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Refresh Token Revocation in Android Native Apps . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Connected Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 About PIN Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Portal Authentication Using OAuth 2.0 and Force.com Sites . . . . . . . . . . . . . . . . . . . . . . . . 363 Customizing the Salesforce Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Using MDM with Salesforce Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Sample Property List Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Using Advanced Authentication in iOS Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

Chapter 14: Using Communities With Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . 369 Communities and Mobile SDK Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Set Up an API-Enabled Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Set Up a Permission Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Grant API Access to Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Configure the Login Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Brand Your Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 Customize Login, Self-Registration, and Password Management for Your Community . . . . . . 374 Use Your Branded Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Using External Authentication With Communities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 External Authentication Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 Using the Community URL Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 Use the Scope Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 Configure a Facebook Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Configure a Salesforce Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 Configure an OpenID Connect Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . 383 Example: Configure a Community For Mobile SDK App Access . . . . . . . . . . . . . . . . . . . . . 385 Add Permissions to a Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 Create a Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Add the API User Profile To Your Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Create a New Contact and User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Test Your New Community Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 Example: Configure a Community For Facebook Authentication . . . . . . . . . . . . . . . . . . . . . 388 Create a Facebook App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 Define a Salesforce Auth. Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 Configure Your Facebook App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Contents

Customize the Auth. Provider Apex Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 Configure Your Salesforce Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Chapter 15: Multi-User Support in Mobile SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 About Multi-User Support . . . . . Implementing Multi-User Support Android Native APIs . . . . . iOS Native APIs . . . . . . . . . Hybrid APIs . . . . . . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

393 393 394 399 403

Chapter 16: Migrating from Previous Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Migrate Android Apps from 5.1 to 5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Migrate iOS Apps from 5.1 to 5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Migrate Hybrid Apps from 5.1 to 5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Migrate React Native Apps from 5.1 to 5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Migrating from Earlier Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Migrate Android Apps from 5.0 to 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Migrate iOS Apps from 5.0 to 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 Migrate Hybrid Apps from 5.0 to 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 Migrate Android Apps from 4.3 to 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 Migrate iOS Apps from 4.3 to 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 Migrate Hybrid Apps from 4.3 to 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 Migrate Android Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Migrate iOS Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Migrate Hybrid Apps from 4.2 to 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Migrate Android Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Migrate iOS Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Migrate Hybrid Apps from 4.1 to 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Migrate Android Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Migrate iOS Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Migrate Hybrid Apps from 4.0 to 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

Chapter 17: Analytics and Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 Salesforce Mobile SDK Logging Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Instrumentation and Event Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Chapter 18: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 iOS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Native REST API Classes for iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Android Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Android Packages and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Android Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 Files API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 FileRequests Methods (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 SFRestAPI (Files) Category—Request Methods (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . 435

Contents

Files Methods For Hybrid Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 Forceios Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Forcedroid Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

CHAPTER 1 In this chapter ... •

Introduction to Mobile Development



Customize Salesforce1, or Create a Custom App?



About This Guide



Sending Feedback

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

1

Preface

Introduction to Mobile Development

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

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

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

2

Preface

Customize Salesforce1, or Create a Custom App?

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

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

3

Preface

About This Guide

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

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

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

Version This book is current with Salesforce Mobile SDK 5.2.

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 [email protected] • Use the Feedback button at the bottom of each page in the online documentation (developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/) .

4

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

About Native, HTML5, and Hybrid Development



Enough Talk; I’m Ready

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

5

Introduction to Salesforce Mobile SDK Development

About Native, HTML5, and Hybrid Development

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

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

6

Introduction to Salesforce Mobile SDK Development

About Native, HTML5, and Hybrid Development

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

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

Hybrid Apps Hybrid apps are built using HTML5 and JavaScript wrapped inside a thin container that provides access to native platform features. For the most part, hybrid apps provide the best of both worlds, being almost as easy to develop as HTML5 apps with all the functionality of native. In addition, hybrid apps can use the Mobile SDK SmartSync 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, so you might be wondering whether hybrid apps store their files on the device or on a server? You can implement a hybrid app locally or remotely. Locally You can package HTML and JavaScript code inside the mobile application binary, in a structure similar to a native application. In this scenario you use REST APIs and Ajax to move data back and forth between the device and the cloud.

7

Introduction to Salesforce Mobile SDK Development

Enough Talk; I’m Ready

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

Mobile Architecture Comparison The following table shows how the three mobile development scenarios stack up. Native

HTML5

Hybrid

Graphics

Native APIs

HTML, Canvas, SVG

HTML, Canvas, SVG

Performance

Fastest

Fast

Fast

Look and feel

Native

Emulated

Emulated

Distribution

App store

Web

App store

Camera

Yes

Browser dependent

Yes

Notifications

Yes

No

Yes

Contacts, calendar

Yes

No

Yes

Offline storage

Secure file system

Not secure; shared SQL, Key-Value stores

Secure file system; shared SQL

Geolocation

Yes

Yes

Yes

Swipe

Yes

Yes

Yes

Pinch, spread

Yes

Yes

Yes

Connectivity

Online, offline

Mostly online

Online, offline

Development skills

Objective-C, Swift, Java

HTML5, CSS, JavaScript

HTML5, CSS, JavaScript

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

8

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

What Was New in Recent Releases

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

How to Upgrade Your Apps 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) 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’s 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’s 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’s New in SmartSync for Mobile SDK 5.2 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.

9

What's New in Mobile SDK 5.2

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.1 General Updates (All Platforms) In the Force.com REST API, SOSL search response bodies recently changed. Instead of returning an array of matching records, SOSL search now returns a dictionary. The array of matching records is in this dictionary under the key “searchRecords”. Mobile SDK 5.1 has amended all SOSL code in its libraries to handle the new response format. Important: If your application uses SOSL, be sure to update your code accordingly! What Was New in Mobile SDK 5.1 for Android To keep up with recent innovations in the Force.com REST API, Mobile SDK adds support for the following features: • If-Unmodified-Since conditional requests. • Use of “Id” as the external ID field for upserts, coupled with null for the external ID. This pattern is useful if you’re upserting multiple records with different external ID fields. • SObjectTree requests. • Batch requests. • Composite requests. All API changes occur in the RestRequest class. See RestRequest Class. What Was New in Mobile SDK 5.1 for iOS • To keep up with recent innovations in the Force.com REST API, Mobile SDK adds support for the following features: – ifUnmodifiedSinceDate conditional requests. – Use of “Id” as the external ID field for upserts, coupled with null for the external ID. This pattern is useful if you’re upserting multiple records with different external ID fields. – SObjectTree requests. – 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 for Mobile SDK 5.1 • Thanks to API refactoring, custom targets can now control SmartSync 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.43.1.

10

What's New in Mobile SDK 5.2

What Was New in Recent Releases

• SmartSync Update—Handling of field lists for “sync up” operations has changed in Mobile SDK 5.1. .

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.

11

What's New in Mobile SDK 5.2

What Was New in Recent Releases

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

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

12

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

Developer Edition or Sandbox Environment?



Development Prerequisites for Android and iOS



Sign Up for Force.com



Creating a Connected App



Installing Mobile SDK for Android and iOS



Mobile SDK Sample Apps

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

13

Getting Started With Mobile SDK 5.2 for Android and iOS

Developer Edition or Sandbox Environment?

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

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

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

14

Getting Started With Mobile SDK 5.2 for Android and iOS

Development Prerequisites for Android and iOS

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

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

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

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

15

Getting Started With Mobile SDK 5.2 for Android and iOS

Sign Up for Force.com

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

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

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

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

16

Getting Started With Mobile SDK 5.2 for Android and iOS

Create a Connected App

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

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

17

Getting Started With Mobile SDK 5.2 for Android and iOS

Create a Connected App

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

18

Getting Started With Mobile SDK 5.2 for Android and iOS

Installing Mobile SDK for Android and iOS

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

Installing Mobile SDK for Android and iOS Salesforce Mobile SDK provides two installation paths. • (Recommended) 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.

19

Getting Started With Mobile SDK 5.2 for Android and iOS

Mobile SDK npm Packages

Mobile SDK npm Packages Most mobile developers want to use Mobile SDK as a “black box” and begin creating apps as quickly as possible. For this use case Salesforce provides two npm packages: forceios for iOS, and forcedroid for Android. Mobile SDK npm packages provide a static snapshot of an SDK release. For iOS, the npm package installs binary modules rather than uncompiled source code. For Android, the npm package installs a snapshot of the SDK source code rather than binaries. You use the npm scripts not only to install Mobile SDK, but also to create template projects. Npm packages for the Salesforce Mobile SDK reside at https://www.npmjs.org. Note: Npm packages do not support source control, so you can’t update your installation dynamically for new releases. Instead, you install each release separately. To upgrade to new versions of the SDK, go to the npmjs.org website and download the new package.

Do This First: Install Node.js, 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 5.2 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.

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

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

20

Getting Started With Mobile SDK 5.2 for Android and iOS

Mobile SDK npm Packages

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

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

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

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

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

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

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

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

21

Getting Started With Mobile SDK 5.2 for Android and iOS

Mobile SDK GitHub Repositories

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

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

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

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

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

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

3. Open a terminal prompt or command window in the directory where you installed the cloned repository. 4. Run ./install.sh on Mac, or cscript install.vbs on Windows

22

Getting Started With Mobile SDK 5.2 for Android and iOS

Mobile SDK Sample Apps

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. Note: Be sure to install npm before building Mobile SDK for Android.

Creating iOS Projects with the Cloned GitHub Repository To create projects with the cloned SalesforceMobileSDK-iOS repository, follow the instructions in build.md in the repository’s root directory. SEE ALSO: Do This First: Install Node.js, 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 When you clone Mobile SDK directly from GitHub, sample files are placed in the hybrid/HybridSampleApps and native/NativeSampleApps directories. For Android: After cloning or updating the repository locally, run cscript install.vbs on Windows or ./install.sh on Mac in the repository root folder. You can then build the Android samples by importing the SalesforceMobileSDK-Android project into Android Studio. Look for the sample apps in the hybrid/HybridNativeSamples and native/NativeHybridSamples project folders. Important: On Windows, be sure to run Android Studio as administrator. For iOS: After cloning or updating the repository locally, run ./install.sh in the repository root folder. You can then build the iOS samples by opening the SalesforceMobileSDK-iOS/SalesforceMobileSDK.xcworkspace file in Xcode. Look for the sample apps in the NativeSamples and HybridSamples workspace folders.

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

23

Getting Started With Mobile SDK 5.2 for Android and iOS

Installing the 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. • SmartSyncExplorer demonstrates the power of the native SmartSync library on Android. It resides in Mobile SDK for Android under native/NativeSampleApps/SmartSyncExplorer.

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

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

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

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

24

Getting Started With Mobile SDK 5.2 for Android and iOS

Installing the Sample Apps

• 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.

25

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.

26

Updating Mobile SDK Apps (5.0 and Later)

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

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

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

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

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

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

27

Updating Mobile SDK Apps (5.0 and Later)

Using Maven to Update Mobile SDK Libraries in Android Apps

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

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

A compile statement takes the form compile '::'

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

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

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

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

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

28

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

React Native for Salesforce Mobile SDK



Mobile UI Elements with Polymer

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

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

29

Welcome to Mobile SDK Labs!

React Native for Salesforce Mobile SDK

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

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

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

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

30

Welcome to Mobile SDK Labs!

Mobile SDK Native Modules for React Native Apps

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

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

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

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

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

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

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

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

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

31

Welcome to Mobile SDK Labs!

Mobile SDK Native Modules for React Native Apps

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

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

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

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

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

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

32

Welcome to Mobile SDK Labs!

Mobile SDK Native Modules for React Native Apps

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

33

Welcome to Mobile SDK Labs!

Mobile SDK Native Modules for React Native Apps

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

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

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

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

34

Welcome to Mobile SDK Labs!

Mobile SDK Sample App Using React Native

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

iOS

Android

Native (Objective-C/Java)

1. Clone the SalesforceMobileSDK-iOS GitHub repo.

1. Clone the SalesforceMobileSDK-Android GitHub repo.

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

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

project folder). Hybrid (HTML/JavaScript)

1. Clone the SalesforceMobileSDK-iOS GitHub repo.

1. Clone the SalesforceMobileSDK-Android GitHub repo.

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

application (in the HybridSamples workspace folder).

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

project folder). React Native (JavaScript with React)

1. Clone SmartSyncExplorerReactNative GitHub repo.

1. Clone SmartSyncExplorerReactNative GitHub repo.

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

3. cd to the app folder and run npm start

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

4. Open the app/android folder in Android Studio

SmartSyncExplorerReactNative 5. Run the SmartSyncExplorerReactNative

application

application

35

Welcome to Mobile SDK Labs!

Mobile SDK Sample App Using React Native

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

Description

README.md

Instructions to get started

external

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

app/ios

The iOS application

app/android

The Android application

app/js

The JavaScript source files for the application

Table 2: React Components File

Component

Description

app/js/index.android.js

Android starting script

app/js/index.ios.js

iOS starting script

app/js/App.js

SmartSyncExplorerReactNative

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

app/js/SearchScreen.js

SearchScreen

Search screen (iOS and Android)

app/jsContactScreen.js

ContactScreen

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

app/js/SearchBar.ios.js

SearchBar

Search bar in the search screen (iOS)

app/js/SearchBar.android.js SearchBar

Search bar in the search screen (Android)

app/js/ContactCell.js

ContactCell

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

app/js/ContactBadge.js

ContactBadge

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

app/js/Field.js

Field

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

app/js/StoreMgr.js

StoreMgr

Interacts with SmartStore and the server (via SmartSync).

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

36

Welcome to Mobile SDK Labs!

Defer Login

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

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

to: [SalesforceSDKManager sharedManager].authenticateAtLaunch = NO;

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

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

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

37

Welcome to Mobile SDK Labs!

Upload Binary Content

• instanceUrl • userAgent • communityId • communityUrl

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

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

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

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

38

Welcome to Mobile SDK Labs!

Mobile UI Elements with Polymer

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

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

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

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

39

Welcome to Mobile SDK Labs!

force-selector-relatedlist

Example

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

Example

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

Example

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

Example

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

40

Welcome to Mobile SDK Labs!

force-sobject-relatedlists

Example

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

Example

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

Example

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

Example When used in a Visualforce context:

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

41

Welcome to Mobile SDK Labs!

force-ui-list

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

Example

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

Example

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

Example

42

CHAPTER 7 Native iOS Development In this chapter ...

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



iOS Native Quick Start



Native iOS Requirements

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



Creating an iOS Project with forceios



Use CocoaPods with Mobile SDK

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



Developing a Native iOS App



Using iOS App Extensions with Mobile SDK



Tutorial: Creating a Native iOS Warehouse App



iOS Sample Applications

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

43

Native iOS Development

iOS Native Quick Start

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

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

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

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

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

44

Native iOS Development

Creating an iOS Project with forceios

App Type

Architecture

Language

native_swift

Native

Swift

react_native

React Native

JavaScript with React markup and CSS

hybrid_local

Hybrid

JavaScript, CSS, HTML5

hybrid_remote

Hybrid with Visualforce

JavaScript, CSS, HTML5, Apex

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, react_native, hybrid_local, hybrid_remote): 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

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

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"

45

Native iOS Development

Creating an iOS Project with forceios

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

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

Using forceios createWithTemplate Interactively To use command line prompts to create an app, open a Terminal window and type forceios create. The forceios utility asks you for each configuration value. For example: $ forceios createWithTemplate Enter URI of repo containing template application: https://github.com/forcedotcom/SmartSyncExplorerReactNative Enter your application name: testWithTemplate 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): testWithTemplate

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