Appbase Analytics
A universal analytics library that allows you to record search, click and conversion for appbase.io clusters.
TOC
Getting started
Browser
1. Load the library
The analytics library can be either loaded via jsDelivr CDN or directly bundled with your application.
You can use the UMD build in browsers by following the below snippet:
<script defer src="https://cdn.jsdelivr.net/npm/@appbaseio/analytics@2.0.0-beta.2/dist/@appbaseio/analytics.umd.min.js"
></script>
2. Initialization
const aaInstance = aa.init({
index: 'INDEX_NAME',
credentials: 'AUTH_CREDENTIALS',
url: 'CLUSTER_URL'
});
Node.js
1. Install the library
Install the library by following the below command:
npm install @appbaseio/analytics
# or
yarn add @appbaseio/analytics
2. Initialization
const aa = require('@appbaseio/analytics');
const aaInstance = aa.init({
index: 'INDEX_NAME',
credentials: 'AUTH_CREDENTIALS',
url: 'CLUSTER_URL'
});
Use cases
The analytics library provides the utility methods to integrate the appbase.io analytics in minutes, the common use-cases are to record the search, clicks and conversion events.
Record search
It helps you to track the search for a particular query term. It returns the queryID
back which can be used to record clicks and conversions for the same search event.
const aa = require('@appbaseio/analytics');
const aaInstance = aa.init({
index: 'INDEX_NAME',
credentials: 'AUTH_CREDENTIALS',
url: 'CLUSTER_URL'
});
aaInstance.search({
query: 'iphone'
});
Note: queryID
will be automatically set in the state and can be retrieved by using the getQueryID
method once a search event has been registered successfully.
Record empty query search
query
is the required key to record a search event however you can set it to empty string to register as an empty query search.
aaInstance.search({
query: ''
});
Record clicks
Use the click
method to record click events. The below example records the two clicks of the result
type for a search query.
const aa = require('@appbaseio/analytics');
const aaInstance = aa.init({
index: 'INDEX_NAME',
credentials: 'AUTH_CREDENTIALS',
url: 'CLUSTER_URL'
});
aaInstance.click({
query: 'iphone',
objects: {
iphoneX_19348: 1,
iphone7_19348: 3
},
meta: {
key1: 'value1'
}
});
Record suggestion clicks
Set the isSuggestionClick
property to true
to record as suggestion click.
aaInstance.click({
query: 'iphone',
isSuggestionClick: true,
objects: {
iphoneX_19348: 1,
iphone7_19348: 3
}
});
Record clicks for a particular search event
Use queryID
instead of query
to record clicks for a particular search event.
// Record a search
aaInstance.search({
query: 'iphone'
});
// Record a click for the last search made
aaInstance.click({
queryID: aaInstance.getQueryID(),
objects: {
iphoneX_19348: 1,
iphone7_19348: 3
}
});
Record clicks with particular events
Attach the custom events to distinguish the click events.
aaInstance.click({
query: 'iphone',
objects: {
iphoneX_19348: 1,
iphone7_19348: 3
},
customEvents: {
click_source: 'promoted_collections'
}
});
Record conversions
Conversions must be recorded for a particular search event so it is required to define a queryID
to record conversion.
// Record a search
aaInstance.search({
query: 'iphone'
});
// Record a conversion for the last search made
aaInstance.conversion({
queryID: aaInstance.getQueryID(),
objects: ['iphoneX_19348', 'iphone7_19348'],
meta: {
key1: value1
}
});
Save search
To save a search state, queryID
must be present.
// Save search state
aaInstance.saveSearch({
queryID: 'cf600405-d4ed-42b0-8b09-08b594fa88d2',
saveSearchID: 'analytics-js-test',
saveSearchMeta: {
key1: 'value1'
},
userID: 'john@appbase.io',
customEvents: { platform: 'mac' }
});
Delete Saved search
To delete a saved search state by Id.
// Save search state
aaInstance.deleteSavedSearch('analytics-js-test');
Get Saved searches
To retrieve saved searches, here we're fetching the saved searches for user with user id as john@appbase.io
.
aa.getSavedSearches(
{
user_id: 'john@appbase.io'
},
(err, res) => {
if (err) {
console.error(err);
} else {
res
.json()
.then(savedSearches => {
// saved searches list
})
.catch(err => {
console.error(err);
});
}
}
);
Favorite
To record a favorite document
aa.favorite({
favoriteOn: '1jftXXEBdEU4aeo6Gdqs',
queryID: 'cf600405-d4ed-42b0-8b09-08b594fa88d2',
source: {
authors: 'John Milton, John Leonard',
average_rating: 3.8,
average_rating_rounded: 4,
books_count: 819,
id: 984,
image: 'https://images.gr-assets.com/books/1455618673l/15997.jpg',
image_medium: 'https://images.gr-assets.com/books/1455618673m/15997.jpg',
isbn: '140424393',
language_code: 'eng',
original_publication_year: 1667,
original_series: '',
original_title: 'Paradise Lost',
ratings_count: 96316,
title: 'Paradise Lost'
},
id: 'analytics-js-test',
userID: 'john@appbase.io',
customEvents: { platform: 'mac' },
meta: {
key1: 'value1'
}
});
Get Favorites
To retrieve favorite documents, here we're fetching the favorites for user with user id as john@appbase.io
.
aa.getFavorites(
{
user_id: 'john@appbase.io'
},
(err, res) => {
if (err) {
console.error(err);
} else {
res
.json()
.then(favorites => {
// list of favorite document
})
.catch(err => {
console.error(err);
});
}
}
);
Set user
It allows you to set the userID
.
const aa = require('@appbaseio/analytics');
// Set during initialization
const aaInstance = aa.init({
index: 'INDEX_NAME',
credentials: 'AUTH_CREDENTIALS',
url: 'CLUSTER_URL',
userID: 'jon@abc.com'
});
// or set by using method
aaInstance.setUserID('jon@abc.com');
Set global events
To set the custom events which will be attached for each event recorded by the instance.
For example:
const aa = require('@appbaseio/analytics');
const aaInstance = aa.init({
index: 'INDEX_NAME',
credentials: 'AUTH_CREDENTIALS',
url: 'CLUSTER_URL'
});
// or set by using method
aaInstance.setGlobalCustomEvents({
platform: 'ios'
});
API Reference
Initialization
const aa = require('@appbaseio/analytics');
const aaInstance = aa.init({
index: 'INDEX_NAME',
credentials: 'AUTH_CREDENTIALS',
url: 'CLUSTER_URL',
userID: 'USER_ID',
globalCustomEvents: 'GLOBAL_CUSTOM_EVENTS'
headers?: 'CUSTOM_HEADERS'
});
Optional configuration options:
Option | Type | Description |
---|---|---|
index |
string (required) |
Elasticsearch index name. |
credentials |
string (required) |
credentials as they appear on the Appbaseio dashboard. It should be a string of the format username:password and is used for authenticating the app. |
url |
string (required) |
Appbaseio cluster URL. |
userID |
string |
UserID allows you to record events for a particular user. For example, you may want to know that how many different users are using the search. |
globalCustomEvents |
Object |
It allows you to set the global custom events which can be used to build your own analytics on top of the appbase.io analytics. Read More |
headers |
Object |
Sometimes it may require to set extra headers to the analytics API. For example, you're using proxy middleware which adds an additional security layer. |
An example with all possible options:
const aa = require('@appbaseio/analytics');
const aaInstance = aa.init({
index: 'books',
credentials: 'foo:bar',
url: 'http://localhost:8000',
userID: 'jon@abc.com',
globalCustomEvents: {
platform: 'mac'
},
headers: {
'X-auth-token': 'XYZ'
}
});
Instance Methods
Record Search
search(searchConfig: Object, callback: Function)
search configuration options:
Option | Type | Description |
---|---|---|
query |
string |
Search query, set to empty string to register as an empty query search. |
queryID |
string |
Search query ID returned from Appbase. |
customEvents |
Object |
To set the custom events, for e.g { "platform": mac }
|
filters |
Object |
It allows to record the applied facets on the search query, for e.g { "year": 2018 }
|
hits |
Array |
To set the search hits, a hit object can have the id , type & source properties . |
impressions |
Array |
To set the impressions, a hit object can have the id & index properties. |
Note:
query
or queryID
must be present.
An example with all possible options:
search(
{
query: 'iphone',
// or
queryID: 'cf827a07-60a6-43ef-ab93-e1f8e1e3e1a8',
customEvents: {
source: 'promoted_results'
},
filters: {
year: 2019
},
hits: [
{
id: '12345678',
source: {
title: 'iphoneX'
},
type: '_doc'
}
]
},
(err, res) => {
if (err) {
// handle error
} else if (res) {
// handle response
}
}
);
Get queryID
The below method returns the queryID
from the last search made.
getQueryID(): string
Record Click
To record a click event
click(clickConfig: Object, callback: Function)
click configuration options:
Option | Type | Description |
---|---|---|
query |
string |
Search query, set to empty string to register as an empty query search. |
queryID |
string |
Search query ID returned from Appbase. |
objects |
{[key: string]: number} (required) |
To set the click object ids followed by click positions, for example { "iphoneX_1234": 2 } . |
isSuggestionClick |
boolean |
Set as true to register as a suggestion click. |
customEvents |
Object |
To set the custom events, for e.g { "platform": mac }
|
meta |
Object |
Meta data |
Note:
query
or queryID
must be present.
An example with all possible options:
click(
{
query: 'iphone',
// or
queryID: 'cf827a07-60a6-43ef-ab93-e1f8e1e3e1a8',
customEvents: {
source: 'promoted_results'
},
objects: {
iphone_1234: 2
},
isSuggestionClick: true,
meta: {
key1: value1
}
},
(err, res) => {
if (err) {
// handle error
} else if (res) {
// handle response
}
}
);
Record conversion
To record a conversion event
conversion(conversionConfig: Object, callback: Function)
conversion configuration options:
Option | Type | Description |
---|---|---|
queryID |
string (required) |
Search query ID returned from Appbase. |
objects |
Array<string> (required) |
To set the converted object ids, for example: ["iphoneX_1234"] . |
meta |
Object |
Meta data |
Note:
queryID
must be present.
An example with all possible options:
conversion(
{
queryID: 'cf827a07-60a6-43ef-ab93-e1f8e1e3e1a8',
objects: ['iphone_1234'],
meta: {
key1: value1
}
},
(err, res) => {
if (err) {
// handle error
} else if (res) {
// handle response
}
}
);
Save search
To save search state
saveSearch(config: Object, callback: Function)
configuration options:
Option | Type | Description |
---|---|---|
queryID |
string (required) |
Search query ID returned from Appbase. |
saveSearchID |
string |
Saved search ID. |
saveSearchMeta |
Object |
Meta data |
userID |
string |
User Id. |
customEvents |
Object |
To set the custom events, for e.g { "platform": mac }
|
Note:
queryID
must be present.
An example with all possible options:
saveSearch(
{
queryID: 'cf600405-d4ed-42b0-8b09-08b594fa88d2',
saveSearchID: 'analytics-js-test',
saveSearchMeta: {
key1: 'value1'
},
userID: 'john@appbase.io',
customEvents: { platform: 'mac' }
},
(err, res) => {
if (err) {
// handle error
} else if (res) {
// handle response
}
}
);
Delete Saved search
To delete search state by Id
deleteSavedSearch(savedSearchId: string, callback: Function)
An example with all possible options:
deleteSavedSearch('analytics-js-test', (err, res) => {
if (err) {
// handle error
} else if (res) {
// handle response
}
});
Get saved searches
To retrieve saved searches
getSavedSearches(queryParams: Object, callback: Function)
You can find the available query params at here.
getSavedSearches(
{
user_id: 'john@appbase.io'
},
(err, res) => {
if (err) {
// handle error
} else if (res) {
res
.json()
.then(favorites => {
// list of saved searches
})
.catch(err => {});
// handle response
}
}
);
Favorite
To record a favorite document
favorite(config: Object, callback: Function)
configuration options:
Option | Type | Description |
---|---|---|
queryID |
string (required) |
Search query ID returned from Appbase. |
favoriteOn |
string (required) |
Favorite document ID. |
source |
Object (required) |
Favorite document source object data |
id |
string |
Favorite ID. |
meta |
Object |
Meta data |
userID |
string |
User Id. |
customEvents |
Object |
To set the custom events, for e.g { "platform": mac }
|
Note:
queryID
, favoriteOn
and source
must be present.
An example with all possible options:
favorite(
{
favoriteOn: '1jftXXEBdEU4aeo6Gdqs',
queryID: 'cf600405-d4ed-42b0-8b09-08b594fa88d2',
source: {
authors: 'John Milton, John Leonard',
average_rating: 3.8,
average_rating_rounded: 4,
books_count: 819,
id: 984,
image: 'https://images.gr-assets.com/books/1455618673l/15997.jpg',
image_medium: 'https://images.gr-assets.com/books/1455618673m/15997.jpg',
isbn: '140424393',
language_code: 'eng',
original_publication_year: 1667,
original_series: '',
original_title: 'Paradise Lost',
ratings_count: 96316,
title: 'Paradise Lost'
},
id: 'analytics-js-test',
userID: 'john@appbase.io',
customEvents: { platform: 'mac' },
meta: {
key1: 'value1'
}
},
(err, res) => {
if (err) {
// handle error
} else if (res) {
// handle response
}
}
);
Get favorites
To retrieve saved favorites
getFavorites(queryParams: Object, callback: Function)
You can find the available query params at here.
getFavorites(
{
user_id: 'john@appbase.io'
},
(err, res) => {
if (err) {
// handle error
} else if (res) {
res
.json()
.then(favorites => {
// list of favorites
})
.catch(err => {});
// handle response
}
}
);
Set headers
It allows you to set the custom headers in analytics endpoints.
setHeaders(headers: Object)
Set user
Sets the user ID. User ID helps to record an event for that particular user.
setUserID(userID: string)
Set global events
Sets the global event data. This will be added to all the analytics requests made by the instance.
setGlobalCustomEvents(globalEvents: Object)
Contributing
Fork the repo and run the following command to run & test locally.
yarn && yarn test
Other Projects You Might Like
-
Arc API Gateway for ElasticSearch (Out of the box Security, Rate Limit Features, Record Analytics and Request Logs).
-
ReactiveSearch ReactiveSearch is an Elasticsearch UI components library for React, React Native and Vue. It has 25+ components consisting of Lists, Ranges, Search UIs, Result displays and a way to bring any existing UI component into the library.
-
searchbox A lightweight and performance-focused search box UI libraries to query and display results from your ElasticSearch app (aka index).
-
Dejavu allows viewing raw data within an appbase.io (or Elasticsearch) app. Soon to be released feature: An ability to import custom data from CSV and JSON files, along with a guided walkthrough on applying data mappings.
-
Mirage ReactiveSearch components can be extended using custom Elasticsearch queries. For those new to Elasticsearch, Mirage provides an intuitive GUI for composing queries.
-
ReactiveMaps is a similar project to Reactive Search that allows building realtime maps easily.
-
appbase-js While building search UIs is dandy with Reactive Search, you might also need to add some input forms. appbase-js comes in handy there.
License
This library is Apache licensed.