Backendless API for Android © 2015 Backendless Corp. Backendless API for Android © 2015 Backendless Corp. All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the written permission of the publisher. Products that are referred to in this document may be either trademarks and/or registered trademarks of the respective owners. The publisher and the author make no claim to these trademarks. While every precaution has been taken in the preparation of this document, the publisher and the author assume no responsibility for errors or omissions, or for damages resulting from the use of information contained in this document or from the use of programs and source code that may accompany it. In no event shall the publisher and the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused directly or indirectly by this document. Generated on: December 2015 Special thanks to: All the people who contributed to this document, to everyone who has helped us out with the vision for the product, feature suggestions and ideas for improvements. Special thanks to our families for your support, encouragement and patience. 3 Contents Table of Contents User Service 6 1 Overvi.e..w................................................................................................................................ 6 2 Setup................................................................................................................................... 6 3 Core C.l.a..s..s.e..s.......................................................................................................................... 9 4 Error .H..a..n..d..l.i.n..g...................................................................................................................... 11 5 User P...r.o..p..e..r.t.i.e..s.................................................................................................................... 11 6 Retrie..v..e.. .U..s.e..r.. .E..n..t.i.t.y. .P...r.o..p..e..r.t.i.e..s............................................................................................ 13 7 User R...e..g..i.s.t.r.a..t.i.o..n.................................................................................................................. 14 8 Login................................................................................................................................... 17 9 Faceb..o..o..k.. .L..o..g..i.n................................................................................................................... 21 10 Upda.t.e.. .U..s.e..r.. .P..r.o..p..e..r.t.i.e..s........................................................................................................ 25 11 Get C.u..r.r..e..n..t. .U..s.e..r.................................................................................................................. 28 12 Logou..t................................................................................................................................. 28 13 Passw..o..r..d.. .R..e..c..o..v.e..r..y............................................................................................................. 29 14 Secur..i.t.y............................................................................................................................... 31 15 Role .T..o.. .U..s.e..r.. .M..a..p..p..i.n..g.......................................................................................................... 35 Data Service 37 1 Overv..i.e..w.............................................................................................................................. 37 2 Setup................................................................................................................................... 38 3 Sync .a..n..d.. .A..s..y..n..c. .C...a..l.l.s.......................................................................................................... 41 4 Error .H..a..n..d..l.i.n..g...................................................................................................................... 42 5 Native.. .v..s.. .E..x..t.e..r.n..a..l. .D..a..t.a..b..a..s..e..s.............................................................................................. 42 6 Using. .E..x..t.e..r.n..a..l. .D...a..t.a..b..a..s.e..s.................................................................................................... 43 7 Data .O..b..j.e..c..t......................................................................................................................... 47 8 Savin.g.. .D...a..t.a.. .O..b..j.e..c..t.s............................................................................................................ 48 9 Upda.t.i.n..g.. .D..a..t.a.. .O..b..j.e..c..t.s......................................................................................................... 52 10 Delet.i.n..g.. .D..a..t.a.. .O..b..j.e..c..t.s.......................................................................................................... 59 11 Retrie..v..i.n..g.. .S..c..h..e..m...a.. .D..e..f.i.n..i.t.i.o..n.............................................................................................. 65 12 Basic. .S..e..a..r.c..h........................................................................................................................ 67 13 Advan..c..e..d.. .S..e..a..r..c.h................................................................................................................. 73 14 Using. .D..a..t.e..s.. .i.n.. .S..e..a..r.c..h.......................................................................................................... 80 15 Relat.i.o..n..s. .O...v.e..r..v.i.e..w............................................................................................................... 81 16 Relat.i.o..n..s. .(.S..a..v..e../.U..p..d..a..t.e..)...................................................................................................... 87 17 Relat.i.o..n..s. .(.D..e..l.e..t.e..)................................................................................................................ 97 © 2015 Backendless Corp. 3 4 Backendless API for Android 18 Rela.t.i.o..n..s.. .(.R..e..t.r.i.e..v..e..)........................................................................................................... 104 19 Rela.t.i.o..n..s.. .w...i.t.h.. .G..e..o.. .P..o..i.n..t.s.................................................................................................. 114 20 Secu..r.i.t.y.............................................................................................................................. 122 21 Perm...i.s.s..i.o..n..s. .A..P...I................................................................................................................ 128 Messaging Service 131 1 Over..v.i.e..w............................................................................................................................. 131 2 Setu.p.................................................................................................................................. 131 3 Core.. .C..l.a..s.s..e..s...................................................................................................................... 135 4 Sync.. .a..n..d.. .A..s..y.n..c.. .C..a..l.l.s......................................................................................................... 138 5 Erro.r. .H..a..n..d..l.i.n..g.................................................................................................................... 139 6 Push.. .N..o..t.i.f.i.c..a..t.i.o..n.. .S..e..t.u..p.. .(.A..n..d..r..o..i.d..)..................................................................................... 139 7 Push.. .N..o..t.i.f.i.c..a..t.i.o..n.. .S..e..t.u..p.. .(.i.O...S..)............................................................................................ 143 8 Devi.c..e.. .R..e..g..i.s..t.r.a..t.i.o..n............................................................................................................ 153 9 Retr.i.e..v.e.. .D...e..v.i.c..e.. .R..e..g..i.s..t.r.a..t.i.o..n.............................................................................................. 154 10 Man.a..g..i.n..g.. .R..e..g..i.s..t.r.a..t.i.o..n..s..................................................................................................... 155 11 Canc..e..l. .D..e..v..i.c..e.. .R..e..g..i.s..t.r.a..t.i.o..n................................................................................................ 156 12 Mess..a..g..e.. .P..u..b..l.i.s..h..i.n..g........................................................................................................... 157 13 Publ.i.s..h.. .P..u..s..h.. .N..o..t.i.f.i.c..a..t.i.o..n..s................................................................................................. 164 14 Canc..e..l. .S..c..h..e..d..u..l.e..d.. .M...e..s.s..a..g..e............................................................................................... 165 15 Mess..a..g..e.. .S..u..b..s..c.r..i.p..t.i.o..n........................................................................................................ 166 16 Canc..e..l. .S..u..b..s..c..r.i.p..t.i.o..n........................................................................................................... 172 17 Send..i.n..g.. .E..m...a..i.l................................................................................................................... 173 File Service 175 1 Over..v.i.e..w............................................................................................................................. 175 2 Setu.p.................................................................................................................................. 175 3 Sync.. .a..n..d.. .A..s..y.n..c.. .C..a..l.l.s......................................................................................................... 179 4 Erro.r. .H..a..n..d..l.i.n..g.................................................................................................................... 180 5 Hand..l.i.n..g.. .F..i.l.e..s.. .v..i.a.. .C..o..n..s.o..l.e................................................................................................. 180 6 File .U..p..l.o..a..d......................................................................................................................... 184 7 Save.. .F..i.l.e..s.. .F..r.o..m... .B..y..t.e.. .A..r.r..a..y.s.............................................................................................. 189 8 File .D..o..w...n..l.o..a..d.................................................................................................................... 191 9 File .D..e..l.e..t.i.o..n....................................................................................................................... 192 10 Dire.c.t.o..r..y. .D...e..l.e..t.i.o..n.............................................................................................................. 193 11 Git I.n..t.e..g..r.a..t.i.o..n.................................................................................................................... 193 12 Web. .H...o..s.t.i.n..g....................................................................................................................... 195 13 Cust.o..m... .D..o..m...a..i.n.. .N..a..m...e........................................................................................................ 196 14 Cust.o..m... .W...e..b.. .T..e..m...p..l.a..t.e.. .H..o..s..t.i.n..g.......................................................................................... 197 15 Files.. .S..e..c..u..r.i.t.y..................................................................................................................... 200 © 2015 Backendless Corp. 5 Contents Geo Service 201 1 Over..v.i.e..w............................................................................................................................. 201 2 Setu.p.................................................................................................................................. 203 3 Sync.. .a..n..d.. .A..s..y.n..c.. .C..a..l.l.s......................................................................................................... 206 4 Erro.r. .H..a..n..d..l.i.n..g.................................................................................................................... 207 5 Addi.n..g.. .a.. .G...e..o.. .C..a..t.e..g..o..r.y...................................................................................................... 207 6 Dele.t.i.n..g.. .a.. .G...e..o.. .C..a..t.e..g..o..r.y.................................................................................................... 211 7 Retr.i.e..v.i.n..g.. .G...e..o.. .C..a..t.e..g..o..r.i.e..s................................................................................................. 213 8 Addi.n..g.. .a.. .G...e..o..P..o..i.n..t............................................................................................................ 215 9 Upda..t.i.n..g.. .a.. .G...e..o..P..o..i.n..t......................................................................................................... 217 10 Dele.t.i.n..g.. .a.. .G...e..o..P..o..i.n..t.......................................................................................................... 217 11 Impo..r.t.i.n..g.. .G...e..o.. .D..a..t.a............................................................................................................ 219 12 Sear..c.h.. .i.n.. .C...a..t.e..g..o..r.y............................................................................................................ 221 13 Sear..c.h.. .i.n.. .R...a..d..i.u..s............................................................................................................... 224 14 Sear..c.h.. .i.n.. .R...e..c.t.a..n..g..u..l.a..r.. .A..r.e..a............................................................................................... 232 15 Geo. .P..o..i.n..t. .C..l.u..s..t.e..r.i.n..g.......................................................................................................... 239 16 Rela.t.i.o..n..s.. .w...i.t.h.. .D..a..t.a.. .O..b..j.e..c..t.s............................................................................................... 248 17 Geo.f.e..n..c.e.. .D...e..s.i.g..n..e..r............................................................................................................ 252 18 Geo.f.e..n..c.e.. .A...P..I.................................................................................................................... 263 Index 269 © 2015 Backendless Corp. 5 6 Backendless API for Android 1 User Service 1.1 Overview The Backendless User Service empowers applications with the functionality related to the user accounts such as user registrations, logins, password recovery and logouts. The core concept which the User Service relies on is the User entity. The structure of the entity is configurable, that is a developer can decide which properties "describe" a user in the context of a given version of the application. Typically, properties describing a user are the ones collected during the user registration process. The User Service provides the API enabling the following functionality for the applications built on top of Backendless: User Registration - Applications use the Backendless' registration API to let the users register and create accounts for subsequent logins. Application developers can restrict access to the server-side resources for specific user accounts or based on roles. User Login - the API lets the registered users login to establish their identity within the application. Password Recovery - Backendless supports a complete workflow allowing users to recover lost or forgotten passwords. User Logout - the API lets the logged in users terminate their session and disassociate their identity from the application. Updating User Registration - the API supports the operation of updating user information. 1.2 Setup Pure Java and Android clients can consume the Backendless services using the class library (JAR) provided in the Backendless SDK for Java. 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. Download SDK The SDK can be downloaded from the Backendless website. Maven integration The backendless client library for Android and Java is available through the Maven repository. To add a dependency for the library, add the following to pom.xml: com.backendless android 1.0 Before the Java/Android client uses any of the APIs, the code must initialize the Backendless Application using the following call: Backendless.initApp( application-id, secret-key, version ); Proguard Configuration If your Android application uses Proguard, it is necessary to add the following configuration parameters to proguard.cfg: © 2015 Backendless Corp. 7 User Service -dontwarn -keep class weborb.** {*;} 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. © 2015 Backendless Corp. 8 Backendless API for Android 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 element, by inserting it just before the closing tag : 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 Secret Key Values for the application-id and secret-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. © 2015 Backendless Corp. 9 User Service 3. The "App Settings" section is selected by default. The interface contains the text fields for "Application ID" and secret keys for each supported client-side environment. 4. Use the "Copy" button to copy the value into the system clipboard. Make sure to use the "Android Secret Key" for the secret-key argument. The version argument must contain the name of the targeted version. When a new application is created, the default version name is "v1". To manage versions, login to the console, select the "Manage" icon and click "Versioning". 1.3 Core Classes The Backendless User Service uses the following core classes: Backendless.UserService - provides access to the user service API. All user-related operations, such as user registration, user update, login, logout and password recovery are available through this class. BackendlessUser - represents a user registered with the application. The class is used in: User Registration - an instance of the class contains a list of user properties User Registration/Properties Update - an instance of the class contains a list of properties to be updated The Login method returns an instance of the class upon successful login. BackendlessUser Class Definition The BackendlessUser class is defined as: © 2015 Backendless Corp. 10 Backendless API for Android package com.backendless; import java.util.HashMap; import java.util.Map; public class BackendlessUser { // Returns all properties of the user object public Map getProperties() // sets the properties of the user to the values from the specified map public void setProperties( Map properties ) // adds properties from the specified map to the existing properties collection public void putProperties( Map properties ) // retrieves the value of the property public Object getProperty( String key ) // sets the value of the property public void setProperty( String key, Object value ) // returns internal id of the user object assigned by Backendless. // The value is available only for registered user accounts. public String getUserId() // sets the password for the account public void setPassword( String password ) // retrieves the password for the user account public String getPassword() } AsyncCallBack - an interface used in the asynchronous API calls. An implementation of the interface must provide two methods. One accepting a result from the server (with the generic type T as the argument) and the other for handling errors reported by the server. AsyncCallback Class Definition The AsyncCallback interface is defined as: package com.backendless.async; import com.backendless.exceptions.BackendlessFault; public interface AsyncCallback { public void handleResponse( T response ); public void handleFault( BackendlessFault fault ); } © 2015 Backendless Corp.

Backendless API for Android

Similar Backendless API for Android