Clavis Endpoints: Events and SIMS Recommendations

Once the Clavis v3 SDK has been installed, you can use two available endpoints:

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

Notes:

• You can find the OpenAPI documentation in Clavis V3 API
• Clavis stores a user.id just to identify which user produces an event on which article. That id could be any string you want, you just have to ensure you identify each user uniquely. user.id is not related to cookies or sessions or any auth-related thing, so all users are always tracked as anonymous visitors by Clavis.
• To return Clavis recommendations, the SIMS Recommendations endpoint requires at least 1000 events from 25 unique users who have each generated at least 2 events.

PutEvents Endpoint

Inserts events into Clavis to be considered on the algorithm for creating recommendations.

Dates

All date-time objects are returned in UTC in the following ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Parameters

The following parameters are required and must have a value:

• document.id
• document.site
• user.id
• click through (optional)

Example:

  clavis
   .event({
      document: {
        id: '[DOCUMENT ID]',
        site: '[DOCUMENT SITE]',
      },
      user: {
        id: '[USER ID]',
      },
   })
   .then((response) => {
      console.log('Put event response: ${JSON.stringify(response, null, 2)}');
   });

Response

Will output the confirmation of the event created and its unique id

{
  "event": "e0ccf5af-ee15-460b-91c9-e71f1ed2f7b0",
  "status": "CREATED"
}

SIMS Recommendations (Collaborative) Endpoint

Recommendations Call

Usage: recommendationsByDocument(document_id,n)

Parameters

The parameter document_id is the id of the article that will trigger the recommendations and n is the number of recommendations to retrieve. The value n is an optional parameter, if it’s not used, the default value will be 10.

Example:

clavis
  .recommendationsByDocument(
    '[DOCUMENT ID]',
    2, // Number of recommendations (optional, default 10)
  )
  .then((recommendations) => {
    console.log('Recommendations by document response: ${JSON.stringify(recommendations, null, 2)}');
  });

Response

Will output the set of document_id’s with the following data already extracted from Content API:

• version
• created_date
• last_updated_date
• publish_date
• canonical_url
• headlines
• website
• website_url

{
  "document_id": "[DOCUMENT ID]",
  "recommendations": [
    {
      "document_id": "[DOCUMENT ID]",
      "score": 1,
      "content": {
        "version": "0.10.6",
        "created_date": "2020-08-18T16:16:02.638Z",
        "last_updated_date": "2021-01-12T11:53:06.755Z",
        "publish_date": "2021-01-12T11:53:06.433Z",
        "canonical_url": "/example/url",
        "headlines": {
          "basic": "Example Text",
          "mobile": "",
          "native": "",
          "print": "",
          "tablet": "",
          "web": "",
          "meta_title": ""
        },
        "website": "[DOCUMENT SITE]",
        "website_url": "/example/url"
      }
    },
  ]
}

Recommendation’s Error Responses

Codes: 2xxx

Uses standard HTTP response codes to indicate success or failure. Codes in the 2xx are successful, codes in the 4xx range indicate that something is wrong with your request, and codes in the 5xx indicate something went wrong with the API. All errors return an error field describing what went wrong.

HTTP: 500
{
  "code": "2000",
  "error": "Recommendations Error: There is an unexpected error in recommendations engine. Try again later or contact support."
}

HTTP: 400
{
  "code": "2001",
  "error": "Invalid `items` parameter value"
}

HTTP: 500
{
  "code": "2002",
  "error": "No recommendations returned from Clavis"
}

HTTP: 404
{
  "code": "2101",
  "error": "Provided site (website parameter) not found"
}

HTTP: 500
{
  "code": "2102",
  "error": "Invalid content-api token"
}

HTTP: 500
{
  "code": "2103",
  "error": "Not documents found"
}

HTTP: 500
{
  "code": "2104",
  "error": "Unexpected missing property in returned payload"
}

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