Export user profiles to an audience

This guide demonstrates how to fetch and browse user profiles using Algolia’s Advanced Personalization API. The provided code snippets offer a straightforward way to interact with the API and retrieve user data for segmentation purposes.

Exporting an audience lets you segment users based on their affinities to create focused email or ad campaigns. For example, you could send promotional content about outdoor gear to users with a high affinity for camping or hiking.

Before you begin

Ensure you have a query string builder utility, such as the qs library available in your project.

Fetch user profiles

The Advanced Personalization API exposes an endpoint to retrieve user profiles based on specified parameters.

Here’s a function to communicate with this endpoint:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import qs from 'qs';

export async function fetchUserProfiles(params) {
  const { appId, apiKey, region, ...usersParams } = params;
  const response = await fetch(
    `https://ai-personalization.${region}.algolia.com/2/users${qs.stringify(
      usersParams,
      { addQueryPrefix: true }
    )}`,
    {
      headers: {
        'X-Algolia-Application-Id': appId,
        'X-Algolia-API-Key': apiKey,
      },
    }
  );

  if (!response.ok) {
    const errorMessage = await response.text();
    throw new Error(errorMessage);
  }

  const json = await response.json();

  return json;
}

The function takes as parameters an object containing:

• appId: Your Algolia Application ID
• apiKey: Your Algolia API Key with search, browse, and recommendation ACLs
• region: The Algolia region (for example, "us", "eu")
• Additional parameters for retrieving user profiles

Browse user profiles

To iterate through all user profiles and handle pagination automatically, use this function:

1
2
3
4
5
6
7
8
9
10
11
12
export async function browseUserProfiles(callback, params) {
  let nextPageToken = '';
  do {
    const response = await fetchUserProfiles({
      ...params,
      nextPageToken,
    });
    nextPageToken = response.nextPageToken;

    await callback(response.users);
  } while (nextPageToken);
}

Process batches of user profiles

Here’s an example of how to process batches of user profiles:

1
2
3
4
5
6
7
8
9
10
11
async function processUsers(users) {
  // Perform operations with all users in the batch
}

await browseUserProfiles(processUsers, {
  appId: 'YourApplicationID',
  apiKey: 'YourSearchOnlyAPIKey',
  region: 'us',
  affinity: 'category:camping',
  limit: 100
});

Segment users based on their category:camping affinity and implement targeted strategies for these users. For example, send them an email about a discount on camping products.

Find the list of available parameters in the REST API documentation.