Skip to content

Client-side Setup

Pure Java and Android clients can consume the Backendless services using the class library (JAR) provided in the Backendless SDK for Android/Java. If you downloaded Backendless SDK for Android/Java from our website, make sure to reference backendless.jar located in the /lib folder of the SDK in the project dependencies and the runtime classpath to get access to the API.

Gradle Setup

If your project uses Gradle, you can add the following configuration to your build.gradle file:

dependencies {  
    implementation group: 'com.backendless', name: 'backendless', version: '5.0.+'  

    // required for real-time database and real-time messaging  
    implementation ('io.socket:socket.io-client:1.0.0') {  
      // excluding org.json which is provided by Android  
      exclude group: 'org.json', module: 'json'  
    }  
}

Important

It is not recommended to use the '+' sign in the dependency version number. Make sure to check the current version of the Backendless library (check only 5.x or later) in Maven Central.

SDK from Maven

The backendless client library for Android and Java is available through the Maven repository. Since the version of Backendless deployed to maven changes frequently, make sure to lookup the latest version number from Maven Central. To add a dependency for the Backendless library, add the following to pom.xml:

<dependency>  
  <groupId>com.backendless</groupId>  
  <artifactId>backendless</artifactId>  
  <version>VERSION FROM MAVEN</version>   
</dependency>  

<!-- required for real-time database and real-time messaging -->  
<dependency>  
    <groupId>io.socket</groupId>  
    <artifactId>socket.io-client</artifactId>  
    <version>1.0.0</version>  
</dependency>

Android Manifest

Since Backendless APIs communicate with a server, it is necessary to add the android.permission.INTERNET permission to the manifest file. Add the line below to the <manifest> element:

<uses-permission android:name="android.permission.INTERNET" />

Application initialization

Before the Java/Android client uses any of the APIs, the code must initialize the Backendless Application using the following call:

Android apps

Backendless.initApp( Context, application-id, api-key );

where Context is an instance of android.content.Context. For instance, it may be your Android application main activity.

Java programs (command line, etc)

Backendless.initApp( application-id, api-key );

Proguard Configuration

If your Android application uses Proguard, it is necessary to add the following configuration parameters to proguard.cfg:

-dontwarn com.backendless.**  
-dontwarn weborb.**  
-keep class weborb.** {*;}

If you run your application with minifyEnabled (obfuscation is turned on), it is necessary to add the following statement to proguard.cfg:

-keep class com.backendless.** {*;}

Apps with Google Maps and Geolocation

Android applications using Google Maps, for instance, the Geo service sample app generated by Backendless code generator, require additional configuration in order for Google maps to be displayed. The process of configuring an app to support Google maps consists of the following tasks:

  1. Display the debug certificate fingerprint
    1. Locate your debug keystore file. The file name is debug.keystore, and is created the first time you build your project. By default, it is stored in the same directory as your Android Virtual Device (AVD) files:
      • OS X and Linux: ~/.android/
      • Windows Vista and Windows 7: C:\Users\your_user_name\.android\
    2. If you are using Eclipse with ADT, and you are not sure where your debug keystore is located, you can select Windows > Prefs > Android >Build to check the full path, which you can then paste into a file explorer to locate the directory containing the keystore.
    3. List the SHA-1 fingerprint.
      • For Linux or OS X, open a terminal window and enter the following:
        keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
        
      • For Windows Vista and Windows 7, run:
        keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android
        
    4. You should see output similar to this:
      Alias name: androiddebugkey  
      Creation date: Jan 01, 2013  
      Entry type: PrivateKeyEntry  
      Certificate chain length: 1  
      Certificate[1]:  
      Owner: CN=Android Debug, O=Android, C=US  
      Issuer: CN=Android Debug, O=Android, C=US  
      Serial number: 4aa9b300  
      Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033  
      Certificate fingerprints:  
           MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9  
           SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75  
           Signature algorithm name: SHA1withRSA  
           Version: 3
      
    5. The line that begins SHA1 contains the certificate's SHA-1 fingerprint. The fingerprint is the sequence of 20 two-digit hexadecimal numbers separated by colons.
  2. Create an API project in the Google APIs Console
    1. In a browser, navigate to the Google APIs Console.
      • If you haven't used the Google APIs Console before, you're prompted to create a project that you use to track your usage of the Google Maps Android API. Click Create Project; the Console creates a new project called API Project. On the next page, this name appears in the upper left hand corner. To rename or otherwise manage the project, click on its name.
      • If you're already using the Google APIs Console, you will immediately see a list of your existing projects and the available services. It's still a good idea to use a new project for Google Maps Android API, so select the project name in the upper left hand corner and then click Create.
    2. You should see a list of APIs and services in the main window. If you don't, select Services from the left navigation bar.
    3. In the list of services displayed in the center of the page, scroll down until you see Google Maps Android API v2. To the right of the entry, click the switch indicator so that it is on.
    4. This displays the Google Maps Android API Terms of Service. If you agree to the terms of service, click the checkbox below the terms of service, then click Accept. This returns you to the list of APIs and services.
  3. Obtain a Google Maps API key

    If your application is registered with the Google Maps Android API v2 service, then you can request an API key. It's possible to register more than one key per project.

    1. Navigate to your project in the Google APIs Console.
    2. In the Services page, verify that the "Google Maps Android API v2" is enabled.
    3. In the left navigation bar, click API Access.
    4. In the resulting page, click Create New Android Key....
    5. In the resulting dialog, enter the SHA-1 fingerprint, then a semicolon, then your application's package name. For example:
      BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75;com.example.android.mapexample
      
    6. The Google APIs Console responds by displaying Key for Android apps (with certificates) followed by a forty-character API key, for example:
      AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
      
  4. Add the API key to your application

    Follow the steps below to include the API key in your application's manifest, contained in the file AndroidManifest.xml. From there, the Maps API reads the key value and passes it to the Google Maps server, which then confirms that you have access to Google Maps data.

    1. In AndroidManifest.xml, add the following element as a child of the <application> element, by inserting it just before the closing tag </application>:
      <meta-data  
          android:name="com.google.android.maps.v2.API_KEY"  
          android:value="API_KEY"/>
      
    2. Substitute your API key for API_KEY in the value attribute. This element sets the key com.google.android.maps.v2.API_KEY to the value of your API key, and makes the API key visible to any MapFragment in your application.
    3. Save AndroidManifest.xml and re-build your application.

Application ID and API Key

Values for the application-id and api-key headers must be obtained through the Backendless Console:

  1. Login to your account and select the application.
  2. Click the Manage icon from the vertical icon-menu on the left.
  3. The App Settings section is selected by default. The interface contains values for Application ID and API keys for each supported client-side environment.
  4. Use the Copy icon to copy the value into the system clipboard.
    appsettings-keys.zoom60

Make sure to use the "Android API Key" for the api-key argument.