Connect Discovery

Xeerpa Connect Discovery assumes you have already implemented your own Social Login functionality on your website, mobile application, or WiFi hotspot. If this is not the case, please inquire about our Social Login Xeerpa Connect Backend Auth which facilitates connection with the API of each social network with Xeerpa.

Xeerpa is compatible with Social Login providers like Gigya, Janrain, LoginRadius, Cool-Tabs and EasyPromos, if you are using them you should check their specific documentation instead of this.


What is Xeerpa Connect Discovery?


Xeerpa Connect Discovery is a web service that, once called for each user logging in to your website, allows Xeerpa to process the social data of those users that connect via the social login buttons you may have provided.

When a user logs in with their social profile on your website or app, you'll need to make a GET request from your server through the Xeerpa Connect Discovery web service so that Xeerpa can generate a profile for that user in the Xeerpa Dashboards. This call requires a specific set of parameters to be sent to Xeerpa.

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

Flujo Discovery


Step 1: Information you'll need to send us

 Firstly, you need to let us know (by email at support@xeerpa.com) the following information about your apps:

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 in the social network
Brand ID that the app corresponds to, if more than one of your brands share the app
Url where we can access your app’s thumbnail image
List of permissions that your app is requesting
Server IP:
Your server's API address. Note that calls to Xeerpa Connect Discovery must be made from the server, never from a client device like the user's browser or from a mobile device



Step 2: Connect your app to Xeerpa 

Implement the call to our Xeerpa Connect Discovery web service, which will need to be launched by your server every time a user accepts your app permissions or logs in:

CLIENTURL will be provided when we register your app in Xeerpa (see step 1 above)
CLIENTID will be provided when we register your app in Xeerpa (see step 1 above)
CLIENTPWD will be provided when we register your app in Xeerpa (see step 1 above)
Social network where you are launching your app: FB :Facebook, TW :Twitter, LI:LinkedIn, GO:Google, IG:Instagram.
App ID/API Key of your app (see step 1 above)
User’s ID in the social network
User’s social network session token for your app
Only for Twitter and LinkedIn apps. User’s session token
Only for Google. RefreshToken if access_type=offlineused (recommended).
BRANDID (Optional)
Only if you have apps for more than one brand, Xeerpa Brand’s id
ID (Optional)
Used to store the user’s CRM id, when available
IP (Optional)
User’s IP address, when available
Whether or not the user accepts to receive commercial communications from you or your partners. This is typically requested to the user in an opt-in checkbox in your website or app. The robinson parameter works under the following logic:

robinson=true : User doesn't want to receive commercial communications.

robinson=false : User wants to receive commercial communications.

IDDATA (Optional)
(If not specified Xeerpa's Internal app ID) Tag for parametrer DATA describing the content of DATA.
DATA (Optional)
Can be used to send Xeerpa any other information that the client would like to store associated with the user. For example, if the web or app displays a form that the user has to fill-in, these values can be sent in the DATA parameter. External data in JSON format (See Step 2 earlier in this document). Replace the & character with %26 in this parameter.
DEBUG (Optional)
For debugging purposes, send TRUE in this parameter when you are sending test requests
CONNECT (Optional)
Will call Xeerpa Connect Widgets to enrich your app with personalization. See next section for more information.
LOCS (Optional)
Will add a Location to the Geolocations Map which can be used as a filter. The format will be a JSON like this: {"id":"LOC_ID","name":"Xeerpa","lat":40.42,"lon":-3.78,"date":"2018-09-25T11:23:42.000Z","address":"the-address"}

ie You can send a WiFi ID to identify the users who logged in at a particular store. See an example below.


A successful response would be a JSON with:

"errorCode": 1,
"message": "New user successfully added to Xeerpa Connect Discovery queue“,
“query”:  {
   “clientId”: 58398f9,
   “clientPwd”: jg93j93,
   “socialNetwork”: FB,
   “appId”: 38147865,
   “userId”: 64064705,
   “userToken”: AAAFa8FEOR5kBAE6bOJ },
“queueId” : “54da2af9aa52d7f4d2f4147f”



i. An example of a basic request for a Facebook app would look like this (you can test all calls in your browser before implement them in your server):

https://URL.xeerpa.com:8443/discoveruser?clientId=58398f9&clientPwd=jg93j93&socialNetwork=FB&appId=38147865&userId=64064 705&userToken=AAAFa8FEOR5kBAE6bOJk


ii. A basic example for Twitter is shown below:

https://URL.xeerpa.com:8443/discoveruser?clientId=58398f9&clientPwd=jg93j93&socialNetwork=TW&appId=w4i2cxGYIeIjJsrJz9i4Z A5&userId=188520085&userToken=188520085_k7LqPglddAFltbclQtVKwRBP4xbVz7IoWw0z&userTokenSecret=mi1cv75O3MbzEP5QdgcnmrPFBmZ


iii. Another example with more parameters:

https://URL.xeerpa.com:8443/discoveruser?clientId=25258f9&clientPwd=jg9as&socialNetwork=FB&appId=693345372&userId=100122 1&userToken=8K9DKSM50SK&brand=a05930f94c939a4&id=5343&IP=‘purchase_0102012 ’&data={“date":12/12/2014, “amount":3231.2}&locs={"id":"FB_OR_CLIENT_ID","name":"Xeerpa","lat":40.42,"lon":-3.78,"date":"2018-09-25T11:23:42.000Z"}


Sending additional profile data to Xeerpa

Xeerpa Connect Discovery will retrieve all the user data from the social network based on the consents granted by the user in the social login process. Additionally, other information related to the user can be sent to Xeerpa so it is stored as part of the user profile. For instance, fields populated by the user in the registration form, or sales lines, can be sent into Xeerpa so they become part of the profile.

There are three ways of doing this:

1) With the DATA parameter:

https://URL.xeerpa.com:8443/discoveruser?clientId=25258...&data={“date":12/12/2014, “amount":3231.2}

Note that this method overwrites any previous data sent for the current app. To add data check the IDDATA option below.

2) With the IDDATA parameter:



This method will accumulate the values for the same user, adding the new set of data provided.



Step 3: Obtain advanced 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_friends, user_gender, user_birthday, user_location, user_posts, user_tagged_places and user_likes) - please feel free to request any further information about this Widget, contacting us through support@xeerpa.com.

Using Xeerpa Summary Widget for Facebook

Remember to contact Xeerpa in advance in order to register your app with Xeerpa Connect Widgets.

This Widget is 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.

Include a parameter called connect to your Xeerpa Discovery call (please refer to previous section). When using this parameter, Xeerpa Connect Discovery will return 2 additional parameters:

Contains all the code (Html, Javascript and CSS) necessary to render the widget in your app. Insert this code as the content of a div element (this requires that your app uses jQuery and the UTF-8 encoding).
This parameter includes the raw data of the user (email, name, location...).

Add the following parameter to your Xeerpa Connect Discovery call in order to use Xeerpa Connect Widgets:

LANG (Optional)
Language: en: English. es: Spanish. ca: Catalan. EN by default
NOQUEUE (Optional)
TRUE | FALSE. FALSE by default. If TRUE Xeerpa Connect Discovery will not process this user (use only if you'll do another call to Xeerpa).
CSS (Optional)
TRUE | FALSE. FALSE by default. If TRUE Xeerpa will send a default css.


Set the CONNECT param to the user's language LANG=“ES" or “EN" in the call to the web service described before and Xeerpa will return the HTML and CSS necessary to render the widgets. Simply transfer this HTML code to an empty div in your website or app and the widgets will be rendered. You can add your own CSS rules to override the default ones and adapt this HTML to your look&feel.

Xeerpa Connect Discovery will add this user to Xeerpa and will return a parameter called html with the code to embed into your app:

"errorCode": 1,
"message": "New user successfully added to Xeerpa Connect Discovery queue“,
“query”: {
   “clientId”: 58398f9,
   “clientPwd”: jg93j93,
   “socialNetwork”: FB,
   “appId”: 38147865,
   “userId”: 64064705,
   “userToken”: AAAFa8FEOR5kBAE6bOJ
“queueId” : “54da2af9aa52d7f4d2f4147f”,
“html” : “html goes here”,
“data” : {
   “name” : “John”,
   “surname” : “Smith”
Keep in mind
Your website must not contain any '#fb' style set in the CSS.


An example of a URL through Xeerpa Connect Discovery including the call for the Summary Widget looks like this:

https://URL.xeerpa.com:8443/discoveruser?clientId=58398f9&clientPwd=jg93j93&socialNetwork=FB&appId=38147865 &userId=-64064705&userToken=AAAF8FEOR5kBAE6bOJk&robinson=true&connect={"show":"summary","lang":"LANG"}


Processing multiple users in the same call

The Xeerpa Connect API offers the capability of processing multiple users in the same call, in order to make the process more efficient for larger volumes. Below is an example of the sintax for this call in NodeJS, note that this is a POST message instead of a GET:

  • const axios = require('axios');
    const data = {
    	brand: "BRAND",        // OPTIONAL
    	clientId: "CLIENT_ID",
    	clientPwd: "CLIENT_PWD",
    	socialNetwork: "FB",
    	appId: "APP_ID",
    		{userId:"USER_ID_1",userToken:"USER_TOKEN",id:"ID",data:{"field1": "value1","field2":"field2"}},
    		{userId:"USER_ID_2",userToken:"USER_TOKEN",id:"ID",data:{"field1": "value1","field2":"field2"}}
    async function makeGetRequest() {
    	const result = await axios.post('https://URL.xeerpa.com:8443/discoveruser', data);

Note that the recommended maximum number of profiles to be included in the same call is 100.



Q: The web service is not sending any response

A: Requests to Xeerpa are usually made to port 8443, and your server making the request must allow sending and receiving of these requests and their responses. When no response is being received, typically it is because port 8443 is not available in your server. To increase security, you can limit traffic through this port requests to and from *.xeerpa.com.

Another posible reason could be that you are using POST instead of GET as request method. Please use GET.