# Implementing AI Scores

## Implementation and flow

The flowchart below illustrates a user journey on your website, where user identity and behavior are processed to retrieve cluster data and display a personlized PLP ranked with AI scored depending on the implementation method.

{% tabs %}
{% tab title="Using API" %}

<figure><img src="/files/Ny9WuGZq1wx9u3ZMUfBH" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Using SDK" %}

<figure><img src="/files/j0gkqsN04z9J4fVRjOo8" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

The AI Score cluster that the user is assigned to will change as the user performs activities on the site.​

{% hint style="info" %}
As a cluster may expire during a user session, the version of the user cluster (designated by the generation timestamp) must be aligned with the version of the displayed clusters.
{% endhint %}

### Retrieving a user cluster <a href="#how-to-get-the-user-cluster" id="how-to-get-the-user-cluster"></a>

Depending on whether you're using the API or the SDK, you can retrieve clusters as follows:

{% tabs %}
{% tab title="Using the API" %}
**Clusters from API responses**

When implementing tracking the response of the activity call will look as follows:

```json
{ ​
  "profiles": ​{        ​
    "customerid#live1#sessionid#a4c2386e-b19": ​{ ​
      "clusters": ​{
        "5f11b72aa6b7e52e94b8a6cf": ​{ ​ // Algorithm Id
          "1634504597142": 2, // key: Timestamp, value: Cluster Number for profile
          "1634591034702": 10 ​
        } ​
      } ​
    } ​
  } 
}
```

**Clusters from dedicated endpoint**

Retrieve the Cluster of the user with following call:

<mark style="color:blue;">`GET`</mark> `https://collect-eu.attraqt.io/:trackerKey:/users/:idRepository:/:id:/clusters`

**Path Parameters**

| Name           | Type                                   | Description                                                                                                  |
| -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| trackerKey\*   | string                                 | Your account/tenant tracker key. Example: f5c09cdc-5c02-4520-8293-b1b12f44f417                               |
| idRepository\* | string                                 | <p>The identity repository you are using to identify the user.</p><p>Example: sessionid</p>                  |
| id\*           | <mark style="color:red;">stri</mark>ng | <p>The id of this user for this identity repository.</p><p>Example: 5a664160-784e-444c-a6d3-337a2d4af0a6</p> |

Example response:

```
{
   "data": {
     "5ce2a8dbd8c622244f5d1130": {
       "1586436731840": 9,
       "1586307414486": 7
     }
   }
}
```

Fore more information on the various types of identity repositories, see [here](/product-discovery/tracking-and-sending-events/identities/user-object.md).
{% endtab %}

{% tab title="Using the SDK" %}
The method for retrieving the current user's clusters is as follows:

```javascript
xo.activity.getUserClusters();
```

This returns the user's current clusters that were stored in the local storage by the previous sending of activities, or call the endpoint if the clusters are not yet known.

```json
{
   "5ce2a8dbd8c622244f5d1130": {
     "1586436731840": 9,
     "1586307414486": 7
   }
}
```

{% hint style="info" %}
This feature is only available from version 2.0.0 of the SDK
{% endhint %}
{% endtab %}
{% endtabs %}

## Versioning in Fredhopper<mark style="color:red;">​</mark> <a href="#versioning-in-fredhopper" id="versioning-in-fredhopper"></a>

AI Scores are versioned to prevent shopper/cluster mismatches when a new update has been processed. Cluster objects returned by activities or by calling the cluster API contain two generation timestamps. Each timestamp has an associated cluster value.

When the front-end generates the query string request to Fredhopper, it should use the cluster ID for the model version that matches that in the local ‘current model version’ variable​.

A new display field will be enabled on the published endpoint which the front-end can use to determine the current cluster value (Epoch timestamp) that is loaded and should be used.

<figure><img src="/files/jWBljEHQTT0JUZ6OUg0q" alt=""><figcaption><p>Fredhopper Versioning</p></figcaption></figure>

​


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://crownpeak.gitbook.io/product-discovery/ai-scores-for-fhr/usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.