Skip to end of metadata
Go to start of metadata

The AMPLIFY Appcelerator Platform Services SDK for Android provides APIs for your Android application built with Java to access Mobile Backend Services (MBS).

Getting the SDK

To download and start using the SDK, you first need to register your Android application in Dashboard. See Managing Non-Titanium Client Applications in Dashboard for details on registering a new application. After you register the application, a service key is generated that associates your application with all the Platform services. Appcelerator Dashboard also provides full instructions for enabling all Platform Services in your application. This guide will deal specifically with enabling and using MBS in an Android application.

Running the APSCloud example application

The SDK ZIP file includes an Android sample project that demonstrates the basic usage of each of the Cloud APIs. To run the sample, you first need to register a new application in Dashboard to obtain the necessary service key. You will then copy the key into the imported sample project's main Activity and then run the application.

Create the APSCloudExample application in Dashboard:

  1. Log into the AMPLIFY Platform.
  2. Select the Dashboard link on the Dashboard tile.
  3. From the Orgs menu, select the organization to associate with the application. Note that the Orgs menu will not appear if you are not a member of multiple organizations.
  4. Click the Add menu (+) and select Register App for Services.
  5. In the dialog:
    • Type APSCloudExampleApp (or another name) in the Name field.
    • Select Android from the Platform menu.
    • Select any category from the Category menu.
  6. Click Next and then click the Overview tab.
  7. Click the Services tab, then click Show Key under Cloud > Performance > Analytics.
  8. Select Development from the Environment menu, then click the clipboard icon to copy the key to your clipboard.

 

Build APSCloudExample project:

  1. Launch the Android Studio IDE.
  2. Click "Open an existing Android Studio project' in the welcome dialog.
  3. Open folder: ./appcelerator-sdk-android-<VERSION>/examples
  4. Open file: ./APSCloudExample/src/main/java/com/appcelerator/apscloudexample/MainActivity.java
  5. Locate the following line of code and replace << YOUR APP KEY >> with the service key you copied to your clipboard previously.

  6. In Android Studio top toolbar, select "APSCloudExample" from the drop-down menu.
  7. Run the application on an Android device or emulator.

Once the application is running, try the following:

  • Create a new user by selecting Users > Create User. Enter a username, password, and password confirmation, then click Create. If the user is created successfully, the following dialog is shown:
     
  • View the newly created user in Dashboard:
    1. Log into the AMPLIFY Platform.
    2. Select the Dashboard link on the Dashboard tile.
    3. Select your MBS application from the Apps tab.
    4. Select Manage Data, then click Users in the Manage Data Objects table. You should see the user you created listed in the Users table.

Enabling Cloud services in a new project

Once you've registered an application in Dashboard, downloaded the APS SDK, and obtained your application service key.

Set up Cloud services in your project:

  1. Create a libs folder under your Android app project folder.
  2. From the APS SDK's libs folder, copy the following files to your app project's libs folder:
    • aps-analytics.aar
    • aps-cloud.aar
    • aps-services.aar
  3. Open your Android app project's build.gradle file and add the following to the dependencies block.

    build.gradle
  4. Import the APSServiceManager class into the project's main Activity:

  5. Call the below APSServiceManager class' enable() method in your main activity's onCreate() method. Set the "<<YOUR APP KEY>>" to the Service key provided by the Dashboard.

    MainActivity.java

    At this point, your application can begin making API calls. Note that the application will need to import additional classes, depending on which APS APIs it uses.

Making API Calls and Handling Responses

The com.appcelerator.aps package contains a collection of classes whose methods map to individual REST API method endpoints. For example, the APSUsers.create() method corresponds to the /users/create.json method endpoint.

Alternatively, you can use the generic APSCloud.sendRequest() method to make REST calls directly against the Cloud APIs. For more information, see Making Generic REST API Calls.

Icon

All Cloud API calls must be made on the UI (main) thread, and callbacks are executed on the UI thread.

Building Request Parameters

The first parameter of each Cloud API method is a HashMap object that contains the parameters to send with the request. For example, the APSPhotos.show() method takes a photo_id parameter whose value is, naturally, the ID of the photo to show.

Handling Responses

The second parameter of each method call is an instance of APSResponseHandler, an interface that has the following signature:

The instance you specify must override the onResponse and onException methods. The onResponse method is invoked upon completion of a Cloud API call, and the onException handler is invoked if there is an exception while communicating with the MBS server.

The APSResponse object provides getter methods to access information about the response. For instance, the getSuccess() method returns a boolean indicating if the method call was successful or not; the getResponse() method returns a JSON-encoded object with the results of the method call.

The onException() handler is invoked for any exceptions that occur during communication with the MBS server.

Example: APSUsers Login Call with Response Handler

The following example logs in an existing MBS user by their username and password. After a successful login, the application updates a TextView object with the user's MBS username.

Monitoring Request Progress

For Cloud API methods that involve uploading large files, such as APSPhotos.create() or APSFiles.create(), there is an overloaded version that takes an optional progressHandler parameter. This parameter takes an APSProgressHandler instance, which must provide an onProgress handler. This handler is periodically triggered as the file transfer continues and is passed an integer between 0-100, indicating the current upload progress.

Example: APSFiles Create Call with Progress Handler

The following example uploads a file from the device (/res/raw/reference.pdf) to the MBS storage server. Since the method call requires that uploaded data be an instance of java.io.File, the application needs to copy the resource to a read-write directory before uploading it. Locally storing the file requires that the WRITE_EXTERNAL_STORAGE permission is included in your AndroidManifest.xml file.

The progress callback calls the setProgress() method on a ProgressBar object, displaying the status of the upload. After the request completes, the application displays a toast notification.

 Expand source

Making Generic REST APIs Method Calls

The APSCloud.sendRequest() method lets you quickly make REST API calls directly against MBS, rather than using the specialized classes (like APSUsers). In general, you should use specialized classes as they provide an easier API. However, if new REST methods are deployed to the APS Cloud backend, this approach lets you immediately start using those methods without waiting for an update to the SDK.

To make a generic request, you call APSCloud.getInstance() to get a reference to the shared APSCloud object and call its sendRequest() method. For each call, you must specify the following:

  • REST API method endpoint relative to api.cloud.appcelerator.com/v1. Method endpoints are listed in the corresponding entries in the REST API documentation.
  • The HTTP method to use.
  • Data to send with the request.

For example, to create a post, pass the sendRequest() method the following information:

  • REST API method endpoint: posts/create.json
  • The HTTP method to use: POST
  • Data to send with the request: at a minimum, you must specify the content property.

The following uses the sendRequest() API to create a new Post object.

 Expand source

Working with Push Notifications

The  APSPushNotifications class lets your application subscribe, send, and receive push notifications. To use the class, you also need the  APSCloudPush class, which provides the underlying services to handle incoming push notifications.

To use these classes:

Adding the APSCloudPush Library

  1. Create a libs folder under your Android app project folder.
  2. From the APS SDK's libs folder, copy the following files to your app project's libs folder:
    • aps-analytics.aar
    • aps-cloud.aar
    • aps-cloudpush.aar
    • aps-services.aar
  3. Open your Android app project's build.gradle file and add the following to the dependencies block.

    build.gradle

Subscribe to push notifications

Once the project is set up, the application needs to register with MBS to receive push notifications. The application should do this once the application starts, for example, in the onCreate() method of the application's main activity.

To register push notifications, the application needs to retrieve the device token using the  APSCloudPush.getInstance.retrieveDeviceToken() method, then pass the token to either the  APSPushNotifications.subscribe() or  APSPushNotifications.subscribeToken() method to subscribe to a push channel.

Icon

Call APSServiceManager.getInstance().enable() before calling any methods on APSCloudPush; otherwise, an exception will be thrown.

For example, the code below can be added to the main activity's onCreate() method to subscribe the device to the friend_channel:

 Expand source

Once push services have been configured, and you've obtained a device token by registering your application to receive push notifications, you can start calling methods of the APSCloudPush and APSPushNotifications classes.

CloudPush example application

The SDK includes the APSCloudPushExample application that demonstrates the use of the APSPushNotifications and APSCloudPush APIs. To run the sample application, you'll first need to create an Android application in Dashboard (or use an existing application) and configure its push notification settings to include a FCM sender ID and application key.

Build the APSCloudPushExample application:

  1. Launch the Android Studio IDE.
  2. Click "Open an existing Android Studio project' in the welcome dialog.
  3. Open folder: ./appcelerator-sdk-android-<VERSION>/examples
  4. Open file: ./APSCloudPushExample/src/main/java/com/appcelerator/apscloudpushexample/MainActivity.java
  5. Locate the following line of code and replace << YOUR APP KEY >> with the service key generated by Dashboard.

  6. In Android Studio top toolbar, select "APSCloudPushExample" from the drop-down menu.
  7. Run the application on an Android device or emulator.