> For the complete documentation index, see [llms.txt](https://fredhopper.gitbook.io/product-discovery/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fredhopper.gitbook.io/product-discovery/ai-scores-for-fhr/usage.md).

# 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="https://3916646904-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfLO8j00CcKdYax4GPUyE%2Fuploads%2Fgit-blob-443601233cb337df133c80f67cd77d5f9f4aead7%2Fimage%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Using SDK" %}

<figure><img src="https://3916646904-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfLO8j00CcKdYax4GPUyE%2Fuploads%2Fgit-blob-78438aa33243184d819b9051d714c99938e9251d%2Fimage%20(3).png?alt=media" 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="https://3916646904-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfLO8j00CcKdYax4GPUyE%2Fuploads%2Fgit-blob-bf39ee0f4c98a0a26a6188bc0f1f0659baa79df3%2Fimage%20(4).png?alt=media" alt=""><figcaption><p>Fredhopper Versioning</p></figcaption></figure>

​