Skip to content

Commit 6c4ac85

Browse files
mstierankamstieranka
committed
Rewrite README
1 parent 506ee19 commit 6c4ac85

File tree

1 file changed

+84
-254
lines changed

1 file changed

+84
-254
lines changed

‎README.md‎

Lines changed: 84 additions & 254 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,47 @@
1-
# Recombee API Client
1+
<div align="center">
2+
<img src="https://raw.githubusercontent.com/recombee/.github/refs/heads/main/assets/mark.svg" width="64px" align="center" alt="Recombee" />
3+
<br/>
4+
<h1>Recombee API Client</h1>
5+
</div>
26

3-
A javascript library for easy use of the [Recombee](https://www.recombee.com/) recommendation API.
7+
<p align="center">
8+
<a href="https://www.npmjs.com/package/recombee-js-api-client" rel="nofollow"><img src="https://img.shields.io/npm/v/recombee-js-api-client" alt="Version"></a>
9+
<a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/npm/l/recombee-js-api-client" alt="License"></a>
10+
</p>
411

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).
12+
<div align="center">
13+
<a href="https://docs.recombee.com/js_client">Documentation</a>
14+
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
15+
<a href="https://github.com/recombee/js-api-client/issues/new">Issues</a>
16+
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
17+
<a href="mailto:[email protected]">Support</a>
18+
<br />
19+
</div>
620

7-
Documentation of the API can be found at [docs.recombee.com](https://docs.recombee.com/).
21+
## ✨ Features
822

9-
## Installation
23+
- Thin JavaScript wrapper around the Recombee API
24+
- Supported endpoints: [Interactions](https://docs.recombee.com/api#user-item-interactions), [Recommendations](https://docs.recombee.com/api#recommendations) & [Search](https://docs.recombee.com/api#search)
25+
- UMD-compatible
26+
- TypeScript definitions included
1027

11-
The library is [UMD](https://github.com/umdjs/umd) compatible.
28+
## 🚀 Getting Started
1229

13-
### &lt;script&gt; tag
30+
There are two ways to include the library in your project:
1431

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:
32+
### 🔌 Install via code snippet
1633

17-
```js
18-
<script src="https://cdn.jsdelivr.net/gh/recombee/[email protected]/dist/recombee-api-client.min.js"></script>
34+
You can add the following `<script>` tag into your HTML file:
35+
36+
```html
37+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/recombee-api-client.min.js"></script>
1938
```
2039

21-
and use the global `recombee` object.
40+
After this script is included, you can access the client using the global `recombee` object (also available as `window.recombee`).
41+
42+
### 📦 Install via package manager
2243

23-
### Package managers
44+
If you prefer, you can also use a package manager:
2445

2546
```sh
2647
npm install recombee-js-api-client
@@ -32,269 +53,78 @@ pnpm add recombee-js-api-client
3253
bun add recombee-js-api-client
3354
```
3455

35-
and import into your code using
56+
Afterwards, you can import the `recombee` object:
3657

3758
```js
3859
import recombee from 'recombee-js-api-client'
39-
// or
40-
const recombee = require('recombee-js-api-client');
4160
```
4261

43-
The library ships with types, so you should get autocomplete in your IDE out of the box.
44-
If you're using TypeScript, it should recognize these correctly and warn you about any type errors.
45-
46-
## How to use
47-
48-
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.
49-
50-
It is intentionally not possible to change the item catalog (properties of items) with the public token, so you should use one of the following ways to send it to Recombee:
51-
52-
- Use one of the server-side SDKs (Node.js, PHP, Java...). The synchronization can done for example by a peridodically run script. See [this section](https://docs.recombee.com/gettingstarted.html#managing-item-catalog) for more details.
53-
- Set a catalog feed at [Recombee web admin](https://admin.recombee.com/).
54-
55-
### Sending interactions
56-
57-
```javascript
58-
// Initialize client with name of your database and PUBLIC token
59-
const client = new recombee.ApiClient('name-of-your-db', '...db-public-token...', {region: 'us-west'});
60-
61-
// Interactions take the ID of the user and the ID of the item
62-
client.send(new recombee.AddBookmark('user-13434', 'item-256'));
63-
client.send(new recombee.AddCartAddition('user-4395', 'item-129'));
64-
client.send(new recombee.AddDetailView('user-9318', 'item-108'));
65-
client.send(new recombee.AddPurchase('user-7499', 'item-750'));
66-
client.send(new recombee.AddRating('user-3967', 'item-365', 0.5));
67-
client.send(new recombee.SetViewPortion('user-4289', 'item-487', 0.3));
68-
```
69-
70-
### Requesting recommendations
71-
72-
You can [recommend items to user](https://docs.recombee.com/api.html#recommend-items-to-user), [recommend items to item](https://docs.recombee.com/api.html#recommend-items-to-item) or even [recommend Item Segments](https://docs.recombee.com/api#recommend-item-segments-to-user) such as categories, genres or artists.
73-
74-
It is possible to use Promises or callbacks.
62+
### 🏗️ Example
7563

76-
#### Promise
64+
With the `recombee` object, you can send user-item interactions and receive recommendations as follows:
7765

78-
```javascript
79-
// Get 5 recommendations related to 'item-365' viewed by 'user-13434'
80-
const response = await client.send(
81-
new recombee.RecommendItemsToItem("item-356", "user-13434", 5)
82-
);
83-
// or
84-
client
85-
.send(new recombee.RecommendItemsToItem("item-356", "user-13434", 5))
86-
.then(function (res) {
87-
console.log(res.recomms);
88-
})
89-
.catch(function (error) {
90-
console.log(error);
91-
// use fallback...
92-
});
93-
```
94-
95-
#### Callback
96-
97-
Callback function take two parameters:
98-
99-
- _err_ - `null` if request succeeds or `Error` object
100-
- _res_ - object containg reply from Recombee
101-
102-
```javascript
103-
const callback = function (err, res) {
104-
if (err) {
105-
console.log(err);
106-
// use fallback ...
107-
return;
108-
}
109-
console.log(res.recomms);
110-
};
111-
112-
// Get 5 recommendations for user-13434
113-
client.send(new recombee.RecommendItemsToUser("user-13434", 5), callback);
114-
```
115-
116-
### Personalized search
117-
118-
[Personalized full-text search](https://docs.recombee.com/api.html#search-items) is requested in the same way as recommendations.
119-
120-
#### Promise
121-
122-
```javascript
123-
const searchQuery = " ... search query from search field ....";
124-
const response = await client.send(
125-
new recombee.SearchItems("user-13434", searchQuery, 5)
66+
```js
67+
// Initialize the API client with the ID of your database and the associated PUBLIC token
68+
export const client = new recombee.ApiClient(
69+
'database-id',
70+
'...db-public-token...',
71+
{
72+
// the region of your database (default: 'eu-west')
73+
region: 'us-west',
74+
},
12675
);
127-
// or
128-
client
129-
.send(new recombee.SearchItems("user-13434", searchQuery, 5))
130-
.then(function (res) {
131-
console.log(res.recomms);
132-
})
133-
.catch(function (error) {
134-
console.log(error);
135-
// use fallback...
136-
});
137-
```
138-
139-
#### Callback
140-
141-
```javascript
142-
const searchQuery = " ... search query from search field ....";
143-
client.send(new recombee.SearchItems("user-13434", searchQuery, 5), callback);
144-
```
145-
146-
### Recommend Next Items
147-
148-
Recombee can return items that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (infinite scroll) or goes to the next page. See [Recommend next items](https://docs.recombee.com/api.html#recommend-next-items) for more info.
14976

150-
```javascript
151-
const initialRecomms = await client.send(
152-
new recombee.RecommendItemsToUser("user-13434", 5)
77+
// Send interactions
78+
client.send(
79+
new recombee.AddDetailView('user-4395', 'item-129', {
80+
cascadeCreate: true,
81+
recommId: '23eaa09b-0e24-4487-ba9c-8e255feb01bb',
82+
}),
15383
);
154-
// Get next 3 recommended items as user-13434 is scrolling the page down
155-
const nextRecomms = await client.send(
156-
new recombee.RecommendNextItems(initialRecomms.recommId, 3)
157-
// notice we're using recommId from previous request ^
158-
);
159-
```
160-
161-
### Optional parameters
162-
163-
Recommendation requests accept various optional parameters (see [the docs](https://docs.recombee.com/api.html#recommendations)). Following example shows some of them:
164-
165-
```javascript
166-
client.send(new recombee.RecommendItemsToUser('user-13434', 5,
167-
{
168-
scenario: 'homepage', // Label particular usage. You can assign various settings
169-
// for each scenario in the Admin UI (https://admin.recombee.com/).
170-
returnProperties: true, // Return properties of the recommended items
171-
includedProperties: ['title', 'img_url', 'url', 'price'], // Use these properties to show
172-
// the recommended items to user
173-
filter: "'title' != null AND 'availability' == \"in stock\""
174-
// Recommend only items with filled title
175-
// which are in stock
176-
}
177-
), callback);
178-
17984

85+
// Request recommendations
86+
client
87+
.send(
88+
new recombee.RecommendItemsToItem('item-356', 'user-13434', 5, {
89+
returnProperties: true,
90+
includedProperties: ['title'],
91+
}),
92+
)
93+
.then((response) => {
94+
// `recommId` needs to be sent with interactions based on recommendations
95+
console.log(response.recommId);
96+
97+
// The `recomms` object contains the `id` (and `values` if `returnProperties` is true)
98+
response.recomms.forEach((item) => {
99+
console.log(`ID: ${item.id}, Title: ${item.values.title}`);
100+
});
101+
})
102+
.catch((error) => {
103+
console.log(error);
104+
// use fallback...
105+
});
180106
```
181107

182-
## Integration Example
183-
184-
### 1. Create instant account at recombee.com
185-
186-
### 2. Upload items catalog
187-
188-
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).
189-
You will see the items in web interface after the feed is processed.
190-
191-
### 3. Use client to send interaction and get recommendations
108+
## 📝 Documentation
192109

193-
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:
110+
Discover the full [JavaScript API Client documentation](https://docs.recombee.com/js_client) for comprehensive guides and examples.
194111

195-
```html
196-
<!DOCTYPE html>
197-
<html lang="en">
198-
<head>
199-
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
200-
</head>
201-
<body>
202-
<div class="container">
203-
<div class="row">
204-
<h1>Related products</h1>
205-
<div class="col-md-12">
206-
<div class="row" id='relatedProducts'>
207-
</div>
208-
</div>
209-
</div>
210-
</div>
211-
212-
<script src="https://cdn.jsdelivr.net/gh/recombee/[email protected]/dist/recombee-api-client.min.js"></script>
213-
214-
<script type="text/javascript">
215-
216-
// A simple function for rendering a box with recommended product
217-
function showProduct(title, description, link, imageLink, price){
218-
return [
219-
'<div class="col-md-4 text-center col-sm-6 col-xs-6">',
220-
' <div class="thumbnail product-box" style="min-height:300px">',
221-
' <img src="' + imageLink +'" alt="" />',
222-
' <div class="caption">',
223-
' <h3><a href="' + link +'">' + title + '</a></h3>',
224-
' <p>Price : <strong>$ ' + price + '</strong> </p>',
225-
' <p>' + description+ '</p>',
226-
' <a href="' + link +'" class="btn btn-primary" role="button">See Details</a></p>',
227-
' </div>',
228-
' </div>',
229-
'</div>'
230-
].join("\n")
231-
}
232-
233-
// Initialize client
234-
const client = new recombee.ApiClient('js-client-example', 'dXx2Jw4VkkYQP1XU4JwBAqGezs8BNzwhogGIRjDHJi39Yj3i0tWyIZ0IhKKw5Ln7', {region: 'eu-west'});
235-
236-
const itemId = 'product-270';
237-
const userId = 'user-1539'
238-
239-
// Send detail view
240-
client.send(new recombee.AddDetailView(userId, itemId));
241-
242-
// Request recommended items
243-
client.send(new recombee.RecommendItemsToItem(itemId, userId, 3,
244-
{
245-
returnProperties: true,
246-
includedProperties: ['title', 'description', 'link', 'image_link', 'price'],
247-
filter: "'title' != null AND 'availability' == \"in stock\"",
248-
scenario: 'related_items'
249-
}),
250-
(err, resp) => {
251-
if(err) {
252-
console.log("Could not load recomms: ", err);
253-
return;
254-
}
255-
// Show recommendations
256-
const recomms_html = resp.recomms.map(r => r.values).
257-
map(vals => showProduct(vals['title'], vals['description'],
258-
vals['link'], vals['image_link'], vals['price']));
259-
document.getElementById("relatedProducts").innerHTML = recomms_html.join("\n");
260-
}
261-
);
262-
</script>
263-
264-
</body>
265-
</html>
266-
```
112+
For a complete breakdown of all endpoints and their responses, check out our [API Reference](https://docs.recombee.com/api).
267113

268-
You should see something like this:
114+
## 🤝 Contributing
269115

270-
<a href="./examples/related_products.png"><img src="./examples/related_products.png" alt="Related products" width="500"/></a>
116+
We welcome all contributions—whether it’s fixing a bug, improving documentation, or suggesting a new feature.
271117

272-
Please notice how the properties returned by `returnProperties` & `includedProperties` were used to show titles, images, descriptions and URLs.
118+
To contribute, simply fork the repository, make your changes, and submit a pull request. Be sure to provide a clear description of your changes.
273119

274-
### Remark on user identification
120+
Thanks for helping make this project better!
275121

276-
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:
122+
## 🔧 Troubleshooting
277123

278-
```javascript
279-
ga('create', 'UA-XXXXX-Y', 'auto'); // Create a tracker if you don't have one
280-
// Replace the UA-XXXXX-Y with your UA code from Google Analytics.
124+
Are you having issues? We recommend checking [our documentation](https://docs.recombee.com/js_client) to see if it contains a possible solution.
281125

282-
const client = new recombee.ApiClient('js-client-example', 'dXx2Jw4VkkYQP1XU4JwBAqGezs8BNzwhogGIRjDHJi39Yj3i0tWyIZ0IhKKw5Ln7');
126+
If you want to reach out, you can either [open a GitHub issue](https://github.com/recombee/js-api-client/issues/new) or send an email to [email protected].
283127

284-
ga(function(tracker) {
285-
const userId = tracker.get('clientId'); // Get id from GA
286-
287-
client.send(new recombee.RecommendItemsToUser(userId, 3,
288-
{
289-
returnProperties: true,
290-
includedProperties: ['title', 'description', 'link', 'image_link', 'price'],
291-
filter: "'title' != null AND 'availability' == \"in stock\"",
292-
scenario: 'homepage'
293-
}),
294-
(err, resp) => { ... }
295-
);
296-
});
297-
298-
```
128+
## 📄 License
299129

300-
This time [RecommendItemsToUser](https://docs.recombee.com/api.html#recommend-items-to-user) is used - it can be used for example at your homepage.
130+
The Recombee JavaScript API Client is provided under the [MIT License](https://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)