Loading...
 

Connect Widgets

Xeerpa Recommender:

In order to comply with certain social networks' use cases and policies (namely Facebook, Instagram and Google), websites implemmeting social login with these networks must implement a personalised content recomendations feature. The Xeerpa Recommender widget provides such functionality.

It consists of a content slider or mosaic which is returned by Xeerpa as a JSON string with HTML code, showing relevant content recommendations based on all the information the user has accepted to share with the brand. The HTML can be inserted in an empty  div element and requires jQuery and UTF-8 encoding.

Currently, the widget can recommend content based on: likes and preferences, geolocations, posts, gender and age. These content recommendations must be provided by the client so it can be configured in the widget by the Xeerpa team.

The recommended content consists of:

- One working URL for each recommended content

- One 580x290px / 72ppp resolution relevant image for each URL

Recommended content should include at least:

  • Two slides for gender (one for male users, one for female users)
  • Three slides for age (for different over 18 generations)
  • Five slides for interests (one for each Xeerpa categories group: "Household", "Leisure", "Art & Beauty", "Industry & Digital World", "Lifestyle")
  • As many slides as possible for geolocations. These should recommend places to visit which are relevant to the client and close to user's location (i.e. stores, bars, stadiums, etc.)

This is how the Xeerpa Recommender looks like with some content examples:

Home screen:

1

Age based content:

2

Gender based content:

3

Geolocation based content:

4

Likes/posts based content:

5

 

Technical details:

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


How to implement the Xeerpa Recommender:

Using the Xeerpa Connect Back-Auth method

https://auth-CLIENTURL/widgets/summary?id=AU_ID&token=AU_TOKEN&lang=LANG&socialNetwork=SOCIALNETWORK

Using the Xeerpa Connect Discovery method

Option A ) https://CLIENTURL:8443/discoveruser?clientId=CLIENTID&clientPwd=CLIENTPWD&socialNetwork=SOCIALNETWORK&appId=APPID&userId=USERID&userToken=USERTOKEN&connect={"show":"summary", "lang":"es"}

Option B ) https://
CLIENTURL:8443/widgets/summary?clientId=CLIENTID&clientPwd=CLIENTPWD&appId=APPID&userId=USERID&userToken=USERTOKEN&socialNetwork=SOCIALNETWORK
Important
Remember that all calls to the Xeerpa API must be done server-to-server.
CLIENTURL
CLIENTURL will be provided when we register in Xeerpa.
NAME
Name of widget to call:
Summary: This widget will show basic data, preferences and locations of your user.
CLIENTID
CLIENTID will be provided when we register in Xeerpa.
CLIENTPWD
CLIENTPWD will be provided when we register in Xeerpa. 
APPID
App ID/Key of your app.

 

ID
User’s Xeerpa ID provided by Xeerpa on data.id
TOKEN
User’s Xeerpa token provided by Xeerpa on data.token
USERID
User's ID in the Social Network
USERTOKEN
User’s social network session token for your app
LANG (optional)
Language: en: English (default) , es: Spanish,  sr: Serbian

 

SOCIALNETWORK (required)
FB: Facebook, IG: Instagram, GO: Google

 

 

Xeerpa Connect Widgets will return a JSON string with a parameter called orwith the code to embed into your app:

html
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 (requires that your app uses jQuery and the UTF-8 encoding).

 

A successful response would be a JSON with:

{"errorCode":1,
"html":"HTML-CODE-HERE"}

An example of a call for the Xeerpa Recommender through Xeerpa Connect BackAuth looks like this:

https://auth-CLIENTURL/widgets/summary?id=au_gfdskhgfirjiwgkds&token=fhu349GYUgd7sgfugFSOFKIHEWOIUjgfkjsoh&lang=en&socialNetwork=GO

An example of an URL through Xeerpa Connect Discovery including the call for the Xeerpa Recommender looks like this:

https://CLIENTURL:8443/wigets/summary?clientId=58398f9&clientPwd=jg93j93&socialNetwork=IG&appId=38147865 &userId=-64064705&userToken=AAAF8FEOR5kBAE6bOJk

*Xeerpa Recommender can also be requested through a request to /discoveruser endpoint, adding connect={"show":"summary"} to the query.

 

 

 

Proximity Widget:

The Proximity Widget will recommend stores, bars, or locations from a list predefined by the Client after the user logs in, based on the user's locations history.

You can customize the parameters of the call with the specific parameters of the Proximity Widget:

IDAREA (Optional)
1 by default. If the brand sets up locations, for example in Madrid and Barcelona, 1=Madrid and 2=Barcelona.
PRETTY (Optional)
Will send the JSON response with HTML format to make it easier be read. For testing purposes only.

 

- PRECONFIGURATION IN DASHBOARD:

Xeerpa will need a JSON with this structure:

Address and fbid are Optional parameters.

YearsAgo is used to establish the maximum antiquity of the location.

Each item.loc must be in <long, lat> format.

[{

    "idArea":1

    "name": "Bares Madrid",
    "yearsAgo": 1.5,
    "items":[

        {
            "fbid": "194047290628",
            "name": "EL VIAJERO MADRID",
            "address": "Plaza de la Cebada, 11 28005 Madrid Spain",
            "loc": -3.435342, 40.875675
        },
        {
            "fbid": "125524167491802",
            "name": "KIKEKELLER",
            "address": "corredera baja de san pablo 17 28004 Madrid Spain",
            "loc": -3.5634562, 40.454232

        }
},{

    "idArea":2,
    "name": "Bares Barcelona",
    "yearsAgo": 1.5,
    "items":[

        {
            "fbid": "223768944302469",
            "name": "Restaurante La Cava del Faraón",
            "address": "Calle de Segovia, 8 28005 Madrid Spain",
            "loc": -3.93532, 40.235746

        },
        {
            "fbid": "272280762853",
            "name": "Le Cabrera",
            "address": "Barbara de Braganza nº 2 28004 Madrid Spain",
            "loc": -3.562665, 40.4567547
        }    
}]

 - OUTPUT:

After the user logs in, a JSON array will be generated with the following format:

Top recommendations will be sorted by class (recommendation level). The class will depend on the density of the locs of the user, near a specific location.

These classes can be A-E.

[ {
        spot: {
            name: EL VIAJERO MADRID,
            loc: -3.435342, 40.875675
            fbid: 194047290628
        },
        'class': 'A'
    },
    {
        spot: {
            name: BAR PIRULETA MADRID,
            loc: -3.5634562, 40.454232
            fbid: 125524167491802
        },
        'class': 'C'
    },
    {
        spot: {
            name: La Candelita,
            loc: -3.743523, 40.24657
            fbid: 194047290628
        },
        'class': 'D'
    }
]

An example of a call for the Proximity Widget through Xeerpa Connect Backend Auth PHPs looks like this:

https://auth-CLIENTURL/widgets/proximity?id=au_gfdskhgfirjiwgkds&token=fhu349GYUgd7sgfugFSOFKIHEWOIUjgfkjsoh&lang=EN&idArea=1&pretty=true

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

https://CLIENTURL:8443/widgets/proximity?clientId=58398f9&clientPwd=jg93j93&socialNetwork=FB&appId=38147865 &userId=-64064705&userToken=AAAF8FEOR5kBAE6bOJk&robinson=true&connect={"show":"proximity","lang":"EN","idArea":"1","pretty":"true"}

 

Engagement Widget: 

The Engagement Widget will show which Communities the user is already following and which not, from a list predefined by the Client.

- PRECONFIGURATION IN DASHBOARD:

You can optionally choose the Likes in the Dashboard menu.

- OUTPUT:

{
    likes: {
        0: {
            fbid: '829572895749',
            item: 'Cristiano Ronaldo'
        },
        1: {
            fbid: '4624426264',
            item: 'Real Madrid CF'
        },
        2: {
            fbid: '464236436',
            item: ' Sergio Ramos'
        }
    },
    notLikesYet: {
        0: {
            fbid: '49083905',
            item: 'Lucas Vz'
        },
        1: {
            fbid: '9406378349063',
            item: 'FCB'
        }
    }
}

An example of a call for the Engagement Widget through Xeerpa Connect Backend Auth PHPs looks like this:

https://auth-CLIENTURL/widgets/engagement?id=au_gfdskhgfirjiwgkds&token=fhu349GYUgd7sgfugFSOFKIHEWOIUjgfkjsoh

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

https://CLIENTURL:8443/widgets/engagement?clientId=58398f9&clientPwd=jg93j93&socialNetwork=FB&appId=38147865 &userId=-64064705&userToken=AAAF8FEOR5kBAE6bOJk&robinson=true&connect={"show":"engagement"}

 

Interests Widget:

 The Interests Widget will provide data about the (sub)categories a particular user has shown more interest on.

 You can customize the parameters of the call with the specific parameters of the Interests Widget:

LANG (optional)
Language: en: English. es: Spanish. ca: Catalan. en by default

 

- OUTPUT:

After he logs in, a JSON array will be generated with the following format:

{
    0: {
        subcategory: "Magazines",
        value: 9.6,
        category: "Media"
    },
    1: {
        subcategory: "Arts and Culture",
        value: 8.5,
        category: "Arts and Culture"
    },
    2: {
        subcategory: "Toys",
        value: 7.9,
        category: "Children"
    },
    3: {
        subcategory: "Education",
        value: 6.6,
        category: "Arts and Culture"
    },
    4: {
        subcategory: "NGOs",
        value: 6.5,
        category: "NGO and Causes"
    },

    ...

    179: {
        subcategory: 'Basketball',
        value: 0,
        category: 'Sport'
    },
    180: {
        subcategory: 'Vegan products',
        value: 0,
        category: 'Food'
    }
}

 An example of a call for the Interests Widget through Xeerpa Connect Backend Auth PHPs looks like this:

https://auth-CLIENTURL/widgets/interests?clientId=58398f9&clientPwd=jg93j93&socialNetwork=FB&appId=38147865 &id=au_gfdskhgfirjiwgkds&token=fhu349GYUgd7sgfugFSOFKIHEWOIUjgfkjsoh&lang=EN

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

https://CLIENTURL:8443/widgets/interests?clientId=58398f9&clientPwd=jg93j93&socialNetwork=FB&appId=38147865 &userId=-64064705&userToken=AAAF8FEOR5kBAE6bOJk&robinson=true&connect={"show":"interests","lang":"en"}

 

Social Groups Widget:

 The Social Groups Widget will provide aggregated data about each user's interests. A Social Group is a set of subcategories predefined by the Client.

 You can customize the parameters of the call with the specific parameters of the Social Groups Widget:

LANG (optional)
Language: en: English. es: Spanish. ca: Catalan. en by default

 

 

- PRECONFIGURATION IN DASHBOARD:

The Client will set up the Social Groups in the Dashboard menu with 4 to 8 subcategories in each one.

 

- OUTPUT:

After the user logs in, a JSON array will be generated with the following format:

The levels can be A-E.

{
    0: {
        group: 'Futboleros Cerveceros',
        level: 'A'
    },
    1: {
        group: 'Runners Sin Lactosa',
        level: 'B'
    },
    2: {
        group: 'Hipsters',
        level: 'E'
    }
}

An example of a call for the Social Groups Widget through Xeerpa Connect Backend Auth PHPs looks like this:

https://auth-CLIENTURL/widgets/socialgroups?clientId=58398f9&clientPwd=jg93j93&socialNetwork=FB&appId=38147865 &id=au_gfdskhgfirjiwgkds&token=fhu349GYUgd7sgfugFSOFKIHEWOIUjgfkjsoh&lang=EN

An example of an URL through Xeerpa Connect Discovery including the call for the Social Groups Widget looks like this:

https://CLIENTURL:8443/widgets/socialgroups?clientId=58398f9&clientPwd=jg93j93&socialNetwork=FB&appId=38147865 &userId=-64064705&userToken=AAAF8FEOR5kBAE6bOJk&robinson=true&connect={"show":"socialgroups","lang":"en"}