Android Quick Start

Get Gimbal up and running in your Android App.

Create Your Developer Account

Go to the Gimbal Manager and create an account.

Gimbal Manager »

Create Your Android Application

The following steps will set up an application in Eclipse ready for enabling Gimbal features.

Confirm Your Environment

Make sure you:

Create a new Eclipse project

In Eclipse choose File > New > Project and search for "Android Application Project" as seen below.

Fill out your "Application Name", "Project Name", and "Package Name" fields.

Important Make sure the "Minimum Required SDK", "Target SDK", and "Compile With" fields are set to at least API 8: Android 2.2. Then click through the rest of the "New Android Application" setup wizard.

Add these jars to your project

  • Context-Core.jar
  • Context-Location.jar
  • android-logging.jar
  • spring-android-rest-template-1.0.1.RELEASE.jar
  • spring-android-core-1.0.1.RELEASE.jar

Note You will find these jars in the client-sample-mall-mart-embed/libs folder inside the Gimbal SDK zip file.

Add jars to your Android application by copy and pasting them into the libs folder of your android project.

Your project should now look similar to this:

Create Your Gimbal Application

Follow the link below to create your application in Manager.

Note This link should take you to the "Production" environment. You can check by looking in the top right part of the page and verifying that it says "Production".

Create Gimbal Application »

Fill in the fields to look something like this:

Then click Generate.

Your newly generated API key should appear under your package name.

Configure Your Application for the Gimbal SDK

In order for your application to use Gimbal API's, it has to authenticate itself by providing your API key, name, and desired capabilities. You will need to create a file called usercontext.properties at the location assets/properties. You may have to create the properties folder yourself.

You will add three lines to your file so it looks like the following:

  • Line 1 specifies your API key that you just generated. Copy and paste it into the specified spot.
  • Line 2 is the text you wish to use in your application to describe the value-added feature you are providing for your users.
  • Line 3 tells Gimbal that you will be using its geofencing capabilities (this is case-sensitive).

To allow Gimbal location to function, you need to add a few elements to your AndroidManifest.xml file.

First, you need to specify the permissions that Gimbal needs to function properly. They are shown below.

            <uses-permission android:name="android.permission.INTERNET" />
            <uses-permission android:name="android.permission.READ_PHONE_STATE" />
            <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
            <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
            <uses-permission android:name="android.permission.WAKE_LOCK" />
            <uses-permission android:name="android.permission.BATTERY_STATS" />
            <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
            <uses-permission android:name="android.permission.WRITE_SETTINGS" />
            <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
        

Then, you need to add a service and a receiver to your application. Make sure you place them inside of the <application></application> XML element. Where it says "com.companyname.applicationname" in red, replace it with your application's package name. (the package name you entered when you generated your API key)

            <service
            android:name="com.qualcommlabs.usercontext.service.GimbalService"
            android:exported="false" >
                <intent-filter>
                   <action android:name="com.companyname.applicationname.service.USER_CONTEXT_SERVICE" />
                 </intent-filter>
            </service>

            <receiver
            android:name="com.qualcommlabs.usercontext.service.UserContextServiceStartStopReceiver"
            android:enabled="true" >
                <intent-filter>
                     <action android:name="android.intent.action.BOOT_COMPLETED" />
                </intent-filter>
                <intent-filter>
                    <action android:name="android.intent.action.ACTION_SHUTDOWN" />
                </intent-filter>
            </receiver>
        

Enable Context Core Connector

Now, we will add code to your MainActivity which is located in src/com.companyname.applicationname/MainActivity.java. This file should have been generated automatically when you created the project. It will contain a few overridden methods by default. You can leave them the way they are for now.

Important We are adding the code here for the purpose of demonstrating how to quickly get an application functioning. The location of this code in your application will depend on your design and intended usage of Gimbal.

First, import the necessary files:

            import android.util.Log;

            import com.qualcommlabs.usercontext.Callback;
            import com.qualcommlabs.usercontext.ContextCoreConnector;
            import com.qualcommlabs.usercontext.ContextCoreConnectorFactory;
        

Then, in your onCreate() method obtain an instance of the ContextCoreConnector and store it in a field. At the end, we call a private helper method called checkContextConnectorStatus(). Don't worry about any errors Eclipse gives you for writing this line because we will implement the method in a few steps:

            private ContextCoreConnector contextCoreConnector;
            
            @Override
            protected void onCreate(Bundle savedInstanceState) {
                super.onCreate(savedInstanceState);
                setContentView(R.layout.activity_location);
                contextCoreConnector = ContextCoreConnectorFactory.get(this);
                checkContextConnectorStatus();
            }
        

Finally, write the checkContextConnectorStatus() method we mentioned earlier. First, it checks to see if the permission has been enabled by the user. If it has then we use other Gimbal features (Geofencing, Communication, Interest Sensing, etc). If it hasn't then we call enable(). This prompts the user to accept terms of service and enable gimbal. If enable() succeeds, we are ready to use Gimbal features. Otherwise, we log the error message:

           private void checkContextConnectorStatus() {
                if (contextCoreConnector.isPermissionEnabled()) {
                    // Gimbal is already enabled
                }
                else {
                    contextCoreConnector.enable(this, new Callback<Void>() {

                        @Override
                        public void success(Void arg0) {
                            // Gimbal is ready
                        }

                        @Override
                        public void failure(int arg0, String arg1) {
                            Log.e("failed to enable", arg1);
                        }
                    });
                }
            }

        

Run Your Application

Now, you are ready to add varioud Gimbal features. In order to launch the application make sure your phone is plugged in and in debug mode, then in Eclipse right click on your project and click Run as -> Android Application. Upon successful launch, you will be prompted to accept Gimbal terms of service.

Learn More

For additional details on how to leverage the SDK functionality, refer to the sample applications and documentation included in the zip file provided.

Detailed Gimbal Android Guide »