Guides / Sending events / Connectors

If you’re using Twilio Segment to track user interactions on your website or app, you can set up Algolia as a destination to forward click and conversion events.

Integrating Algolia with Segment has three steps:

  1. Enable the Algolia destination in Segment.
  2. Enable clickAnalytics with your searches.
  3. Augment your Segment events with Algolia-related data.

Enable the Algolia destination in Segment

To add the Algolia destination to Segment, follow these steps:

  1. Sign in to your Segment web app and select the workspace you want to work in.
  2. Select the source you want to set up and click Add Destination.

    Add a destination to a source

  3. Search for the Algolia destination and select it to add it.

    Add the Algolia destination

  4. Sign in to your Algolia account and select the application you want to configure.
  5. Copy your application ID and search API key from the dashboard and paste it into Segment.

    Add your Algolia credentials

For more information about adding destinations, go to the Segment documentation.

Enable clickAnalytics

To relate click and conversion events to searches, Algolia needs a query ID. To get the queryID parameter for a search, set the clickAnalytics parameter to true:

1
2
3
4
5
6
index.search('YourSearchQuery', {
  userToken: 'user-1',
  clickAnalytics: true
}).then(({ hits, queryID }) => {
  console.log(hits, queryID);
})

Identify users

If you use Segment’s analytics.identify() function to identify users, use the same identifier for Algolia by passing it as the userToken parameter with your search. For example, if you want to use Personalization:

1
2
3
4
5
6
index.search('YourSearchQuery', {
  userToken: 'user-1',
  enablePersonalization: true
}).then(({ hits }) => {
  console.log(hits);
})

Algolia requires these properties that aren’t part of the regular Segment specifications:

Property Type Required?
index string Yes
eventType value: 'view', 'click', or 'conversion' Yes
eventSubtype value: 'addToCart' or 'purchase' (only applicable to 'conversion' events) No
queryID string No
objectIDs string[] or objectID: string No
positions number[] or position: number No
filters Array<{ type: string; value: string; }> or string[] (${type}:${value}—for example, brand:apple) No
objectData See the Insights API reference for the objectData parameter (only applicable to 'addToCart' and 'purchase' events) No

For more information, see the Insights API reference.

You can get these properties with the following code:

1
2
3
4
5
6
7
8
index.search('query', {
  userToken: 'user-1',
}).then(({ hits, queryID, hitsPerPage, page }) => {
  hits.map((hit, index) => {
    const position = index + 1 + page * hitsPerPage;
    const objectID = hit.objectID;
  });
});

The following code is an example of a click event tracked with Segment that includes all the necessary Algolia-related properties:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
analytics.track('Product Clicked', {
  product_id: '507f1f77bcf86cd799439011',
  sku: 'G-32',
  category: 'Games',
  name: 'Monopoly: 3rd Edition',
  brand: 'Hasbro',
  variant: '200 pieces',
  price: 18.99,
  quantity: 1,
  coupon: 'MAYDEALS',
  position: 3,
  url: 'https://www.example.com/product/path',
  image_url: 'https://www.example.com/product/path.jpg',
  // Algolia-related properties
+ index: 'my-algolia-index',
+ eventType: 'click',
+ queryID: 'fd0bbaadc287937s7671d00f1d053b88',
+ objectID: '131280270'
});

Refer to Segment’s Algolia Insights destination documentation for details on which Segment events are supported by default.

Debug events with Segment

If you have administrator permissions for your Segment source, you can send test events. To do this, select your source and click Validate. Select Algolia Insights as the destination.

Check events in the Segment app

Now, you can send a test event using the Event builder or JSON editor.

Send a test event to the Algolia Insights destination

A green box with the status “200 OK” means that Segment successfully sent a test event to the Algolia Insights destination. To check, if the event delivery was successful, go to the Event Delivery tab.

For example, sending an event with a wrong queryID shows a Delivery Issue.

To check if Algolia receives your events correctly, go to the Events Debugger in the Algolia dashboard. For more information, see Validate your events.

Did you find this page helpful?