Clavis SDK

Clavis v3 consists of an SDK to be installed on your website and configured to use the two available endpoints:

Events endpoint is used to collect clickstream data from users
SIMS Recommendations endpoint uses event data to generate recommendations based on Popularity or Similarity

SDK

Clavis Engine SDK to consume Clavis Engine service.

The right way to use this SDK is to import the Javascript bundle generated when you build the project.

Requisites

Install NVM (Optional)
Install Node 18 (LTS)

nvm install --lts=gallium

Install

npm install

Run

npm run start

Build

npm run build

Response Type

The following content types are responded by the SDK

JSON: application/json

In order to use the SDK, the Javascript bundle that is generated when the project is built, needs to be imported.

How to use

Import the JS bundle into the website. You can use either the uncompressed (.js) file or a compressed version (js.gz). Uncompressed:
```
     <script>https://cdn-clavis-corecomponents-prod.arc-perso.aws.arc.pub/clavis.main.js"></script>
```
Compressed:
```
     <script>https://cdn-clavis-{organizationname}-prod.arc-perso.aws.arc.pub/clavis.main.js.gz"></script>
```
- Note 1: In code samples, we are getting the SDK JS bundle from Arc-Clavis-Corecomponents-Prod.S3.Amazonaws.Com. You need to change corecomponents and sandbox to your organization and environment names you are going to use. The pattern is as follows: arc-clavis-{organization}-{environment}.s3.amazonaws.com for S3. For CDN the URL pattern is cdn-clavis-{organization}-{environment}.arc-perso.aws.arc.pub
- Note 2: If you don’t have the CDN activated please request to Clavis team to deploy the CDN feature for you.
Setup the configuration object. You need to provide the Clavis service URL and your ARC site.
- protocol: Clavis service supports https or http. Clavis service is usually deployed in https.
- host: This is the DNS where Clavis service is running. We usually follow this convention clavis-<arc-customer-org>-<env>.arc-perso.aws.arc.pub. Where:
- port: The Clavis service HTTP port used. If the default HTTP port is used a blank value is enough.
- site: The ARC site where Clavis is enabled.
This is a sample configuration object for corecomponents and the site the-gazette. You have to provide different configuration values according to your organization.
```
const sdkConfig = {
protocol: 'https',
host: 'arc-clavis-corecomponents-prod',
port: '', // We are using default port, this means no port value is needed, we set it as empty string.
site: 'the-gazette',
};
```

Instantiate an SDK client.

const clavis = ClavisSDK.default.newInstanceFromConfig(sdkConfig);

API

Clavis SDK is a client for the Clavis Service. Clavis SDK consists of two main functionality:

Events: The initial step in the Clavis flow. The user’s behavior is tracked by Clavis.
Recommendations: The final step in the Clavis flow. Based on the user interactions (events) Clavis is able to provide recommendations.

Events

An Event is the representation of a user’s behavior. By now, Clavis only supports Click events.

Click

A click is the interaction of a User clicking a specific article. This event needs to be submitted to Clavis to be used in the recommendations algorithms.

     const click = {
    document: {
        id: 'E4P5GV7GNRGNLIN3LFQ5IZ245A',
        site: 'the-gazette',
        },
        user: {
            id: '527cccf9-708a-4de6-b4bb-0738101e0978',
            },

};
// Waiting for response for demonstrative purposes. Usually submiting events don’t require to wait for result.
clavis.event(click).then((response) => {
    console.log(`Put event response: ${JSON.stringify(response, null, 2)}`);

});

Recommendations

Is the list of documents (articles) that Clavis recommends based on the different algorithms. By now, Clavis only supports two algorithms:

Popularity
SIMS

Popularity

Recommend the most popular documents based on all of your user behavioral data.

     const limit = 10; // The number of documents (recommendations) to return.

clavis.recommendationsByPopularity(limit).then((recommendations) => {
console.log(`Recommendations by popularity response: ${JSON.stringify(recommendations, null, 2)}`);
});

SIMS (Similarity)

Recommend documents that are most similar to a document you specify when you get recommendations.

     const documentId = 'NP2PIBCHYVCLTIMNOJ6YPXXLBY'; // The document ID that user read.
const limit = 10; // The number of documents (recommendations) to return.

clavis.recommendationsByDocument(documentId, limit).then((recommendations) => {
  console.log(`Recommendations by document response: ${JSON.stringify(recommendations, null, 2)}`);
});

View the Endpoint Documentation for API contracts.

We value your feedback! If you have suggestions, please reach out to your technical account manager or post suggestions to Our Ideas Portal.