Skip to content

Commit 791e8ae

Browse files
OndraFiedlerOndraFiedler
committed
js client for Recombee recommendation API
0 parents  commit 791e8ae

30 files changed

+8351
-0
lines changed

‎.gitignore

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
8+
# Runtime data
9+
pids
10+
*.pid
11+
*.seed
12+
*.pid.lock
13+
14+
# Directory for instrumented libs generated by jscoverage/JSCover
15+
lib-cov
16+
17+
# Coverage directory used by tools like istanbul
18+
coverage
19+
20+
# nyc test coverage
21+
.nyc_output
22+
23+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
24+
.grunt
25+
26+
# Bower dependency directory (https://bower.io/)
27+
bower_components
28+
29+
# node-waf configuration
30+
.lock-wscript
31+
32+
# Compiled binary addons (https://nodejs.org/api/addons.html)
33+
build/Release
34+
35+
# Dependency directories
36+
node_modules/
37+
jspm_packages/
38+
39+
# TypeScript v1 declaration files
40+
typings/
41+
42+
# Optional npm cache directory
43+
.npm
44+
45+
# Optional eslint cache
46+
.eslintcache
47+
48+
# Optional REPL history
49+
.node_repl_history
50+
51+
# Output of 'npm pack'
52+
*.tgz
53+
54+
# Yarn Integrity file
55+
.yarn-integrity
56+
57+
# dotenv environment variables file
58+
.env
59+
60+
# parcel-bundler cache (https://parceljs.org/)
61+
.cache
62+
63+
# next.js build output
64+
.next
65+
66+
# nuxt.js build output
67+
.nuxt
68+
69+
# vuepress build output
70+
.vuepress/dist
71+
72+
# Serverless directories
73+
.serverless
74+
75+
# FuseBox cache
76+
.fusebox/

‎.neutrinorc.js

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
module.exports = {
2+
use: [
3+
['@neutrinojs/fork', {
4+
configs: {
5+
minified: {
6+
use: [
7+
(neutrino) => {
8+
lib = require('./../../../util/neutrino-library');
9+
10+
lib(neutrino, {
11+
name: 'recombee',
12+
filename: 'recombee-api-client.min.js',
13+
minify: true,
14+
target: 'web',
15+
externals: {
16+
whitelist: ['jssha']
17+
},
18+
babel: {
19+
presets: [
20+
['babel-preset-env', {
21+
targets: {
22+
browsers: [
23+
'last 2 Chrome versions',
24+
'last 2 Firefox versions',
25+
'last 2 Edge versions',
26+
'last 2 Opera versions',
27+
'last 2 Safari versions',
28+
'last 2 iOS versions',
29+
'> 2% in BE'
30+
]
31+
}
32+
}]
33+
]
34+
}
35+
});
36+
}
37+
]
38+
},
39+
40+
nonminified: {
41+
use: [
42+
(neutrino) => {
43+
lib = require('./../../../util/neutrino-library');
44+
45+
lib(neutrino, {
46+
name: 'recombee',
47+
filename: 'recombee-api-client.js',
48+
minify: false,
49+
target: 'web',
50+
externals: {
51+
whitelist: ['jssha'],
52+
},
53+
babel: {
54+
presets: [
55+
['babel-preset-env', {
56+
targets: {
57+
browsers: [
58+
'last 2 Chrome versions',
59+
'last 2 Firefox versions',
60+
'last 2 Edge versions',
61+
'last 2 Opera versions',
62+
'last 2 Safari versions',
63+
'last 2 iOS versions',
64+
'> 2% in BE'
65+
]
66+
}
67+
}]
68+
]
69+
}
70+
});
71+
}
72+
]
73+
},
74+
}
75+
}]
76+
]
77+
};

‎README.md

+237
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# Recombee API Client
2+
3+
A javascript library for easy use of the [Recombee](https://www.recombee.com/) recommendation API.
4+
5+
It is intended for usage in browsers and other client side integrations (such as in React Native / NativeScript mobile apps). For Node.js SDK please see [this repository](https://github.com/recombee/node-api-client).
6+
7+
Documentation of the API can be found at [docs.recombee.com](https://docs.recombee.com/).
8+
9+
## Installation
10+
11+
The library is [UMD](https://github.com/umdjs/umd) compatible.
12+
13+
### <script> tag
14+
15+
You can download [recombee-api-client.min.js](./dist/recombee-api-client.min.js) and host it at your site, or use a CDN such as [jsDelivr](https://www.jsdelivr.com/) CDN:
16+
17+
```js
18+
<script src="https://cdn.jsdelivr.net/gh/recombee/[email protected]/dist/recombee-api-client.min.js"></script>
19+
```
20+
21+
### npm
22+
Use `npm` also for React Native / NativeScript applications.
23+
```
24+
npm install recombee-js-api-client --save
25+
```
26+
27+
### Bower
28+
29+
```
30+
bower install recombee-js-api-client -S
31+
32+
```
33+
34+
## How to use
35+
36+
This library allows you to request recommendations and send interactions between users and items (views, bookmarks, purchases ...) to Recombee. It uses the **public token** for authentication.
37+
38+
It is intentionally not possible to change item catalog (properties of items) with public token, so you should use one of the following ways to send it to Recombee:
39+
40+
- Use one of the server-side SDKs (Node.js, PHP, Java...). The synchronization can done for example by a peridodically ran script. See [this section](https://docs.recombee.com/gettingstarted.html#managing-item-catalog) for more details.
41+
- Set a product feed at [Recombee web admin](https://admin.recombee.com/).
42+
43+
### Sending interactions
44+
45+
```javascript
46+
// Initialize client with name of your database and PUBLIC token
47+
var client = new recombee.ApiClient('name-of-your-db', '...db-public-token...');
48+
49+
//Interactions take Id of user and Id of item
50+
client.send(new recombee.AddBookmark('user-13434', 'item-256'));
51+
client.send(new recombee.AddCartAddition('user-4395', 'item-129'));
52+
client.send(new recombee.AddDetailView('user-9318', 'item-108'));
53+
client.send(new recombee.AddPurchase('user-7499', 'item-750'));
54+
client.send(new recombee.AddRating('user-3967', 'item-365', 0.5));
55+
client.send(new recombee.SetViewPortion('user-4289', 'item-487', 0.3));
56+
57+
```
58+
59+
### Requesting recommendations
60+
61+
You can [recommend items to user](https://docs.recombee.com/api.html#recommend-items-to-user) or [recommend items to item](https://docs.recombee.com/api.html#recommend-items-to-item).
62+
63+
It is possible to use callbacks or Promises.
64+
65+
#### Callback
66+
Callback function take two parameters:
67+
68+
- *err* - `null` if request succeeds or `Error` object
69+
- *res* - object containg reply from Recombee
70+
71+
```javascript
72+
73+
var callback = function (err, res) {
74+
if(err) {
75+
console.log(err);
76+
// use fallback ...
77+
return;
78+
}
79+
console.log(res.recomms);
80+
}
81+
82+
// Get 5 recommendations for user-13434
83+
client.send(new recombee.RecommendItemsToUser('user-13434', 5), callback);
84+
```
85+
86+
87+
#### Promise
88+
89+
```javascript
90+
// Get 5 recommendations related to 'item-365' viewed by 'user-13434'
91+
client.send(new recombee.RecommendItemsToItem('item-356', 'user-13434', 5))
92+
.then(function(res) {
93+
console.log(res.recomms);
94+
})
95+
.catch(function(error) {
96+
console.log(error);
97+
// use fallback ...
98+
});
99+
100+
```
101+
102+
#### Optional parameters
103+
Recommendation requests accept various optional parameters (see [the docs](https://docs.recombee.com/api.html#recommendations)). Following example shows some of them:
104+
105+
```javascript
106+
client.send(new recombee.RecommendItemsToUser('user-13434', 5,
107+
{
108+
returnProperties: true, // Return properties of the recommended items
109+
includedProperties: ['title', 'img_url', 'url', 'price'], // Use these properties to show
110+
// the recommended items to user
111+
filter: "'title' != null AND 'availability' == \"in stock\"",
112+
// Recommend only items with filled title
113+
// which are in stock
114+
scenario: 'homepage' // Label particular usage
115+
}
116+
), callback);
117+
118+
119+
```
120+
121+
## Integration Example
122+
123+
### 1. Create instant account at recombee.com
124+
125+
126+
### 2. Upload items catalog
127+
You can use a [script](https://docs.recombee.com/gettingstarted.html#managing-item-catalog) or set a product feed at [Recombee web admin](https://admin.recombee.com/). We will set following sample Google Merchant product feed: [product_feed_sample.xml](./examples/product_feed_sample.xml).
128+
You will see the items in web interface after the feed is processed.
129+
130+
### 3. Use client to send interaction and get recommendations
131+
132+
Let's assume we want to show recommendations at product page of pants `product-270` to user with id `user-1539`. The following HTML+js sample send the detail view of the product by the user and request 3 related items from Recombee:
133+
```html
134+
<!DOCTYPE html>
135+
<html lang="en">
136+
<head>
137+
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
138+
</head>
139+
<body>
140+
<div class="container">
141+
<div class="row">
142+
<h1>Related products</h1>
143+
<div class="col-md-12">
144+
<div class="row" id='relatedProducts'>
145+
</div>
146+
</div>
147+
</div>
148+
</div>
149+
150+
<script src="https://cdn.jsdelivr.net/gh/recombee/[email protected]/dist/recombee-api-client.min.js"></script>
151+
152+
<script type="text/javascript">
153+
154+
// A simple function for rendering a box with recommended product
155+
function showProduct(title, description, link, imageLink, price){
156+
return [
157+
'<div class="col-md-4 text-center col-sm-6 col-xs-6">',
158+
' <div class="thumbnail product-box" style="min-height:300px">',
159+
' <img src="' + imageLink +'" alt="" />',
160+
' <div class="caption">',
161+
' <h3><a href="' + link +'">' + title + '</a></h3>',
162+
' <p>Price : <strong>$ ' + price + '</strong> </p>',
163+
' <p>' + description+ '</p>',
164+
' <a href="' + link +'" class="btn btn-primary" role="button">See Details</a></p>',
165+
' </div>',
166+
' </div>',
167+
'</div>'
168+
].join("\n")
169+
}
170+
171+
// Initialize client
172+
var client = new recombee.ApiClient('js-client-example', 'dXx2Jw4VkkYQP1XU4JwBAqGezs8BNzwhogGIRjDHJi39Yj3i0tWyIZ0IhKKw5Ln7');
173+
174+
var itemId = 'product-270';
175+
var userId = 'user-1539'
176+
177+
// Send detail view
178+
client.send(new recombee.AddDetailView(userId, itemId));
179+
180+
// Request recommended items
181+
client.send(new recombee.RecommendItemsToItem(itemId, userId, 3,
182+
{
183+
returnProperties: true,
184+
includedProperties: ['title', 'description', 'link', 'image_link', 'price'],
185+
filter: "'title' != null AND 'availability' == \"in stock\"",
186+
scenario: 'related_items'
187+
}),
188+
(err, resp) => {
189+
if(err) {
190+
console.log("Could not load recomms: ", err);
191+
return;
192+
}
193+
// Show recommendations
194+
var recomms_html = resp.recomms.map(r => r.values).
195+
map(vals => showProduct(vals['title'], vals['description'],
196+
vals['link'], vals['image_link'], vals['price']));
197+
document.getElementById("relatedProducts").innerHTML = recomms_html.join("\n");
198+
}
199+
);
200+
</script>
201+
202+
</body>
203+
</html>
204+
```
205+
You should see something like this:
206+
207+
<a href="./examples/related_products.png"><img src="./examples/related_products.png" alt="Related products" width="500"/></a>
208+
209+
210+
Please notice how the properties returned by `returnProperties`&`includedProperties` were used to show titles, images, descriptions and URLs.
211+
212+
### Remark on user identification
213+
214+
In order to achieve personalization, you need a unique identifier for each user. An easy way can be using Google Analytics for this purpose. The example then becomes:
215+
```javascript
216+
ga('create', 'UA-XXXXX-Y', 'auto'); // Create a tracker if you don't have one
217+
// Replace the UA-XXXXX-Y with your UA code from Google Analytics.
218+
219+
var client = new recombee.ApiClient('js-client-example', 'dXx2Jw4VkkYQP1XU4JwBAqGezs8BNzwhogGIRjDHJi39Yj3i0tWyIZ0IhKKw5Ln7');
220+
221+
ga(function(tracker) {
222+
var userId = tracker.get('clientId'); // Get id from GA
223+
224+
client.send(new recombee.RecommendItemsToUser(userId, 3,
225+
{
226+
returnProperties: true,
227+
includedProperties: ['title', 'description', 'link', 'image_link', 'price'],
228+
filter: "'title' != null AND 'availability' == \"in stock\"",
229+
scenario: 'homepage'
230+
}),
231+
(err, resp) => { ... }
232+
);
233+
});
234+
235+
```
236+
237+
This time [RecommendItemsToUser](https://docs.recombee.com/api.html#recommend-items-to-user) is used - it can be used for example at your homepage.

0 commit comments

Comments
 (0)