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


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


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


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


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


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


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


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


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


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


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

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:

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:

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:

  1. Go to http://developers.facebook.com/ and log in.
  2. Click My Apps > Add a New App.
  3. Then select a Website as platform.
  4. Enter your Display Name and click Create New Facebook App ID.
  5. Then choose a Category (for example, Apps for Pages) from the drop-down list and click Create App ID.
  6. Once the app is created, to open its settings, go to My Apps > <Your app name> > Settings.
  7. Click Choose a Platform. Choose Website.
  8. Use the following Site URL as a template, but use your own Appery.io App ID:
  9. The Appery.io App ID can be taken from the Appery.io app URL:
    URLString
  10.  Type appery.io into App Domains and click Save Changes.
  11. 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

  1. 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.
  2. Then, open the Keys and Access Tokens tab to locate the API Key and API Secret.TwitterCredentials

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:Link

Google

To create projects with Google, you need to register with https://console.developers.google.com first.

  1. Select a project or create a new one, naming it (here: ApperyioGoogle) and accepting the terms of usage.
  2. 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.
  3. In the window that opens, click Enable API.
  4. Now, open your project under APIs & auth > Credentials  and click Add credentials.
  5. In the window that opens, select Web application. Enter any name you want.
  6. As a result, you’ll get your client ID and client secret credentials.
  7. When you click OK, the list with your OAuth 2.0 client IDs appears:Creds
  8. 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.
  9. 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
  10. Replace <APPERY-IO-APP-ID> with your app id. It can be found in address string in the browser:
    Link
  11. 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: