To help resolve common issues that often affect mobile apps, Mobile SDK wraps hybrid apps in native containers. These containers provide seamless authentication and session management by internally managing OAuth token exchanges. However, as popular mobile app architectures evolve, this “one size fits all” approach proves to be too limiting in some cases. For example, if a mobile app uses JavaScript remoting in Visualforce, Salesforce cookies can be lost if the user lets the session expire. These cookies can be retrieved only when the user manually logs back in.
Modern versions of Mobile SDK use reactive session management. “Reactive” means that apps can participate in session management, rather than letting the container do all the work. Apps created before Mobile SDK 1.4, however, used proactive, or container controlled, session management. In the proactive scenario, some types of apps would restart when the session expired, resulting in a less than satisfactory user experience. In the reactive scenario, your app can prevent such restarts by refreshing the session token without interrupting the runtime flow.
If you’re upgrading an app from version 1.3 to any later version, you’re required to switch to reactive management. To switch to reactive management, adjust your session management settings according to your app’s architecture. This table summarizes the behaviors and recommended approaches for common architectures.
| App Architecture | Reactive Behavior in Mobile SDK 5.0 and Later | Steps for Upgrading Code |
|---|---|---|
| REST API | Refresh from JavaScript using the com.salesforce.plugin.network plug-in | No coding is required for apps that use force.js, which handles network calls natively through the com.salesforce.plugin.network plug-in. Apps that use other frameworks should also adopt the com.salesforce.plugin.network plug-in for network calls. |
| JavaScript Remoting in Visualforce | Refresh session and CSRF token from JavaScript | Catch the session timeout event, and then either reload the page or load a new iFrame. |
In Mobile SDK 5.0 and later, JQuery Mobile, which some hybrid apps use for networking, is no longer supported as a networking option.
Note
The following sections provide code examples for supported architectures.
Hybrid apps that use REST APIs are required to refresh expired access tokens before each REST call. You can meet this requirement simply by using force.js, which refreshes sessions implicitly through the com.salesforce.plugin.network plug-in. With force.js, your app doesn’t have to add refresh code.
To initiate a user session with force.js, you call force.login(). After the user logs in to an app running in the container, the network plug-in refreshes tokens as necessary when the app tries to access Salesforce resources. The following code, adapted from the ContactExplorer sample, demonstrates a typical force.login() implementation.
When the device notifies that it’s ready, call the force.login() method to post the login screen.
1/* Do login */
2force.login(
3 function () {
4 console.log("Auth succeeded");
5 // Call your app’s entry point
6 // ...
7 },
8 function (error) {
9 console.log("Auth failed: " + error);
10 },
11);Get the complete ContactExplorer sample application here: https://github.com/forcedotcom/SalesforceMobileSDK-Shared/tree/master/samples/contactexplorer
For mobile apps that use JavaScript remoting to access Visualforce pages, incorporate the session refresh code into the method parameter list. In JavaScript, use the Visualforce remote call to check the session state and adjust accordingly.
1<Controller>.<Method>(
2 <params>,
3 function(result, event) {
4 if (hasSessionExpired(event)) {
5 // Reload will try to redirect to login page
6 // Container will intercept the redirect and
7 // refresh the session before reloading the
8 // origin page
9 window.location.reload();
10 } else {
11 // Everything is OK.
12 // Go ahead and use the result.
13 // ...
14 },
15 {escape: true}
16);This example defines hasSessionExpired() as:
1function hasSessionExpired(event) {
2 return event.type == "exception" && event.message.indexOf("Logged in?") != -1;
3}Advanced use case: Reloading the entire page doesn’t always provide the best user experience. To avoid reloading the entire page, you’ll need to:
Instead of fully reloading the page as follows:
1window.location.reload();Do something like this:
1// Refresh oauth token
2cordova.require("com.salesforce.plugin.oauth").authenticate(
3 function (creds) {
4 // Reload hidden iframe that points to a blank page to
5 // to refresh Visualforce domain cookies
6 var iframe = document.getElementById("blankIframeId");
7 iframe.src = src;
8
9 // Refresh CSRF cookie
10 // Get the provider array
11 var providers = Visualforce.remoting.Manager.providers;
12 // Get the last provider in the arrays (usually only one)
13 var provider = Visualforce.remoting.last;
14 provider.refresh(function () {
15 //Retry call for a seamless user experience
16 });
17 },
18 function (error) {
19 console.log("Refresh failed");
20 },
21);We've Moved
j