Get Started with Hybrid Development

Learning Objectives

After completing this unit, you'll be able to:

• Describe two types of hybrid apps
  
• Install Mobile SDK for hybrid development.
  
• Create a Mobile SDK hybrid app with Cordova.
  
• Run your hybrid app.
  

Before You Start

Before you complete any steps in this module, make sure you complete the hands-on challenges in Set Up Your Mobile SDK Developer Tools using the same Trailhead Playground. The work you do in the hands-on challenges here builds on the work you complete in that badge.

• Set Up Your Mobile SDK Developer Tools
  

Understanding the Hybrid Development Concept

Mobile SDK offers hybrid app development as a cross-platform alternative to native apps. Hybrid apps combine the ease of HTML5 Web app development with the native power of iOS and Android. These apps run in a mobile container that parses web app code and runs it as native code. This container, which is built on Apache Cordova technology, lets developers write their code in HTML5, JavaScript, and CSS. Under the hood, hybrid apps are Cordova apps that use the Salesforce Mobile SDK plugin.

Hybrid apps fall into two categories:

• Hybrid local—Hybrid local apps are Web apps that run locally in the mobile container. These apps are developed with the force.js library and store their HTML, JavaScript, and CSS files on the user’s device.
  
• Hybrid remote—Hybrid remote apps deliver Visualforce pages through the mobile container. These apps store some or all their HTML, JavaScript, and CSS files on the Salesforce server.
  

You use the forcehybrid npm utility to create a hybrid project. You can then use the Cordova command line to add more plugins and an Android or iOS target. You can even reuse an existing Web app by simply copying that app’s source files into the new project.

Hybrid projects also include the Mobile SDK container for each target platform. The container is a native project that requires little or no configuration. It provides the runtime bridge between the web or Visualforce app and the device operating system.

Let’s get going! Make sure you’ve completed the required prerequisite badge listed at the top of this unit. Once you’re ready to move forward, you’ll create and explore a basic hybrid local app. You then explore how one of the Mobile SDK sample apps uses the force.js library and learn about hybrid remote apps. You also learn about debugging hybrid apps using Safari and Chrome debugging tools.

What About Pure HTML5 Apps?

HTML5 apps use standard web technologies—typically HTML5, JavaScript, and CSS—to deliver apps through a mobile web browser. This “write once, run anywhere” approach to mobile development creates cross-platform mobile applications that work on multiple devices. While developers can create sophisticated apps with HTML5 and JavaScript alone, some challenges remain. For example, session management, secure offline storage, and access to native device features can pose problems.

This trail doesn’t cover pure HTML5 development.

Comparison of Native and Multi-Platform Development Architectures

The following table shows how the various development scenarios stack up.

Creating a Connected App

Important:The Salesforce Mobile SDK Basics module, which includes connected app instructions, is a prerequisite to this module. You can’t complete this unit's challenge without creating a connected app.

To connect to the Salesforce service, every mobile app requires a Salesforce connected app. A connected app authorizes your app to communicate with Salesforce and securely access Salesforce APIs.

After you create and save your connected app, notice its details.

• Copy the Callback URL and Consumer Key values. You use these values to set up authentication in your app.
  
• Mobile SDK apps do not use the consumer secret, so you can ignore this value.
  

Creating a Hybrid App

Important:

If you haven't already set up the required tools for Mobile SDK, complete the Set Up Your Mobile SDK Developer Tools Trailhead module.

1. At a Terminal window or the Windows command prompt, type forcehybrid create.
   
2. Enter the following values at the prompts:
   

• Platform: One of the following: ios, android, or ios,android
  
• Application type: hybrid_local
  
• Application name: MyTrailHybridLocal
  
• Package name: com.mytrail.hybrid
  
• Organization name: MyTrail, Inc.
  
• Output directory: TrailHybridApps
  

The forcehybrid create command fails on some Windows devices. To work around this error, run cordova plugin add salesforce-mobilesdk-cordova-plugin@v11.1.0 --force. This issue will be fixed with the release of Mobile SDK 12.0.

3. Congratulations—you’ve created a hybrid local app! The script prints the project directory name to the screen when it has finished creating the project. For example: "Your application project is ready in <project directory name>." After you get a command-line message saying that your project is ready, update the new project to reflect your connected app settings.
   
4. In your project directory, open the www/bootconfig.json file in a UTF-8 compliant text editor and update the following properties:
   

• remoteAccessConsumerKey—This value is a default placeholder. In a real app, replace this value with the consumer key from your connected app.
  
• oauthRedirectURI—This value is a default placeholder. In a real app, replace this value with the callback URL from your connected app.
  

5. At the command prompt, change to the application root folder and run cordova prepare.
   

Important:After making any change in the root-level www/ folder, be sure to go to the command prompt and run cordova prepare from the application root folder. This command copies your changes to the platform-specific folders. For example:

cd ~/<your local path>/TrailHybridApps
cordova prepare

The forcehybrid utility has done its part. If you entered “android” for the platform, you now have a Cordova project with a platforms/android/ subfolder that you can open in Android Studio. If you set “Platform” to “ios”, you have a platforms/ios/ subfolder that contains an Xcode workspace. If you set “Platform” to “ios,android”, you have both an iOS workspace and an Android project.

Don’t build the project yet! You’re not quite done.

1. Return to the Terminal or Command Prompt window.
   
2. cd to your app's project directory.
   
3. (Optional—Mac only) To add a second platform “after the fact”:
   

• To add iOS support, type:
  

  cordova platform add ios@5.1.1

• To add Android support, type:
  

  cordova platform add android@8.1.0

About Cordova Plug-ins

To enhance basic functionality in hybrid apps, developers often include third-party Cordova plug-ins. In your own apps, you can include external plug-ins by calling cordova plugin add plug-in_name, followed by cordova prepare.

To add other plug-ins to a forcehybrid app that includes an Android project, remove and then readd the Salesforce plug-in afterwards. This step does not apply to iOS-only forcehybrid apps. Here’s an example:

cordova plugin add cordova-plugin-contacts
cordova plugin add cordova-plugin-statusbar
cordova plugin remove com.salesforce
cordova plugin add https://github.com/forcedotcom/SalesforceMobileSDK-CordovaPlugin --force

Important:Never call cordova plugin add for other plug-ins provided by Mobile SDK. These plug-ins are automatically included in forcehybrid projects.

Getting Support

Seeing unexpected results? Because the hybrid model has dependencies on moving parts that are beyond our control, unforeseen things can happen. Your best resource for asking questions is the Mobile SDK Trailblazer Community.

Run Your Hybrid App

Now that your app is fully configured, let’s run it in Xcode (for iOS apps) or in Android Studio (for Android apps).

Run the App on iOS

To run the app from Xcode:

1. In Xcode, select File | Open.
   
2. Navigate to the platforms/ios/ directory in your new app’s directory.
   
3. Double-click the <app name>.xcodeworkspace file.
   
4. Click the Run button in the upper left corner, or press COMMAND-R.
   

Run the App on Android

To run the app from Android Studio:

1. From the welcome screen, select Import project (Eclipse ADT, Gradle, etc.). Or, if Android Studio is already running, select File | New | Import Project.
   
2. Select <your_project_dir>/platforms/android and click OK. If you’re prompted to use the Gradle wrapper, accept the prompt.
   
3. After the build finishes, select the android target and click Run ‘android’ from either the menu or the toolbar.
   
4. Select a connected Android device or emulator.
   

After you log in to Salesforce, the app displays a list of users from your organization.

Important:If Android Studio offers to update your Gradle wrapper version, accept the offer. After the process finishes, Android Studio automatically re-imports your project.

Resources

• Cordova 3.5 documentation
• Hybrid Apps Quick Start
• HTML5 and Hybrid Development
• https://github.com/forcedotcom/SalesforceMobileSDK-Shared