Introduction
When building an app with Appery.io, you can use social networks to authenticate users. This can be handy: if your app requires registration, instead of providing new credentials, the user can log in with a social network. For now, the following OAuth providers are supported:
First, you should create your app on the OAuth provider side. Read the detailed steps here.
When your app is created, use the provided credentials to configure the connection under database settings: go to Database > Your database > Social connections
, turn the toggle on for the needed social network, and specify the needed credentials.
When a user logs in via a social network, a new user will be created in Users
collection of the Appery.io database. Appery.io X-Appery-Session-Token
will be returned for further API calls.
Returned token doesn’t allows to trigger OAuth providers API. It’s only valid for Appery.io API calls, for example, the Database REST API.
Social network login API
Almost all methods require you to specify the database id, which will be used to create, sign in, log out, etc. your users. You can specify which database to use via dbId
parameter during each method execution, or use setDefaultDB method to specify database id globally.
All the methods are part of the Apperyio.User
namespace, so call them as Apperyio.User.<methodName>
.
The code with promise will run on the device ONLY. To learn how to test the app from browser, check here.
Method | Description |
---|---|
getToken | Returns Appery.io database token. |
getUserId | Returns Appery.io database user id. |
getStatus | Returns current authentication status. |
setDefaultDB | Sets default database id. |
createUser | Creates user in Appery.io database. |
login | Receives Appery.io database token. |
logout | Invalidates token in Appery.io database. |
findUsers | Returns list of users in Appery.io database. |
isLogged | Checks if Appery.io database token is valid. |
updateUser | Updates Appery.io database user. |
invalidate | Deletes Appery.io database token. Doesn’t invalidates token in Appery.io database. |
logoutOauth | Removes social id from Appery.io database. |
loginTwitter | Logging in via Twitter. |
loginFB | Logging in via Facebook. |
loginGoogle | Logging in via Google. |
getToken
Returns Appery.io database token.
Parameters
- dbId – database id. Optional if default database id is set.
getUserId
Returns Appery.io database user id.
Parameters
- dbId – database id. Optional if default database id is set.
getStatus
Returns current login status for certain database. By default, the database which is set by setDefaulDB
is used. If you’re making multiple authentication for several databases, you should provide dbId
parameter to determine, which database status should be returned.
See paragraph below for more about events and status.
Possible values:
- unauthorized
- inProgress
- authorized
- error
Parameters
- dbId – database id. Optional if default database id is set.
setDefaultDB
Sets default database id.
Parameters
- dbId – database id.
createUser
Creates user in Appery.io database. Returns promise.
See users sign up in the database REST API for more.
Parameters
- options – request data. Should contain at least
username
andpassword
fields. - dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.createUser({"username": "test", "password": "test"}).then(function(result){ alert("success_" + JSON.stringify(result)); },function(error) { alert("error_" + JSON.stringify(error)); }); |
login
Receives Appery.io database token. Returns promise.
See users sign in in database REST API for more.
Parameters
- options – request parameters. Should contain
username
andpassword
fields. - dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.login({"username": "test", "password": "test"}).then(function(result){ alert("success_" + JSON.stringify(result)); },function(error) { alert("error_" + JSON.stringify(error)); }); |
logout
Invalidates token in Appery.io database. Returns promise.
See users sign out in database REST API for more.
Parameters
- dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.logout().then(function(result){ alert("success_" + JSON.stringify(result)); },function(error) { alert("error_" + JSON.stringify(error)); }); |
findUsers
Returns list of users in Appery.io database. Returns promise.
See users query in database REST API for more.
Parameters
- options – request parameters. Should contain
username
andpassword
fields. - dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.findUsers({}).then(function(result){ alert("success_" + JSON.stringify(result)); },function(error) { alert("error_" + JSON.stringify(error)); }); |
isLogged
Checks if Appery.io database token is valid. Returns promise.
Parameters
- options – request parameters. Should contain
username
andpassword
fields. - dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.isLogged().then(function(result){ alert("success_" + JSON.stringify(result)); },function(error) { alert("error_" + JSON.stringify(error)); }); |
updateUser
Updates Appery.io database user. Returns promise.
See updating users in database REST API for more.
Parameters
- options – request parameters. Should contain
username
andpassword
fields. - dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.updateUser({"username": "test1", "password": "test"}).then(function(result){ alert("success_" + JSON.stringify(result)); },function(error) { alert("error_" + JSON.stringify(error)); }); |
invalidate
Deletes Appery.io database token. Doesn’t invalidate token in Appery.io database. Returns true
if token exists.
Parameters
- dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.invalidate().then(function(result){ alert("success_" + JSON.stringify(result)); },function(error) { alert("error_" + JSON.stringify(error)); }); |
logoutOauth
Removes social id from Appery.io database. Returns promise.
Parameters
- provider – provider id.
- dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.logoutOauth("twitter").then(function(result){ alert("success_" + JSON.stringify(result)); },function(error) { alert("error_" + JSON.stringify(error)); }); |
loginTwitter
Logging in via Twitter. Returns promise.
Parameters
- clientId – social provider client id.
- callbackUrl – URL for redirecting after user grants access.
- dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.loginTwitter("Twitter Consumer Key (API Key)", "http://appery.io/app/view/<YOUR-APPERY-IO-APP-ID>/").then(function(token){ alert("success_" + token); },function(error) { alert("error_" + JSON.stringify(error)); }); |
loginFB
Logging in via Facebook. Returns promise.
Parameters
- clientId – social provider client id.
- callbackUrl – URL for redirecting after user grants access.
- dbId – database id. Optional if default database id is set.
Example
1 |
Apperyio.User.loginFB("FB APP Id", "http://appery.io/app/view/<YOUR-APPERY-IO-APP-ID>/<Your_Login_Screen_Name>.html").then(function(token){ alert("success_" + token); },function(error) { alert("error_" + JSON.stringify(error)); }); |
loginGoogle
Logging in via Google. Returns promise.
Parameters
- clientId – social provider client id.
- callbackUrl – URL for redirecting after user grants access.
- dbId – database id. Optional if default database id is set.
Example
1 2 3 4 5 |
Apperyio.User.loginGoogle("Google Client ID", "http://appery.io/app/view/<YOUR-APPERY-IO-APP-ID>/").then(function(token){ alert("success_" + token); },function(error) { alert("error_" + JSON.stringify(error)); }); |
Authentication events and statuses
There are few events and statuses that generate during authentication process. You can use these events or status to properly track authentication phase or hook any custom logic. Status can be retrieved by using the getStatus method.
The flow is following:
Initially, authentication status equals unauthorized
. Before start authentication procedure, there is a dbloginstart
event fired and authentication status changes from unauthorized
to inProgress
.
After getting the response from Appery.io database or social network, dbloginend
event fires. Also, status changes to authorized
in case of success or to error
in case of fail.
Normally, when launching app on the mobile device, token will be received automatically during few second once the user logged in. Token will be returned as parameter to defined callback. But when testing app in the browser, app will be fully reloaded after the redirect back from social provider. In this case, callbacks defined in JavaScript will not work:
1 2 3 4 5 |
Apperyio.User.loginFB("FB APP Id", "http://appery.io/app/view/<YOUR-APPERY-IO-APP-ID>/").then(function(token){ //This code will not work in browser },function(error) { //This code will not work in browser too }); |
As all the data in your app was reset, you should also call
setDefaultDB
method after redirect if you’re using it.
As was written above, token will be received automatically during few seconds, so rely on the events and status to determine if the authentication done or not. For example, add the following code on Page Load
event or init
method if building AngularJS app:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
Apperyio.User.setDefaultDB('5492b499e4b0262b47c39fdc'); //If not on the device if (!(document.URL.indexOf('http://') === -1 && document.URL.indexOf('https://') === -1)) { checkStatus(); } function checkStatus() { if (Apperyio.User.getStatus() === "authorized") { //Check if authentication is already finished Apperyio.navigateTo("startScreen"); //And navgiate to diffferent page } else { if (Apperyio.User.getStatus() != "error") //If status not equals to error { document.addEventListener("dbloginend", function() { //Add event listener on dbloginend and check the status again checkStatus(); }); } } } |
You should have a verified Facebook account. Read here for more.
To create an app in Facebook:
- Go to http://developers.facebook.com/ and log in.
- Click
My Apps > Add a New App
. - Then select a
Website
as platform. - Enter your
Display Name
and click Create New Facebook App ID. - Then choose a
Category
(for example,Apps for Pages
) from the drop-down list and click Create App ID. - Once the app is created, to open its settings, go to
My Apps > <Your app name> > Settings.
- Click Choose a Platform. Choose
Website.
- Use the following
Site URL
as a template, but use your own Appery.io App ID:
1https://appery.io/app/view/<YOUR APPERY.IO APP ID>/ - The Appery.io App ID can be taken from the Appery.io app URL:
- Type
appery.io
intoApp Domains
and click Save Changes. - You should make your app public (go to the
App Review > Status
tab, tick the Yes/No button and confirm), otherwise it won’t be live and available to all users:
Use the App ID
and App Secret
to configure social login feature for certain Appery.io database.
- To create a new Twitter app, go to https://apps.twitter.com/. Click Create New App, enter the required information, and click Create your Twitter application.
- Then, open the
Keys and Access Tokens
tab to locate theAPI Key
andAPI Secret.
Use these credentials to configure social login feature for certain Appery.io databases.
Remember to set your app Twitter settings to have read-and-write access, allow the app to sign-in with Twitter, and generate your access token and secret access token.
If login doesn’t work, try adding the valid callback URL, like this: http://appery.io/app/view/YOUR APPERY. IO APP ID/login.html
.
X-Appery-App-Id
(YOUR APPERY. IO APP ID) can be taken from the Appery.io app URL:
To create projects with Google, you need to register with https://console.developers.google.com first.
- Select a project or create a new one, naming it (here:
ApperyioGoogle
) and accepting the terms of usage. - To make the social login work,
Google+ API
should be turned on: click Enable and manage APIs once the project is created and then clickGoogle+ API
. - In the window that opens, click Enable API.
- Now, open your project under
APIs & auth > Credentials
and click Add credentials. - In the window that opens, select
Web application.
Enter any name you want. - As a result, you’ll get your
client ID
andclient secret
credentials. - When you click OK, the list with your
OAuth 2.0 client IDs
appears: - Click on the created client id to open it’s settings. Applications that use JavaScript to access Google APIs must specify
Authorized JavaScript origins
. The origins identify the domains from which your application can send API requests. So, enterhttps://appery.io
forAuthorized JavaScript origins
. - Also, specify authorized
redirect URIs
. It should looks as following:
For AngularJS apps –http://appery.io/app/view/<APPERY-IO-APP-ID>/
For jQuery Mobile –http://appery.io/app/view/<APPERY-IO-APP-ID>/SomePage.html
- Replace
<APPERY-IO-APP-ID>
with your app id. It can be found in address string in the browser:
- After passing the required credentials, click Save.
Now, you can use the client ID
and client secret
to configure social login feature for the certain Appery.io database: