Getting Started in Mobile Development with Android

The Salesforce Mobile SDK for Android is an open source toolkit that provides a collection of native libraries to enable developers to rapidly build Android applications that securely connect to the Salesforce Platform. The SDK abstracts the underlying OAuth 2.0 and REST API calls needed to connect an Android application with the Salesforce Platform, allowing developers to focus on their app's functionality.

The SDK also provides a hybrid container based on the open source Apache Cordova (PhoneGap) project that enables HTML5-based applications to leverage device features like the camera and microphone. The hybrid SDK extends the core Cordova platform to provide additional libraries for key enterprise requirements such as OAuth 2.0 authentication and secure offline storage, effectively providing an enterprise-ready hybrid application container.

Select Architecture

Choose Native to develop native Android applications that can access all of the rich features and hardware on the device. Choose Hybrid to convert a web application developed using HTML5, JavaScript and CSS3 into a native Android binary. A hybrid approach combines the portability of HTML5 with access to device features like the camera and microphone.

Getting Started with Android Native

This quick start creates a native Android application using the Salesforce Mobile SDK. Using this app, users can view a list of Account records from Salesforce.

Prerequisites

  1. Java JDK 6.
  2. Apache Ant 1.8 or later.
  3. Node.js.
  4. Android SDK version 21 or later.
  5. Note: For best results, install all previous versions of the Android SDK as well as your target version.
  6. Eclipse version 3.6 or later.
  7. Android Development Tools plugin for Eclipse version 21 or later.
  8. An Android Virtual Device (AVD) that targets Platform 2.2 or above (we recommend 4.0 or above).
  9. Sign up for a free Salesforce Platform Developer Edition (DE), if you don’t already have one. This will act as your own personal test environment. You should not use this tutorial with a trial, sandbox, or production org.

Create a Connected App in Salesforce

  1. Log into your Developer Edition.
  2. Open the Setup menu by clicking [Your Name] > Setup.
  3. Create a new Connected App by going to App Setup > Create > Apps.
  4. Click the ‘New’ button in the Connected Apps list.
  5. Fill out all required fields and click ‘Save’:
    1. Connected App: MySampleApp
    2. Developer Name: MySampleApp
    3. Contact Email: Your email
    4. Callback URL: sfdc://success.
    5. Selected all available OAuth scopes
  6. From the detail page of the connect app you just created, copy the Consumer Key and Callback URL as you’ll need these later.

Install the Mobile SDK for Android

For the fastest, easiest route to Android development, install Node.js and NPM. Then use NPM to install the forcedroid package. This package installs the Salesforce Mobile SDK for Android.

  1. Download Node.js from www.nodejs.org/download.
  2. Run the downloaded installer and accept all prompts asking for permissions to install.
  3. Open a command prompt and type npm and press ENTER to make sure your installation was successful. If you don’t see a page of usage information, revisit the previous step to find out what’s missing.
  4. Install the Mobile SDK: npm install forcedroid -g
Note: With the -g option, you run npm install from any directory. In Windows environments, global packages are installed in %APPDATA%\npm\node_modules, and binaries are linked in %APPDATA%\npm. In non-Windows environments, use sudo npm install forcedroid -g. The NPM utility installs the package under /usr/local/lib/node_modules, and links binary modules in /usr/local/bin. Most users need the sudo option because they lack read-write permissions in /usr/local.

Create a Native Android Project

It's easy to create a new app by entering information on the command line.

  1. On the command line, enter forcedroid and you'll see a list of options.
  2. Now enter forcedroid create and enter the appropriate information for each prompt.

Note that you can also enter the app options right on the command line:

$ node_modules/.bin/forcedroid create --apptype="native" --appname="package-test" --targetdir="PackageTest" --packagename="com.test.my_new_app"

Run the Project Template App

  1. Before building the new application, build the SalesforceSDK project by running the following commands at the command prompt:
    cd $SALESFORCE_SDK_DIR/native/SalesforceSDK
    $ANDROID_SDK_DIR/tools/android update project -p . -t <id>
    ant clean debug

    where SALESFORCE_SDK_DIR points to your Salesforce SDK installation directory, and ANDROID_SDK_DIR points to your Android SDK directory.

    Note: The -t <id> parameter specifies API level of the target Android version. Use android.bat list targets to see the IDs for API versions installed on your system. See Native Android Requirements for supported API levels.

  2. To build the new application, type the following commands at the command prompt:
    cd your_project_directory
    $ANDROID_SDK_DIR/tools/android update project -p . -t
    ant clean debug

    where ANDROID_SDK_DIR points to your Android SDK directory.

  3. To run the application, start an emulator or plug in your device. Then, type the following command at the command prompt: ant installd
Note: You can freely ignore the warning about sub-projects.

Next Steps

  1. Watch this Dreamforce 2012 session recording on developing offline-capable hybrid and native apps with the Salesforce Mobile SDK and SmartStore.

Getting Started with Android Hybrid

This quick start creates a hybrid Android mobile application using the Salesforce Mobile SDK. A hybrid mobile architecture converts a web application developed using HTML5, JavaScript and CSS3 into a native Android binary. A hybrid approach combines the portability of HTML5 with access to device features like the camera and microphone.

Using this app, users can view a list of Account and Contact records from Salesforce as well as a list of local device contacts.

Prerequisites

  1. Java JDK 6.
  2. Apache Ant 1.8 or later.
  3. Node.js.
  4. Android SDK version 21 or later.
  5. Note: For best results, install all previous versions of the Android SDK as well as your target version.
  6. Eclipse version 3.6 or later.
  7. Android Development Tools plugin for Eclipse version 21 or later.
  8. An Android Virtual Device (AVD) that targets Platform 2.2 or above (we recommend 4.0 or above).
  9. Sign up for a free Salesforce Platform Developer Edition (DE), if you don’t already have one. This will act as your own personal test environment. You should not use this tutorial with a trial, sandbox, or production org.

Create a Connected App in Salesforce

  1. Log into your Developer Edition.
  2. Open the Setup menu by clicking [Your Name] > Setup.
  3. Create a new Connected App by going to App Setup > Create > Apps.
  4. Click the ‘New’ button in the Connected Apps list.
  5. Fill out all required fields and click ‘Save’:
    1. Connected App: MySampleApp
    2. Developer Name: MySampleApp
    3. Contact Email: Your email
    4. Callback URL: sfdc://success.
    5. Selected all available OAuth scopes
  6. From the detail page of the connect app you just created, copy the Consumer Key and Callback URL as you’ll need these later.

Install the Mobile SDK for Android

For the fastest, easiest route to Android development, install Node.js and NPM. Then use NPM to install the forcedroid package. This package installs the Salesforce Mobile SDK for Android.

  1. Download Node.js from www.nodejs.org/download.
  2. Run the downloaded installer and accept all prompts asking for permissions to install.
  3. Open a command prompt and type npm and press ENTER to make sure your installation was successful. If you don’t see a page of usage information, revisit the previous step to find out what’s missing.
  4. Install the Mobile SDK: npm install forcedroid -g
Note: With the -g option, you run npm install from any directory. In Windows environments, global packages are installed in %APPDATA%\npm\node_modules, and binaries are linked in %APPDATA%\npm. In non-Windows environments, use sudo npm install forcedroid -g. The NPM utility installs the package under /usr/local/lib/node_modules, and links binary modules in /usr/local/bin. Most users need the sudo option because they lack read-write permissions in /usr/local.

Create a Hybrid Android Project

It's easy to create a new app by entering information on the command line.

  1. On the command line, enter forcedroid and you'll see a list of options.
  2. Now enter forcedroid create and enter the appropriate information for each prompt.

When specifying the apptype, use -—apptype=”hybrid_local” for a hybrid app with all code in the local project (your HTML and JavaScript files go in ${target.dir}/assets/www/). Use -—apptype=”hybrid_remote” for a hybrid app with code in a Visualforce app on the server.

Note that you can also enter the app options right on the command line:

$ node_modules/.bin/forcedroid create --apptype="hybrid_local" --appname="package-test" --targetdir="PackageTest" --packagename="com.test.my_new_app"

Run the Project Template App

  1. To build the new application, type the following commands at the command prompt:
    cd your_project_directory
    $ANDROID_SDK_DIR/tools/android update project -p .
    <id>

    where ANDROID_SDK_DIR points to your Android SDK directory.

  2. To run the application, start an emulator or plug in your device. Then, type the following command at the command prompt: ant installd

    Note:The -t <id> parameter specifies API level of the target Android version. Use android.bat list targets to see the IDs for API versions installed on your system. See Native Android Requirements for supported API levels.

Note: You can freely ignore the warning about sub-projects.

Next Steps

  1. Take a deeper dive into creating hybrid mobile apps using the Salesforce Mobile SDK.
  2. Learn best practices for using Apache Cordova (PhoneGap) in a Visualforce page.
  3. Learn how to take a Picture and capture a signature in a hybrid app using the Salesforce Mobile SDK.
  4. Learn how to add geolocation and QR/Bar code scanning to a hybrid app using the Salesforce Mobile SDK.
  5. Watch this Dreamforce 2012 session recording on developing offline-capable hybrid and native apps with the Salesforce Mobile SDK and SmartStore.
  6. Learn how to add voice recognition to a hybrid app using the Salesforce Mobile SDK and the AT&T Toolkit for Salesforce Platform.