Was this helpful?

Here's how to integrate Apigee functionality into your Android application using the Apigee SDK for Android.

1. Before you begin

The following are required for using the App Services SDK for Android:

  • Apigee developer account

    Sign in or create a new account if you do not already have one. You won't need it to install the SDK, but you'll need it to create apps.

    For more about Apigee accounts, see Creating an Apigee Account.

    After you've signed up, you'll see that you have a sandbox application to experiment with. For more information about that, see Using a Sandbox Application.

  • Android Developer Tools (ADT)

    If you're new to developing for Android, you'll need the following:

2. Download the Apigee SDK for Android

Download the Apigee SDK for Android and expand the ZIP file.

When you expand the ZIP file, you should see the following structure:

Contribution.txt
README.md
LICENSE.txt
/lib
/new-project-template
/samples
/source

What's included

The SDK includes the following:

File or Directory Description
/lib .jar of the SDK to include in the build path of your project.
/new-project-template A simple template project that already integrates SDK files needed to build apps that support Apigee features.
/samples Sample apps that you can run to explore Apigee features.
/source Source code for the SDK.

3. Integrate the SDK into your project

You can integrate Apigee features into your app by including the SDK in your project.  You can do one of the following:

If you've already got an Android project, you can integrate the Apigee SDK into your project as you normally would:

Add apigee-android-<version>.jar to your class path by doing the following:

Android 4.0 (or later) projects

Copy the jar file into the /libs folder in your project.

Android 3.0 (or earlier) projects

  1. In the Eclipse Package Explorer, select your application's project folder.
  2. Click the File > Properties menu.
  3. In the Java Build Path section, click the Libraries tab, click Add External JARs.
  4. Browse to apigee-android-<version>.jar, then click Open.
  5. Order the apigee-android-<version>.jar at the top of the class path:
    1. In the Eclipse Package Explorer, select your application's project folder.
    2. Click the File > Properties menu.
    3. In the properties dialog, in the Java Build Path section, click the Order and Export tab.
    4. IMPORTANT: Select the checkbox for apigee-android-<version>.jar, then click the Top button.

Applications using Ant

If you are using Ant to build your application, you must also copy apigee-android-<version>.jar to the /libs folder in your application.

If you don't have a project yet, you can begin by using the project template included with the SDK. The template includes support for SDK features.

  • Locate the project template in the expanded SDK. It should be at the following location:
    <sdk_root>/new-project-template

4. Update permissions in AndroidManifest.xml

Add the following Internet permissions to your application's AndroidManifest.xml file if they have not already been added. Note that with the exception of INTERNET, enabling all other permissions are optional.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

5. Initialize the SDK

To initialize the App Services SDK, you must instantiate the ApigeeClient class. There are multiple ways to handle this step, but we recommend that you do the following:

  1. Subclass the Application class, and add an instance variable for the ApigeeClient to it, along with getter and setter methods.
    public class YourApplication extends Application
    {
            
            private ApigeeClient apigeeClient;
            
            public YourApplication()
            {
                    this.apigeeClient = null;
            }
            
            public ApigeeClient getApigeeClient()
            {
                    return this.apigeeClient;
            }
            
            public void setApigeeClient(ApigeeClient apigeeClient)
            {
                    this.apigeeClient = apigeeClient;
            }
    }			
    		
  2. Declare the Application subclass in your AndroidManifest.xml. For example:
    <application>
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:name=".YourApplication"
    	…
    </application>			
    		
  3. Instantiate the ApigeeClient class in the onCreate method of your first Activity class:
    import com.apigee.sdk.ApigeeClient;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);		
    	
    	String ORGNAME = "your-org";
    	String APPNAME = "your-app";
    	
    	ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME,this.getBaseContext());
    
    	// hold onto the ApigeeClient instance in our application object.
    	YourApplication yourApp = (YourApplication) getApplication;
    	yourApp.setApigeeClient(apigeeClient);			
    }
    		

    This will make the instance of ApigeeClient available to your Application class.

6. Import additional SDK classes

The following classes will enable you to call common SDK methods:

import com.apigee.sdk.data.client.DataClient; //App Services data methods
import com.apigee.sdk.apm.android.MonitoringClient; //App Monitoring methods
import com.apigee.sdk.data.client.callbacks.ApiResponseCallback; //API response handling
import com.apigee.sdk.data.client.response.ApiResponse; //API response object

7. Verify SDK installation

Once initialized, App Services will also automatically instantiate the MonitoringClient class and begin logging usage, crash and error metrics for your app.

To verify that the SDK has been properly initialized, run your app, then go to 'Monitoring' > 'App Usage' in the App Services admin portal to verify that data is being sent.

It may take up to two minutes for data to appear in the admin portal after you run your app.

Installation complete! Try these next steps

  • Call additional SDK methods in your code

    The DataClient and MonitoringClient classes are also automatically instantiated for you, and accessible with the following accessors:

    • DataClient dataClient = apigeeClient.getDataClient();

      Use this object to access the data methods of the App Services SDK, including those for push notifications, data store, and geolocation.

    • MonitoringClient monitoringClient = apigeeClient.getMonitoringClient();

      Use this object to access the app configuration and monitoring methods of the App Services SDK, including advanced logging, and A/B testing.

  • Add App Services features to your app

    With App Services you can quickly add valuable features to your mobile or web app, including push notifications, a custom data store, geolocation and more. Check out these links to get started with a few of our most popular features:

    • Push notifications: Send offers, alerts and other messages directly to user devices to dramatically increase engagement. With App Services you can send 10 million push notification per month for free!
    • App Monitoring: When you initialize the App Services SDK, a suite of valuable, customizable application monitoring features are automatically enabled that deliver the data you need to fine tune performance, analyze issues, and improve user experience.
    • Geolocation: Target users or return result sets based on user location to keep your app highly-relevant.
    • Data storage: Store all your application data on our high-availability infrastructure, and never worry about dealing with a database ever again.
    • User management and authentication: Every app needs users. Use App Services to easily implement user registration, as well as OAuth 2.0-compliant login and authentication.
  • Check out the sample apps

    The SDK includes samples that illustrate Apigee features. You'll find the samples in the following location in your SDK download:

    apigee-android-sdk-<version>
    	...
    	/samples
    		

    The samples include the following:

    Sample Description
    books An app for storing a list of books that shows Apigee database operations such as reading, creating, and deleting.
    messagee An app for sending and receiving messages that shows Apigee database operations (reading, creating).
    push An app that uses the push feature to send notifications to the devices of users who have subscribed for them.

 

Comments

What level of the Android API is _required_ for building an app that
uses the SDK jar file? I want to know how far back I can go and not just
build against the latest version of Android -- unless your SDK requires use
of the very latest Android API level. -- Please clarify. Thanks.

When I installed the apigee on Android, I found that:

// hold onto the ApigeeClient instance in our application object.
yourApp = (YourApplication) getApplication;

This sentence is wrong because we could not use "getApplication" method when it is a null instance. There will be a "Java" runtime exception.

The correct way I try is to create a new instance and use "setApplication" method without "get" method.

Here is my code:
// hold onto the ApigeeClient instance in our application object.
testApigee ta = new testApigee();

ta.setApigeeClient(apigeeClient);

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.