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 January 30, 2017
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
The Eltanin Eye for Facebook add-on is currently in beta.
Table of Contents
In few words
Eltanin Eye is an 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:create 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 the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env
file. To view all of your app’s config vars, type heroku config
. Use the following command to add the ELTANIN_URL values retrieved from heroku config to your .env
file.
$ 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
.
For more information, see the Heroku Local article.
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
- Eltanin Eye REST API to learn about available operations and results.
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
- Eltanin Eye REST API to learn about available operations and results.
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:destroy 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: