Social login API | Appery.io Dev Center

If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

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:

Twitter
Facebook
Google

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 and password fields.
dbId – database id. Optional if default database id is set.

Example

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 and password fields.
dbId – database id. Optional if default database id is set.

Example

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

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 and password fields.
dbId – database id. Optional if default database id is set.

Example

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 and password fields.
dbId – database id. Optional if default database id is set.

Example

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 and password fields.
dbId – database id. Optional if default database id is set.

Example

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

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

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

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

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:

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:

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();

});

}

Note, that check starts only if the app launched in browser, because when app working on the device token will be retrieved via callback registered with dot notation.

Registering an app with social network

Facebook

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:

1

https://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 into App 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.

Twitter

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 the API Key and API 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:

Google

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 click Google+ 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 and client 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, enter https://appery.io for Authorized 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: