# Algolia Insights (Actions) Destination

## Destination Info

* Accepts [Page](/docs/segment/connections/spec/page), [Alias](/docs/segment/connections/spec/alias), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls.
* Refer to it as **Algolia Insights (Actions)** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)
* This integration is **partner owned.** Please reach out to the partner's support for any issues.

With the Algolia Insights (Actions) destination, you can send [Insights Events](https://www.algolia.com/doc/guides/sending-events/getting-started/). Insight Events are required to use these Algolia features:

* [Click and conversion analytics](https://www.algolia.com/doc/guides/search-analytics/overview/)
* [Algolia Recommend](https://www.algolia.com/doc/guides/algolia-recommend/overview/)
* [Personalization](https://www.algolia.com/doc/guides/personalization/classic-personalization/what-is-personalization/)
* [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/)
* [A/B Testing](https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing/)
* [Query Categorization](https://www.algolia.com/doc/guides/algolia-ai/query-categorization/)
* [NeuralSearch](https://www.algolia.com/doc/guides/getting-started/neuralsearch/)

This destination is maintained by [Algolia](https://www.algolia.com/). For any issues with the destination, [contact the Algolia team](mailto:hey@algolia.com).

## Getting Started

1. From the Destinations catalog page in the Segment App, click **Add Destination**.
2. Search for **Algolia** in the Destinations Catalog and select the **Algolia Insights (Actions)** destination.
3. Choose which Source should send data to the Algolia destination.
4. Sign in to the [Algolia dashboard](https://dashboard.algolia.com/users/sign_in) and retrieve your **App ID** and **API Key** for the application you'd like to connect. See **[Getting your Algolia credentials](#getting-your-algolia-credentials)** below for details on where to get these values.
5. Enter the **App ID** and **API Key** in the Algolia destination settings in Segment.

### Getting your Algolia credentials

Your app ID and API key can be found in the **API Keys** section of your account settings in the Algolia dashboard. You need a **search** API key to set up the destination.

![Algolia dashboard showing search requests, speed, recommend requests, and data sources.](https://docs-resources.prod.twilio.com/491a27fa3ce681eaf591d62d18dafbc2437806e9b4df9adf506f39230599a036.png)

![Algolia's Organization Settings menu with sections for General, Billing, and Team and Access.](https://docs-resources.prod.twilio.com/570343b7e23ada1192b4ada0ca415aa25b68fb3798d20f962e8ab5973c77e78d.png)

![Algolia API keys page showing Application ID and various API keys with regenerate options.](https://docs-resources.prod.twilio.com/f3bb96db4531dd71c86458b382fa363af9c4e0c05c15fb06d8747e91234b02fe.png)

### Algolia-related data

The Algolia Insights Destination is not a plug-and-play integration. It requires you to modify your frontend code to add additional Algolia-related data like an index name and a query ID.

To access your query ID, make sure [`clickAnalytics`](https://www.algolia.com/doc/api-reference/api-parameters/clickAnalytics/) is enabled in your searches. If you're using the [JavaScript v5 search API client](https://www.algolia.com/doc/libraries/javascript/v5/methods/search/search-single-index/?client=javascript), this looks like:

```js
import { algoliasearch } from 'algoliasearch';

const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');

const response = await client.searchSingleIndex({
  indexName: '<INDEX_NAME>',
  query: '<QUERY>',
  userToken: 'user-1',
  clickAnalytics: true
});
```

Once this is enabled, you will be able to access `queryID` in your search response, which you can then use in your Segment events.

You can read more about how to send Algolia-related data to Segment in the [Algolia documentation](https://www.algolia.com/doc/guides/sending-events/connectors/segment/#augment-your-segment-events-with-algolia-related-data).

## Mapping Events

By default, Algolia has set up mappings for `Product List Filtered`, `Product List Viewed`, `Product Viewed`, `Product Clicked`, `Product Added` and `Order Completed` events. If your event structure doesn't match Segment's [Ecommerce Spec](/docs/segment/connections/spec/ecommerce/v2/), you can update this in the destination mappings section of the Segment app.

![Algolia Insights mappings tab showing data mapping configurations with actions and status toggles.](https://docs-resources.prod.twilio.com/e3173ab6fd266225d4f5aa4796c52b15a4556277bffa69223f58b7090d741f4b.png)

### User identifiers

When mapping user identifiers, Algolia recommends using the **Authenticated User Token** field to map authenticated user IDs and the **User Token** field for anonymous user IDs. For more detail, see the [Algolia documentation](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/#persistent-user-token).

## Track

If you're not familiar with the Segment spec, take a look to understand what the [Track](/docs/segment/connections/spec/track/) method does.

Algolia supports the following Segment events out of the box:

| Supported Events        | Description                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `Product List Filtered` | Send this event when a visitor filters a product list or category.                        |
| `Product List Viewed`   | Send this event when a visitor views a product list or category.                          |
| `Product Viewed`        | Fire this event when a visitor views a product.                                           |
| `Product Clicked`       | Fire this event when a visitor clicks a product.                                          |
| `Product Added`         | Fire this event when a visitor adds a product to their shopping cart.                     |
| `Order Completed`       | Fire this event whenever an order/transaction was successfully completed by the customer. |

For a full list of required properties for each event type, see [Spec: V2 Ecommerce Events](/docs/segment/connections/spec/ecommerce/v2/)

```js
analytics.track('Product List Filtered', {
  search_index: "my-index-name",
  filters: [
    {
      attribute: "color",
      value: "yellow",
    }
  ],
  query_id: "Algolia queryID", // required only for Click Analytics,
  // ... other required properties from the spec
})

analytics.track('Product List Viewed', {
  search_index: "my-index-name",
  products: [
    {
      product_id: "hit objectID",
    },
    {
      product_id: "hit objectID 2",
    },
  ],
  query_id: "Algolia queryID", // required only for Click Analytics,
  // ... other required properties from the spec
})

analytics.track('Product Viewed', {
  search_index: "my-index-name",
  product_id: "hit objectID",
  query_id: "Algolia queryID", // required only for Click Analytics,
  // ... other required properties from the spec
})

analytics.track('Product Clicked', {
  search_index: "my-index-name",
  product_id: "hit objectID",
  position: hitPositionOnIndex, // number
  query_id: "Algolia queryID", // required only for Click Analytics,
  // ... other required properties from the spec
})

// This 
analytics.track('Product Added', {
  search_index: "my-index-name",
  product_id: "hit objectID",
  query_id: "Algolia queryID", // required only for Click Analytics,
  // ... other required properties from the spec
})

analytics.track('Order Completed', {
  search_index: "my-index-name",
  products: [
    {
      product_id: "hit objectID",
      queryID: "Algolia queryID",
        // ...
    },
    // ... other required properties from the spec
  ]
})
```

> \[!NOTE]
>
> If you send anonymous activity to Algolia, Algolia does not connect it to activity attributed to that same user once they are identified.

## Engage

You can send computed traits and audiences generated using [Engage](/docs/segment/engage) to this destination as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/contact/demo).

For user-property destinations, an [identify](/docs/segment/connections/spec/identify/) call is sent to the destination for each user being added and removed. The property name is the snake\_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to `false`.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

> \[!NOTE]
>
> Real-time audience syncs to Algolia Insights (Actions)  may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.

## Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

| Field                    | Description                                                                  | Required | Type     |
| ------------------------ | ---------------------------------------------------------------------------- | -------- | -------- |
| apiKey                   | An API key which has write permissions to the Algolia Insights API           | Yes      | password |
| appId                    | Your Algolia Application ID.                                                 | Yes      | string   |
| QueryID QueryString Name | QueryString name you use for when storing the Algolia QueryID in a page URL. | No       | string   |