Eltanin Eye for Facebook

This add-on is operated by The Eltanin EYE Team

Fast and reliable recommendation engine based on social profiles for your app.

Eltanin Eye for Facebook

Last Updated: 19 March 2014

The Eltanin Eye for Facebook add-on is currently in beta.

Table of Contents

In few words

Eltanin Eye is designed as a add-on for Heroku. It can be plugged into your app and used using few steps. Once it is added it can be used via a standard RESTful Web API. You can register your products, register your users, notify which users buy which products, and ask which users will like which of your products based in their social profiles. And of course, you can use it to show lists like you should also bought this, detect strong affinities, and any other use.

Start in less than 10 steps

You can find the quick start guide in the home page.

Add to your Heroku app

Eltanin Eye is an add-on providing product suggestion for your users powered by their Facebook profiles.

Adding product suggestion to your application based on social profiles (including Facebook) you will be able to suggest the most suitables products to new users even when they have bough none of your products previously.

Eltanin Eye is accessible via a standard RESTful Web API and has supported examples and client libraries for Ruby, PHP, Node, and ShellScript.

Installing the add-on

Eltanin Eye can be attached to a Heroku application via the CLI:

A list of all plans available will be available here.

$ heroku addons:add eltanin
-----> Adding eltanin to sharp-mountain-4005... done, v18 (free)

Once Eltanin Eye has been added a ELTANIN_URL setting will be available in the app configuration and will contain the canonical URL to access to Eltanin Eye service. This can be confirmed using the heroku config:get command.

$ heroku config:get ELTANIN_URL
https://user:pass@instance.ip/resourceid

After installing Eltanin Eye the application should be configured to fully integrate with the add-on.

Local environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it's also possible to set local environment variables using export ELTANIN_URL=value.

Use Foreman to reliably configure and run the process formation specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the ELTANIN_URL values retrieved from heroku config to .env.

$ heroku config -s | grep ELTANIN_URL >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with any RESTful library

Eltanin Eye is accessible via a RESTful Web API. There are lots of REST client libraries available for any language. Some of them are:

You should also need a JSON encoder/decoder if your REST client library does not converts JSON automatically.

Further reading

  • Api to learn about available operations and semantics.
  • Also recommended to see the examples implemented with curl in the Api.

Using with PHP

PHP developers can use its own REST client library or they can use Eltanin Eye driver. Following steps are related to the driver presented.

Installing PHP driver

Download the php driver and uncompress it on your app directory.

$ wget http://www.eltanin-eye.com/downloads/php-driver.zip
$ unzip php-driver.zip

PHP driver dependences

Ensure that you have installed in your web server the cURL and JSON extensions.

Set up your app

You have to include in your PHP app the driver.

require_once("./Eltanin.php");

Connect to Eltanin Eye

Create an instance to the driver using the ELTANIN_URL.

$eltanin = new Eltanin(getenv("ELTANIN_URL"));

At this point you should be able to use the object $eltanin to access to Eltanin Eye.

Register your buyers

Register your Facebook users in Eltanin Eye using its id and token.

$facebook = new Facebook(array(      // your facebook connection
  'appId'  => getenv('FACEBOOK_APP_ID'),
  'secret' => getenv('FACEBOOK_SECRET'),
  'sharedSession' => true,
  'trustForwarded' => true,
));
$buyer = $facebook->getUser();        // get the id, and register user
$eltanin->w('buyers')->w($buyer)->put();
$token = $facebook->getAccessToken(); // get the access token, and set
$eltanin->w('buyers')->w($buyer)->w('social/fb')->put(array('fb_id'=>$buyer, 'token'=>$facebook->getAccessToken()));

Eltanin Eye check the token and obtains its Facebook profile. When this step is complete (usually few seconds) Eltanin Eye will be able to create recommendations based on the previous users and new user profile. To check that this step is complete you can get the validated field from the user:

$buyer = $facebook->getUser();
$validated = $eltanin->w('buyers')->w($buyer)->get()['validated'];

Register your products

Register your products into Eltanin Eye.

$yourProducts = array("p1", "p2"); // list your product names
foreach ($yourProducts as $product) {
  $eltanin->w('products')->w($product)->put();
}

Register products sells

Register the facebook user ids for each product.

$buyer = $facebook->getUser();     // your buyer
$product = "p1";                   // product bought
$eltanin->w('carts')->w($buyer.".".$product)->put(array("buyer"=>$buyer, "items"=>array(array("product"=>$product,"quantity"=>1))));

Ask for a recommendation

All the information is ready. Now you can ask a recommendation for a user by asking to Eltanin Eye:

$buyer = $facebook->getUser();
$recommendations = $eltanin->w('buyers')->w($buyer)->w('social-selling')->get();
echo "<pre>"; var_dump($recommendations);

Everything better with batch

Batch API avoids additional latencies and speedups all the process. Use it like doing direct calls but in a queue. All queue will be served at once. An example of simple call:

$queue = $eltanin->queue();           // create the queue
$queue->w('products')->("p1")->put(); // make call
// ... many other calls
$queue->batch();                      // send all queue

Make multiple queries and get results:

$buyer = $facebook->getUser();
$queue = $eltanin->queue();           // create the queue
$validIdx = $queue->w('buyers')->w($buyer)->get(); // query
// ... many other calls or queries
$allResults = $queue->batch();        // send all queue
$validated = $allResults[$validIdx]['result']['validated']; // get results

Deploy changes

Deploy Eltanin Eye configuration to Heroku:

$ git add Eltanin.php
$ git commit -a -m "Adding eltanin config"
$ git push heroku master
...
-----> Heroku receiving push
-----> Launching... done, v3
       http://your-app-1234.herokuapp.com deployed to Heroku

To git@heroku.com:your-app-1234.git
 * [new branch]      master -> master

Configuration of the add-on can be confirmed by running:

$ heroku run confirmation command

Further reading

Using with Ruby

Ruby developers can use its own REST client library or they can use Eltanin Eye driver. Following steps are related to the driver presented.

Install Ruby driver

The Eltanin Eye ruby driver is available as the eltanin gem.

Update the Gemfile

Applications will need to add the following entry into their Gemfile specifying eltanin REST client library.

gem "eltanin"

Install required gems

You can add eltanin gem to your development machine with the following command:

$ gem install eltanin
$ bundle install

Set up your app

You have to include in your ruby app the driver.

require "eltanin"

Connect to Eltanin Eye

Create an instance to the driver using the ELTANIN_URL.

$eltanin = Eltanin.eye(ENV["ELTANIN_URL"])

At this point you should be able to use the object $eltanin to access to Eltanin Eye.

Register your users

Register your Facebook users in Eltanin Eye using its id and token.

@buyer = session[:buyer]         # your user id
@fb_id = session[:fb_id]         # facebook user id
@token = session[:access_token]  # access token for this user
$eltanin[:buyers][@buyer].put
$eltanin[:buyers][@buyer]["social/fb"].put({:fb_id=>@fb_id,:token=>session[:access_token]})

Eltanin Eye check the token and obtains its Facebook profile. When this step is completed (usually few seconds) Eltanin Eye will be able to create recommendations based on the previous users and new user profile. To check if this step is finished you can get the validated field from the user:

@buyer = session[:buyer]
@validated = $eltanin[:buyers][@buyer].get()['validated']

Register your products

Register your products into Eltanin Eye.

@yourProducts = [ "p1", "p2" ] # list your product names
@yourProducts.each { |product|
   $eltanin[:products][product].put
}

Register products buyers

Register the facebook user ids for each product.

@buyer = session[:buyer] # current buyer
@product = "p1";         # your product name
@buyers = ["35", "78"];  # product current buyers ids
$eltanin[:carts][""+@buyer+"."+product].put({"buyer"=>@buyer,"items"=>["product"=>@product,"quantity"=>1]})

Ask for a recommendation

All the information is ready. Now you can ask a recommendation for a user by asking to Eltanin Eye:

@buyer = session[:buyer]
@recommendations = $eltanin[:buyers][@buyer]['social-selling'].get
yourDisplayFunction @recommendations

Everything better with batch

Batch API avoids additional latencies and speedups all the process. Use it like doing direct calls but in a queue. All queue will be served at once. An example of simple call:

$queue = $eltanin.queue()   # create the queue
$queue[:products]["p1"].put # make call
// ... many other calls
$queue.batch                # send all queue

Make multiple queries and get results:

@buyer = session[:buyer]
$queue = $eltanin.queue()            # create the queue
@validIdx = $queue[:buyers][@buyer].get
// ... many other calls or queries
allResults = $queue.batch           # send all queue
@validated = allResults[$validIdx]['result']['validated']; # get results

Deploy changes

Deploy Eltanin Eye configuration to Heroku:

$ git commit -a -m "Adding eltanin config"
$ git push heroku master
...
-----> Heroku receiving push
-----> Launching... done, v3
       http://your-app-1234.herokuapp.com deployed to Heroku

To git@heroku.com:your-app-1234.git
 * [new branch]      master -> master

Configuration of the add-on can be confirmed by running:

$ heroku run confirmation command

On Heroku, configuration is managed via configuration variables. No configuration files with sensitive information should ever be required within the application source and required config values should be read in from the ENV by supported libraries.

Further reading

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade eltanin:newplan
-----> Upgrading eltanin:newplan to your-app-1234... done, v18 ($49/mo)
       Your plan has been updated to: eltanin:newplan

Removing the add-on

Eltanin Eye can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove eltanin
-----> Removing eltanin from your-app-1234... done, v20 (free)

Support

All Eltanin Eye support and runtime issues should be submitted via on of the Eltanin Support channels. Any non-support related issues or product feedback is welcome at Eltanin Eye home.

Additional resources

Additional resources are available at: