Backendless API for JavaScript

202 Pages·2015·19 MB·English

Backendless API for JavaScript
© 2015 Backendless Corp.
Backendless API for JavaScript
© 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.......................................................................................................................... 7
4 Error H..a..n..d..l.i.n..g....................................................................................................................... 8
5 User P.r.o..p..e..r.t.i.e..s...................................................................................................................... 9
6 Retrie..v..e.. .U..s.e..r.. .E..n..t.i.t.y. .P...r.o..p..e..r.t.i.e..s............................................................................................ 10
7 User R...e..g..i.s.t.r.a..t.i.o..n.................................................................................................................. 12
8 Login................................................................................................................................... 15
9 Upda.t.e.. .U..s.e..r.. .P..r.o..p..e..r.t.i.e..s........................................................................................................ 18
10 Get C.u..r.r..e..n..t. .U..s.e..r.................................................................................................................. 20
11 Logou..t................................................................................................................................. 21
12 Passw..o..r..d.. .R..e..c..o..v.e..r..y............................................................................................................. 22
13 Secur..i.t.y............................................................................................................................... 24
14 Role .t.o.. .U..s.e..r.. .M..a..p..p..i.n..g........................................................................................................... 28
Data Service 29
1 Overv..i.e..w.............................................................................................................................. 29
2 Setup................................................................................................................................... 29
3 Sync .a..n..d.. .A..s..y..n..c. .C...a..l.l.s.......................................................................................................... 30
4 Error .H..a..n..d..l.i.n..g...................................................................................................................... 31
5 Native.. .v..s.. .E..x..t.e..r.n..a..l. .D..a..t.a..b..a..s..e..s.............................................................................................. 31
6 Using. .E..x..t.e..r.n..a..l. .D...a..t.a..b..a..s.e..s.................................................................................................... 32
7 Data .O..b..j.e..c..t......................................................................................................................... 36
8 Savin.g.. .D...a..t.a.. .O..b..j.e..c..t.s............................................................................................................ 36
9 Upda.t.i.n..g.. .D..a..t.a.. .O..b..j.e..c..t.s......................................................................................................... 38
10 Delet.i.n..g.. .D..a..t.a.. .O..b..j.e..c..t.s.......................................................................................................... 42
11 Retrie..v..i.n..g.. .S..c..h..e..m...a.. .D..e..f.i.n..i.t.i.o..n.............................................................................................. 46
12 Basic. .S..e..a..r.c..h........................................................................................................................ 47
13 Advan..c..e..d.. .S..e..a..r..c.h................................................................................................................. 50
14 Using. .D..a..t.e..s.. .i.n.. .S..e..a..r.c..h.......................................................................................................... 54
15 Relat.i.o..n..s. .O...v.e..r..v.i.e..w............................................................................................................... 56
16 Relat.i.o..n..s. .(.S..a..v..e../.U..p..d..a..t.e..)...................................................................................................... 62
17 Relat.i.o..n..s. .(.D..e..l.e..t.e..)................................................................................................................ 69
18 Relat.i.o..n..s. .(.R..e..t.r..i.e..v.e..)............................................................................................................. 72
© 2015 Backendless Corp.
3
4
Backendless API for JavaScript
19 Relat.i.o..n..s. .w...i.t.h.. .G..e..o.. .P...o..i.n..t.s................................................................................................... 77
20 Secur..i.t.y............................................................................................................................... 83
Messaging Service 89
1 Overv..i.e..w.............................................................................................................................. 89
2 Setup................................................................................................................................... 90
3 Core .C..l.a..s..s.e..s........................................................................................................................ 91
4 Sync .a..n..d.. .A..s..y..n..c. .C...a..l.l.s.......................................................................................................... 93
5 Error .H..a..n..d..l.i.n..g...................................................................................................................... 93
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..)....................................................................................... 94
7 Push .N..o..t.i.f.i.c..a..t.i.o..n.. .S..e..t.u..p.. .(.i.O...S..).............................................................................................. 97
8 Mess..a..g..e.. .P..u..b..l.i.s..h..i.n..g........................................................................................................... 107
9 Publ.i.s..h.. .P..u..s..h.. .N..o..t.i.f.i.c..a..t.i.o..n..s................................................................................................. 116
10 Canc..e..l. .S..c..h..e..d..u..l.e..d.. .M...e..s.s..a..g..e............................................................................................... 118
11 Mess..a..g..e.. .S..u..b..s..c.r..i.p..t.i.o..n........................................................................................................ 119
12 Canc..e..l. .S..u..b..s..c..r.i.p..t.i.o..n........................................................................................................... 123
13 Send..i.n..g.. .E..m...a..i.l................................................................................................................... 124
File Service 126
1 Over..v.i.e..w............................................................................................................................. 126
2 Setu.p.................................................................................................................................. 127
3 Sync.. .a..n..d.. .A..s..y.n..c.. .C..a..l.l.s......................................................................................................... 128
4 Erro.r. .H..a..n..d..l.i.n..g.................................................................................................................... 129
5 Hand..l.i.n..g.. .F..i.l.e..s.. .v..i.a.. .C..o..n..s.o..l.e................................................................................................. 129
6 File .U..p..l.o..a..d......................................................................................................................... 133
7 Save.. .F..i.l.e..s.. .F..r.o..m... .B..y..t.e.. .A..r.r..a..y.s.............................................................................................. 135
8 File .D..o..w...n..l.o..a..d.................................................................................................................... 136
9 File .D..e..l.e..t.i.o..n....................................................................................................................... 138
10 Dire.c.t.o..r..y. .D...e..l.e..t.i.o..n.............................................................................................................. 138
11 Git I.n..t.e..g..r.a..t.i.o..n.................................................................................................................... 139
12 Web. .H...o..s.t.i.n..g....................................................................................................................... 141
13 Cust.o..m... .D..o..m...a..i.n.. .N..a..m...e........................................................................................................ 142
14 Cust.o..m... .W...e..b.. .T..e..m...p..l.a..t.e.. .H..o..s..t.i.n..g.......................................................................................... 143
15 Files.. .S..e..c..u..r.i.t.y..................................................................................................................... 145
Geo Service 146
1 Over..v.i.e..w............................................................................................................................. 146
2 Setu.p.................................................................................................................................. 148
3 Erro.r. .H..a..n..d..l.i.n..g.................................................................................................................... 149
4 Addi.n..g.. .a.. .G...e..o.. .C..a..t.e..g..o..r.y...................................................................................................... 150
© 2015 Backendless Corp.
5
Contents
5 Dele.t.i.n..g.. .a.. .G...e..o.. .C..a..t.e..g..o..r.y.................................................................................................... 153
6 Retr.i.e..v.i.n..g.. .G...e..o.. .C..a..t.e..g..o..r.i.e..s................................................................................................. 155
7 Addi.n..g.. .a.. .G...e..o..P..o..i.n..t............................................................................................................ 156
8 Upda..t.i.n..g.. .a.. .G...e..o..P..o..i.n..t......................................................................................................... 158
9 Dele.t.i.n..g.. .a.. .G...e..o..P..o..i.n..t.......................................................................................................... 158
10 Impo..r.t.i.n..g.. .G...e..o.. .D..a..t.a............................................................................................................ 160
11 Sear..c.h.. .i.n.. .C...a..t.e..g..o..r.y............................................................................................................ 161
12 Sear..c.h.. .i.n.. .R...a..d..i.u..s............................................................................................................... 166
13 Sear..c.h.. .i.n.. .R...e..c.t.a..n..g..u..l.a..r.. .A..r.e..a............................................................................................... 170
14 Geo. .P..o..i.n..t. .C..l.u..s..t.e..r.i.n..g.......................................................................................................... 174
15 Rela.t.i.o..n..s.. .w...i.t.h.. .D..a..t.a.. .O..b..j.e..c..t.s............................................................................................... 180
16 Geo.f.e..n..c.e.. .D...e..s.i.g..n..e..r............................................................................................................ 184
17 Geo.f.e..n..c.e.. .A...P..I.................................................................................................................... 195
Index 200
© 2015 Backendless Corp.
5
6
Backendless API for JavaScript
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
To get access to the Backendless services, JavaScript applications must reference the backendless.js
library. The library can be retrieved using any of the approaches listed below:
1. Download Backendless SDK for JavaScript. The SDK can be downloaded from the Backendless
website
2. Install the Backendless Bower package:
bower install backendless
3. Reference the library with either one of the URLs below:
non-compressed library:s
http://api.backendless.com/sdk/js/latest/backendless.js
compressed library:
http://api.backendless.com/sdk/js/latest/backendless.min.js
Before the JavaScript client uses any of the APIs, the code must initialize the Backendless Application
using the following call:
Backendless.initApp( application-Id, secret-key, version )
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.
7
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 "JavaScript 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.
Backendless.User - 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.
The Backendless.User definition contains only one field - password. All other fields can be defined
on the fly - see User Registration for details.
© 2015 Backendless Corp.
8
Backendless API for JavaScript
Backendless.Async - a construct used in the asynchronous API calls. Must reference two functions:
one accepting a result from the server and the other for handling errors reported by the server.
Backendless.Async Definition
The Backendless.Async function is defined as:
function Async( successCallback );
function Async( successCallback, context );
function Async( successCallback, faultCallback, context );
Backendless.Async = Async;
where:
successCallback - a reference to a function which will be called when the server returns a
result. The signature of this callback function must accept one argument
which will be the actual result object returned by the server.
faultCallback - an (optional) reference to a function which will be called if the server
returns an error. The function must accept one argument which is a fault
object containing the information about the error.
context - an (optional) reference to the object which is used as "this" when
calling successCallback or faultCallback
1.4 Error Handling
When the server reports an error, it is delivered to the client through a fault object, which is an untyped
JavaScript object. The fault object has the same structure for both synchronous and asynchronous
invocations:
{
"message": value,
"statusCode": value
}
where:
message - contains a string value with the description of the error
statusCode - error code as a string value. Currently all the error codes are numbers,
however the method returning the error code returns the String type. This is
done for future expansion of the error code system which may include
characters.
The asynchronous calls receive the fault through the fault callback referenced in the Async function.
For the synchronous calls the fault object is thrown as an error which must be handled in a catch( err
) block:
try
{
backendlessAPIcall();
}
catch( err )
{
console.log( "Error message - " + err.message );
console.log( "Error code - " + err.statusCode );
}
© 2015 Backendless Corp.
9
User Service
1.5 User Properties
When a user registers with an application, he provides information which establishes the person's
identity. For one application these properties may include name, phone number and email address, for
another it could be user id, age and gender. Backendless User Service allows each application to have a
custom set of properties associated with the user entity. There are two ways to define what properties
the User entity should have in a Backendless application:
Defining properties with Console
User property management is available on the User Properties screen of the console. To get to the
screen:
1. Login to the console
2. Select the desired application and version
3. Click the Users icon on the left side of the interface. The "User Properties" panel is selected by
default.
The interface consists of two lists: Available Properties and Selected Properties. The Selected
Properties list contains the properties assigned to the User entity - these are the effective properties for
the selected version of the application. The Available Properties list is simply a storage for the non-
effective properties which can be moved to the Selected list if needed. A property can be moved between
the lists by clicking its name.
Identity Property
Among the Selected Properties, one must be marked as identity. This is the property Backendless
uses for the Login and Restore Password operations.. As users register, Backendless ensures the
provided value for the property selected as identity is unique in the context of a specific version for
an application.
Password Property
"password" is a special property. Backendless automatically adds the property when an application
is created. The following rules apply to the password property:
Password cannot be moved out of the Available Properties list.
Password cannot be marked as Identity.
Password is always a required property
© 2015 Backendless Corp.
10
Backendless API for JavaScript
To add a property, click the "Add Custom Property" button. New properties automatically added to the
Selected Properties list. To move a property to the other list, simply click its name.
Defining properties with API
User properties can be defined with the user registration API call. For any property specified in the
object with the user registration information Backendless creates a user property. This behavior can be
turned off/on using the Dynamic User Definition configuration setting in the console (select the Users >>
User Properties). The setting is turned on by default:
1.6 Retrieve User Entity Properties
Application developers can get a list of the properties associated with the user entity using the following
API:
Asynchronous Call Method Signature:
The method call does not block - it returns immediately. The Backendless.Async argument receives
either the response or the fault returned by the Backendless servers.
Backendless.UserService.describeUserClass( Backendless.Async
callback );
where:
callback - an an instance of Backendless.Async which receives either a return value or an error
from the server. The return value from the server is an array of the objects describing
properties of the User entity for the specified version of the application. The structure of
the object in the response array is:
© 2015 Backendless Corp.