Lableb Cloud Search's Javascript Client
Javascript library built to ease your integration with Lableb.
Installation
yarn add @lableb/javascript-sdk
# OR
npm install @lableb/javascript-sdk
Browsers
<script src="https://unpkg.com/@lableb/javascript-sdk/dist/LablebSDK.min.js"></script>
For browser users you need to access LablebClient
from window.LablebSDK.LablebClient
.
const lablebClient = window.LablebSDK.LablebClient();
ES Module in browser
For browser ESM module
<script type="module" src="https://unpkg.com/@lableb/javascript-sdk/dist/browser/index.esm.js"></script>
Node.js
const { LablebClient } = require('@lableb/javascript-sdk');
or
const LablebClient = require('@lableb/javascript-sdk').default;
ESM
import LablebClient from '@lableb/javascript-sdk';
Overview
Lableb's client empower you with all the needed functions for a full search experience including: search, autocomplete, recommendation, indexing, deleting documents and send feedbacks.
It's usage made easy for new users with a very good defaults, and the more you need from it, the more options you can use to suits your advanced usages.
Note: This library is built with Promises, and basically all functions return promises, so stay tuned, and make your functions
async
hronous.
To start, just create your very first client instance
const lablebClient = LablebClient();
Now lablebClient
has all the functions needed for your application.
We'll do a simple search example:
const { code, response, time } = await lablebClient.search({
APIKey: API_KEY,
platformName: PLATFORM_NAME,
query: 'water',
});
const searchResults = response.results;
That's it, we just passed the required fields:
- Platform name
- API Key: used to authenticate your search request, visit Lableb Dashboard to create a new one.
- query is what you're searching for, or basically your end-users' query.
Now you can do more than that, but sticking with the spirit of going fast and easy, that was all what you need.
Options
When creating a new instance of the client you can pass nothing, or pass an option object which can save your time passing the same options over and over to the client's inner functions like search, autocomplete, recommend.
Pass nothing
const lablebClient = LablebClient();
Now for every inner function you have to pass at least an API Key
and a Platform Name
Search
const { code, response, time } = await lablebClient.search({
APIKey: API_KEY,
platformName: PLATFORM_NAME,
query: 'water',
});
Autocomplete
const { code, response, time } = await lablebClient.autocomplete({
APIKey: API_KEY,
platformName: PLATFORM_NAME,
query: 'water',
});
And so on...
Pass the global options
You noticed that we repeatedly passed the shared options to many functions, to end that repetition, you can pass any shared option you find in this library to the main LablebClient
that create the instance for you, and you're all set and ready.
const lablebClient = LablebClient({
APIKey: API_KEY,
platformName: PLATFORM_NAME,
});
Now for the other functions you just pass the required options
Search
const { code, response, time } = await lablebClient.search({
query: 'water',
});
Autocomplete
const { code, response, time } = await lablebClient.autocomplete({
query: 'water',
});
And so on...
When passing options to an inner function might be useful?
Imagine you want to use the same options for all functions(search, autocomplete, recommend, ...etc) but for one function you have a single different option.
You can pass the unique option value only to this specific function call which will override the previously saved value(passed to LablebClient
globally).
Example:
const lablebClient = LablebClient({
searchHandler: SEARCH_HANDLER_1,
});
const { code, response, time } = await lablebClient.search({
searchHandler: SEARCH_HANDLER_2,
query: 'water',
});
Now this search function call will have searchHandler
value set to SEARCH_HANDLER_2
as it override the global option passed to create the client.
Options fields and types
Options pass to LablebClient
are plain JS object, and all it's properties are optional
property | type | default | description |
---|---|---|---|
platformName | string | - | Your platform name as written at Lableb Dashboard |
indexName | string | index | The used data index name as created at Lableb Dashboard | Collections |
APIKey | string | - | Search, Autocomplete, Recommend, and Feedback API Key |
indexingAPIKey | string | - | Index, Delete API Key |
searchHandler | string | default | The used search handler name as found at Lableb Dashboard | Collections | Handlers |
autocompleteHandler | string | suggest | The used autocomplete handler name as found at Lableb Dashboard | Collections | Handlers |
recommendHandler | string | recommend | The used recommend handler name as found at Lableb Dashboard | Collections | Handlers |
interceptors | array of functions | [] | pass an array of interceptors functions to manipulate the request before being sent to Lableb. Read in details |
userId | string | - | end user id |
userIp | string | - | end user IP address |
userCountry | string | - | end user country code(ISO-3166) |
sessionId | string | - | uniques session Id for your end user |
sessionIdGenerator | function | - | pass callback that generate unique session id string |
Note: Creating API Key in Lableb Dashboard
When creating a new API key, make sure you check "search" permission in order to make this key usable for search, autocomplete and recommend requests
Note: Creating Indexing API Key in Lableb Dashboard
When creating a new Indexing API Key, make sure you check "index" permission in order to make this key usable in indexing, and delete requests
Lableb's client API
Search
Query your existing data at Lableb by sending text queries
const lablebClient = LablebClient({
APIKey: process.env.API_KEY,
platformName: process.env.PLATFORM_NAME,
});
const { code, response, time } = await lablebClient.search({
query: 'water'
});
const searchResults = response.results;
Read about Search API in details.
Autocomplete
Get instant auto-complete results for the best typing experience for your end-users, where it can better help them find what they need.
const lablebClient = LablebClient({
APIKey: process.env.API_KEY,
platformName: process.env.PLATFORM_NAME,
});
const { code, response, time } = await lablebClient.autocomplete({
query: 'wat'
});
const autocompleteResults = response.results;
Read about Autocomplete API in details.
Recommend
Smart applications display relevant data for their users, Recommend
enable you to get the most relevant data(document/product/article...) your users are interacting with now, which will better increase your revenue, visits count, and the time a user spent on your application.
Pass down the data Id you want relevant data for, and the recommend
function will return the best possible results.
const lablebClient = LablebClient({
APIKey: process.env.API_KEY,
platformName: process.env.PLATFORM_NAME,
});
const { code, response, time } = await lablebClient.recommend({
id: '475'
});
const recommendResults = response.results;
Read about Recommend API in details.
Indexing
Adding or uploading your data to Lableb is called indexing
.
Indexing is a very smooth experience, passing down the data as an array is all what it does, the only required thing is your data objects must match your data schema
made at Lableb Dashboard.
Assuming your platform schema has an id
and title
as required fields.
const lablebClient = LablebClient({
indexingAPIKey: process.env.API_KEY,
platformName: process.env.PLATFORM_NAME,
});
await lablebClient.index({
documents: [
{ id: '1', title: 'Finding water in Africa' },
{ id: '2', title: 'How important is water for daily life?' }
]
});
Note: You need to use a special API Key for
indexing
anddelete
, we call itindexingAPIKey
, you can create it inside Lableb Dashboard, where you choose to addindex
permission to the created API Key.
Read about Indexing API in details.
Note: How to update already indexed data
To update any existing data you have at Lableb, just re index it again, and it will be updated automatically for you.
Delete
Remove your data from Lableb
can be justified for many reasons, wrong data, stalled data, not needed anymore data... anyway you can absolutely remove any piece of data using its unique id.
const lablebClient = LablebClient({
indexingAPIKey: process.env.API_KEY,
platformName: process.env.PLATFORM_NAME,
});
await lablebClient.delete({
documentId: '274'
});
Read about Delete API in details.
Search By ID
Fetching single document from Lableb
const lablebClient = LablebClient({
APIKey: process.env.API_KEY,
platformName: process.env.PLATFORM_NAME,
});
const { code, response, time } = await lablebClient.searchById({
id: '297424'
});
const searchResult = response;
Read about Search By ID API in details.
Feedback
Sending feedback to Lableb help you study and understand your users behavior at a deeper level through various analytics at Lableb Dashboard.
You can access a feedback object that contains search, autocomplete, recommend feedbacks functions respectively where you have many options to send in the feedback, and you can either send a single feedback to Lableb at a time, or send a batch of feedbacks in one call.
Each feedback object has two functions: single
and batch
Search Feedback Example:
- To Send single search feedback to Lableb use
feedback.search.single
function - To Send many search feedbacks at once to Lableb use
feedback.search.batch
function
Of course there is similar functions for autocomplete and recommend feedback respectively.
When feedback is usually used in application?
Feedback requests are usually fired from the UI(based on users' behavior).
When you do a search at Lableb you get back the search results and display them for your end users, when a user clicks or interact with the displayed result, you send a search feedback to Lableb, and so on.
When your end users interacts with an autocomplete results, you send an autocomplete feedback, and when the end-users interact with a recommend result, you send a recommend feedback.
Feedback APIs:
Real Examples
We have included several simple examples regarding different modules format(esm, cjs) and different environment(node.js, browser) you can check them at examples folder
Don't forget to only change the import statement in browsers examples, or do yarn install
for node.js examples.
Test and code coverage
This library is tested with jest
and has 100% code coverage(run coverage results in your browser.)
FAQ:
-
What is a document at Lableb?
It's a synonyms for data, product, article, and what you call it depends on your platform, whether it's e-commerce, blog, ...etc
-
How can I user
promises
in old browsers?if you're using an old version of
EcmaScript
and want to use theasync/await
syntax you easily do by installbabel-polyfill
-
What is the difference between API Key and indexing API Key?
API Key can only be used for
search
,autocomplete
,recommend
, andfeedbacks
, while indexing API Key is only used forindexing
anddelete
. -
Can I call
index
function in browser?Yes, but doing so will expose your Index API Key in developers tools, so we recommend leaving
indexing
anddelete
only for the server. -
I have an issue, what can I do to solve it?
If you find an issue you can open an issue at the git repository, or contact us at support@lableb.com