Integrate real-time personalization

Real-time personalization is a beta feature according to Algolia’s Terms of Service (“Beta Services”).

This guide demonstrates how to integrate Algolia’s real-time personalization into your search experience, leveraging user profiles for real-time personalized results.

Before you begin

This guide assumes that:

• You have configured the Advanced Personalization feature.
• You have enabled real-time personalization.

This feature isn’t available on every plan. Refer to your pricing plan to see if it’s included.

Using the JavaScript API client

Install the Algolia Personalization real-time client

In a terminal, paste:

1
2
3
npm install --save @algolia/advanced-personalization
# or
yarn add @algolia/advanced-personalization

Initialize the Advanced Personalization client

1
2
3
4
5
6
7
8
import { advancedPersonalizationClient } from '@algolia/advanced-personalization';

// Create an Advanced Personalization client
const client = advancedPersonalizationClient(
  'YourApplicationID',
  'YourSearchOnlyApiKey', // the same one you use for search
  'eu', // or 'us' (check https://dashboard.algolia.com/account/infrastructure/analytics)
);

Compute the real-time profile

You can decide when to compute and refresh a real-time user profile. We recommend that you recompute the user profile after meaningful user interactions such as views, clicks, and conversions, such as add to cart or purchase events.

We recommend:

• Send tracking events first.
• Call computeRealtimeUser immediately after.

1
client.computeRealtimeUser({ userToken });

This function is asynchronous, you don’t need to wait for the response.

Error management

The computeRealtimeUser function can return a number of errors, it is up to you to handle or ignore them depending on your needs.

Retrieve The Personalization Profile (Optional)

Use getRealtimeUser to retrieve the latest profile for advanced UI customizations. Note: This returns meaningful data only after the user has sufficient interaction history.

1
const profile = await client.getRealtimeUser({ userToken });

Example Of A Profile Response

Use this data to adapt your experience (for example: personalized banners).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "version": "1",
    "lastUpdatedAt": "2025-01-01T01:01:10Z",
    "userID": "user_1",
    "search": {
        "MyIndexName": {
            "indices": [
                "MyIndexName"
            ],
            "strategy": "session",
            "filters": {
                "session": [
                    "brand:Apple<score=5>",
                    "category:Smartphones<score=3>"
                ]
            }
        }
    }
}

How to build a secure, personalized search

• Protect sensitive data
  • Always use a search-only API key with limited permissions
  • Don’t expose your Admin API key in client-side code
• Performance optimization
  • Set appropriate timeouts based on your app’s needs
  • Set up fallbacks for when personalization services are unavailable
• User experience
  • Offer a non-personalized fallback for when personalization services are unavailable
  • Consider privacy implications and provide opt-out mechanisms
• Error handling
  • Implement proper error handling for API calls
  • Log errors for monitoring but keep basic search working

Troubleshooting

If you’re not seeing the personalized search results you anticipate:

• Check that Personalization is enabled for the index
• Ensure that the user has sufficient interaction history

Further reading