Loading...
 

Connect BackAuth

The usual process to implement a Social Login is stablishing a connection with the API of each Social Network you may have chosen as a registry method.

With the Xeerpa connect BackAuth product you will only need to stablish a connection with Xeerpa, as the product will take care of these connections itself. That way you don't need to know how each Social Network API works, Xeerpa Connect BackAuth will handle all these connections for you. How?

  • When users click on the login button Xeerpa Connect BackAuth is activated and automatically establishes the connection with the API of the social network selected, authenticating the user.
  • The solution also establishes the connection with the Xeerpa web service in order to analyze the user.
  • Furthermore, Xeerpa Connect BackAuth allows for the addition of more social networks at a later stage, quicker and with greater ease, aleviating your IT team from the task of monitoring for changes to the APIs of the various social networks.

 

Moreover, Xeerpa Connect BackAuth offers the following advantages::

  • Higher speed in the implementation of the Social Login. Once the connection with Xeerpa has been stablished, adding or removing Social Networks to your Social Login will be a matter of a few seconds.

  • You will not have to worry about any change in the policies of privacy and use of social API data. We will take care of maintaining the product updated.

  • Gather more advanced analytics which will allow you to know the details about the conditions the user has logged in with. We will have get more analytics of the users that have logged in from a SL connected to a XCBA.

 

This is the basic data flow designed for Xeerpa Connect BackAuth using Facebook:

Flujo BackAuth

 

Implementing Xeerpa Connect BackAuth

 

This section assumes you are familiar with the creation and configuration of apps in the desired social networks. To learn more about this please visit the section Social Network Apps.

 

Step 1: Information you'll need to send us

After choosing and configuring your app with the appropiate Permissions and Callback URL, you need to send the following information about each of your apps to support@xeerpa.com :

App Name:
Name of your app
Social Network:
Social network of your app
API ID/App Id or Key:
App’s ID in the social network
App Secret:
Your App secret from the social network
Brand:
App's brand ID or name
SocialLoginCallback:
URL called by a social network after the user accepts to log in. For example,   https://mydomain.com/socialLogin/socialLoginCallback.php
SocialLoginCompleted:
URL called by Xeerpa after the authentication process is completed. For example,   https://mydomain.com/socialLogin/socialLoginCompleted.php
Keep in mind
After this step we will send you an AUTHTOKEN and a PERSONALIZED URL only valid for your server, in order to call the Xeerpa engine. You will need these parameters for the next step

 

Step 2: Implement the Social Network Login Buttons 

Important

Upon request Xeerpa can provide sample code for implementing step 2 and step 3 of this document for PHP and Node.js. Please do not hesitate to inquire at support@xeerpa.com

2.1 Render your social network buttons in your website or promotion

You will need to implement a button for each Social Network you may have chosen in your Website, Mobile App or Promotion. To design the social login button follow these guidelines:
 
  • Color: It must be the Social Network's official color.
  • Logo: Use the official logo which will be available in the Brand Guidelines. Do not use old logos or custom variations.
  • Copy: We recommend you to use a phrase related to the call to action. These messages help improve the conversion rate. For example: "Login with.." or "Continue with.."

These are some examples of the buttons:

Social Login Buttons2

 

When the user clicks on one of these buttons you must open a new window popup and make a call to your own server to respond to this onclick event.

Keep in mind
Make sure you implement the parameter scrollbar=yes when opening the popup to ensure the view of the whole message in firefox.

 

2.2 In your server, create the entry point to receive the onclick event from step 2.1  (avoiding the use of the word “Xeerpa” in the url). From there make a GET request to Xeerpa using the following parameters:

https://auth-CLIENTURL/auth?authToken=AUTHTOKEN&socialNetwork=SOCIALNETWORK&id=ID&info=INFO&robinson=ROBINSON
CLIENTURL:
CLIENTURL was provided when you registered your app in Xeerpa.
authToken
AUTHTOKEN was provided when you registered your app in Xeerpa. 
socialNetwork
A reference to the social network chosen by the user to authenticate with.
FB: Facebook, TW: Twitter, LI: LinkedIn, GO: Google, IG: Instagram
id (Optional)
User’s ID in your CRM, when available.
info (Optional):
false by default. If true, Xeerpa will send an extra field with the default user information in a more detailed structure. See Step 2.4
robinson (Optional):
Whether or not the user accepts to receive commercial communications from you. This is typically requested to the user in an opt-in checkbox in your website or app. Set ROBINSON to TRUE if the user does NOT wish to receive them, or to FALSE if he wants to.

 

Xeerpa will respond with a JSON. If errorCode is not 1 you should deal with the error. Otherwise you mut redirect the popup to the url specified in the response:

errorCode:
Error code value will be 1 if everything is correct.
message:
Error message if any.
url:
URL where the user will need to be redirected to.
Example of call:

https://auth-test.xeerpa.com/auth?authToken=o0u1mnbjf9fadf45OGj6Abej897e6i98i7j9defh9jjcjbha7f&socialNetwork=FB

Example return value:

{

“errorCode": 1,

"url": "https://www.facebook.com/dialog/oauth?display=popup&response_type=code&redirect_uri=http%3A%2F%2Ftest.com%2Ftest%2F%2FresponseCallback.php %3Frid%3D5SQR8N9V15_iUaRgbZ1_h_9fjjjjcijb9ha75fc4iicage&scope=public_profile,email,user_friends,user_birthday,user_location,user_likes,user_tagged_places,user_posts&client_id=17347454208“

}

 

2.3 Create the socialLoginCallback point in your server (avoid using the word Xeerpa). This will be used one or more times (depending of the social network) to stablish a dialogue between Xeerpa and the social network. The information may arrive in your entry point by GET, POST or both, so it must be aggrupped and then sent to Xeerpa with a GET request. 

https://auth-CLIENTURL/auth/response?GET_AND_POST_RECEIVED
CLIENTURL:
CLIENTURL was provided when you registered your app in Xeerpa.
GET_AND_POST_RECEIVED:
Data received by the popup in by GET and POST methods.

 

For example, if a social network returns “aaa=123" by GET and "bbb=456“ by POST, you should construct the call to Xeerpa like that:

https://auth-test.xeerpa.com/auth/response?aaa=123&bbb=456

The response from Xeerpa will be a JSON similar to the step 2.2, and the next step depends of the presence of the property "fields" in the JSON:

  • if there is no "fields" property in the JSON, you can simply redirect the popup to the JSON's url property.
errorCode:
Error code. (1 if successful and no error occurred)
message:
Error message if error code is not 1
url:
URL to redirect the user (when the “fields” parameter is not present)

 

  • If the response does contain the fields property, you will have to make a POST request to the JSON's url passing the fields value as the body of the request.
errorCode:
Error code. (1 if successful and no error occurred)
message:
Error message if error code is not 1
url:
URL to redirect the user (when the “fields” parameter is not present)
For example, "https://www.linkedin.com/uas/oauth2/accessToken"
fields:
Some String to be used as body of the request.
For example, "ccc=789&ddd=0"
POST to https://www.linkedin.com/uas/oauth2/accessToken with body ccc=789&ddd=0

The response will always be a plain text that should be included as a query parameter called "data" to the popup's current url and redirect it to that new address.

redirect the popup to
https://auth-
CLIENTURL/auth/response?GET_AND_POST_RECEIVED&data=RESPONSE_PLAIN_TEXT

 

2.4 Create the socialLoginCompleted point in your server as specified in Step1.1 (avoid using the word Xeerpa). The last redirection made by the socialLoginCallback entry point is to your own server, passing the user information in JSON format.

errorCode:
Error code. (1 if successful and no error occurred)
message:
Error message if error code is not 1
DATA:

JSON with user’s data. Some data could be empty depending on the Social Network.

errorCode:
Errorcode.(1 if successful and no error occurred)
message:
Success or error message
id:
Xeerpa User ID
token:
Xeerpa User Token
socialNetwork:
Object
    name:
FB: Facebook, TW: Twitter, LI: LinkedIn, GO: Google, IG: Instagram
    id:
User ID in the social Network
    token:
User token in the social Network
    refreshToken
    verifier
    secret
If available in authenticated social network
auth:
Object
    expires:
Xeerpa token expiration date.
    refreshToken:
Special Xeerpa Token to request a new Xeerpa User Token
    firstTime:
The presence of this paramater indicates this is the first time this user has been authentified in Xeerpa 
user:
Object
    name
    nick
    email
    address
    country
    gender
    lang
    birthday
 
info:
Object (Available when the info parameter is specified in step 2.1)
    name:
Object
        first
        middle
        last
        full
        nick
String
    email:
Array
        value
        checked
String
    address:
Object
        raw
        country
        state
        city
        street
        building
        floor
        door
        zip
String
    phone:
Object
        raw
        countryCode
        number
        extension
        type
String
    gender:
Object
        value
String
    lang:
Object
        first
        second
        raw
String
    birthday:
Object
        day
        month
        year
        time
Number

 

At this point you should pass the user information back to your page, using postMessage, cookies or any other method of your preference. You may also securely process the user information and store it on your own database.

Optionally you can call Xeerpa to assign Robinson, a user’s CRM ID or extra data using Xeerpa's user ID and token: 

https://auth-CLIENTURL/auth/robinson?id=ID&token=TOKEN&robinson=Boolean
https://auth-CLIENTURL/auth/newId?id=ID&token=TOKEN&newId=String
https://auth-CLIENTURL/auth/data?id=ID&token=TOKEN&data=JSON
https://auth-CLIENTURL/auth/locs?id=ID&token=TOKEN&locs={"id":"FB_OR_CLIENT_ID","name":"LOCATION_NAME","lat":LATITUDE,"lon":LONGITUDE,"date":"YYYY-MM-DDTHH:MM:SS.000Z"}
CLIENTURL
CLIENTURL will be provided when we register your app in Xeerpa
ID
User’s Xeerpa ID: auth.id in Step 2.4
TOKEN
User’s Xeerpa Token: auth.token in Step 2.4
NEWID
User´s CRM ID
ROBINSON
TRUE if the user does not want to receive commercial communications, or FALSE if she/he accepts to receive them
DATA
External data in JSON format to insert into the user. Replace the & character with %26 in this parameter.
LOCS
Will add a Location to the Geolocations Map which can be used as a filter. The format will be a JSON like this: {"id":"FB_OR_CLIENT_ID","name":"Xeerpa","lat":40.42,"lon":-3.78,"date":"2018-09-25T11:23:42.000Z"}. I.E: You can send a WiFi ID to identify the users who logged in at a particular store. See an example below.

 

Finally you can close the popup or display a widget that helps you getting some social networks' special permissions. For more information read the next step.

 
 

Step 3: Obtain advanced user permissions

For Xeerpa to be able to gather and process the most important social information from the Facebook users, the Facebook Application linked to your Facebook Xeerpa Connection must be allowed to request the permissions to extract the advanced details. You can find more information about these permissions here.

Facebook reviews all the permission requests for every Facebook App, and this approval must be granted once for each Facebook App. You can use the Xeerpa Connect Summary Widget to obtain these permissions (user_birthday, user_location, user_posts, user_tagged_places, user_gender, user_friends and user_likes) - please feel free to request any further information about this Widget, contacting us through support@xeerpa.com.

 

Using Xeerpa Connect Summary Widget for Facebook

This Widget will be returned by Xeerpa as a JSON with some basic HTML which can be customized to match the look and feel of your website, mobile applicaiton, or WiFi hotspot, and can be extended to provide a more personalized user experience. Please check our Summary Widget article.

The Summary Widget call is already implemented in the Connect BackAuth PHP files, though in case you prefer to add the calls to your own PHP file, you can manually implement the Summary Widget making this call:

https://auth-CLIENTURL/widgets/summary?id=ID&token=TOKEN&lang=LANG&tab=TAB&css=CSS
CLIENTURL
CLIENTURL will be provided when we register your app in Xeerpa
ID
User’s Xeerpa ID:  'id' in Step 2.4
TOKEN
User’s Xeerpa Token: token in Step 2.4
LANG (Optional)
Language: EN: English. ES: Spanish. CA: Catalan. EN by default.
TAB (Optional)
USER | LIKES | PLACES. By default none. Which tab will be show expanded by default.
CSS (Optional)
TRUE | FALSE. TRUE by default. If TRUE Xeerpa will send a default css.
Keep in mind
Your website must not contain any '#fb' style set in the CSS.