Guides / Getting insights and analytics / Connectors / Segment

Mar. 12, 2021

Supported Events

Product List Viewed

Segment spec

Segment contextual parameters used by Algolia

userId: an identifier for logged-in users. Can be set through analytics.identify. Maps to userToken in the Insights event payload.
anonymousId: an identifier for non logged-in users. Maps to userToken in the Insights event payload when userId wasn’t set through analytics.identify.

You can read more about Segments Identities.

Extra parameters required by Algolia

products.$.objectID: the objectID of the record. Maps to objectIDs in the Insights event payload.
index: Name of the targeted index. Maps to index in the Insights event payload.

Copy
analytics.identify('user-1'); // only if user is logged in

analytics.track('Product List Viewed', {
  products: [
    {
      objectID: '507f1f77bcf86cd799439011',  // Algolia specific, required
      // ...
    },
    {
      objectID: '505bd76785ebb509fc183733',
      // ...
    }
  ],
  index: "<YOUR_ALGOLIA_INDEX>",  // Algolia specific, required
  // ...
});

This code sends the following payload to the Insights REST API:

Copy
{
  "eventType": "view",
  "eventName": "Product List Viewed",
  "userToken": "user-1",
  "index": "<YOUR_ALGOLIA_INDEX>",
  "objectIDs": [ "507f1f77bcf86cd799439011", "505bd76785ebb509fc183733" ]
}

You should to trigger the Product List Viewed event every time a user receives a new set of results.

To achieve this with InstantSearch, you can combine a debouncing function with the hits connector and send Product List Viewed every time new results are presented to the user.

Note that the browser library and the Node.js library from Segment have different interfaces.

Copy

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
27
28
29
index.search({ query: "my query", clickAnalytics: true }, (err, result) => {
  // Let's assume that `result.hits` are rendered
  // and our user has viewed the list.

  // ...

  // The following code will send an event to Segment
  // along with the information of the list.
  analytics.track("Product List Viewed", {
    list_id: undefined,
    category: undefined,
    products: result.hits.map(hit => ({
      objectID: hit.objectID, // Extra parameters required by Algolia
      product_id: hit.product_id,
      sku: hit.objectID,
      category: hit.categories[0],
      name: hit.name,
      brand: hit.brand,
      variant: undefined,
      price: hit.price,
      quantity: 1,
      coupon: undefined,
      position: hit.__position,
      url: undefined,
      image_url: hit.image
    })),
    index: indexName // Extra parameters required by Algolia
  });
});

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
27
28
29
30
31
32
33
index.search({ query: "my query", clickAnalytics: true }, (err, result) => {
  // Let's assume that `result.hits` are rendered
  // and our user has viewed the list.

  // ...

  // The following code will send an event to Segment
  // along with the information of the list.
  analytics.track({
    userId: userId,
    event: "Product List Viewed",
    properties: {
      list_id: undefined,
      category: undefined,
      products: result.hits.map(hit => ({
        objectID: hit.objectID, // Extra parameters required by Algolia
        product_id: hit.product_id,
        sku: hit.objectID,
        category: hit.categories[0],
        name: hit.name,
        brand: hit.brand,
        variant: undefined,
        price: hit.price,
        quantity: 1,
        coupon: undefined,
        position: hit.__position,
        url: undefined,
        image_url: hit.image
      })),
      index: indexName // Extra parameters required by Algolia
    }
  });
});

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Required: InstantSearch.js >= 4.8.3

search.use(
  instantsearch.middlewares.createInsightsMiddleware({
    insightsClient: null,
    onEvent(event) {
      const { widgetType, eventType, payload, hits } = event;
      if (widgetType === "ais.hits" && eventType === "view") {
        analytics.track("Product List Viewed", {
          index: payload.index,
          products: hits.map((hit) => ({
            objectID: hit.objectID,
            // the rest...
          })),
        });
      }
    },
  })
);

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
function debounce(fn, delay) {
    let timerId;
    return function(...args) {
      if (timerId) {
        clearTimeout(timerId);
      }
      timerId = setTimeout(() => {
        fn(...args);
        timerId = null;
      }, delay);
    };
  }

  const debouncedHitsRender = debounce(({ hits }) => {
    const products = hits.map(hit => ({
      objectID: hit.objectID,
      // ...
    }));
    products.length > 0 && console.log(products);
  }, 500);

  const CustomHits = connectHits((...args) => {
    debouncedHitsRender(...args);
    return null;
  });

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
import { Component, OnInit, forwardRef, Inject } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectHits } from 'instantsearch.js/es/connectors';

function debounce(fn, delay: number) {
  let timerId;
  return function(...args) {
    if (timerId) {
      clearTimeout(timerId);
    }
    timerId = setTimeout(() => {
      fn(...args);
      timerId = null;
    }, delay);
  };
}

const track = debounce(hits => {
  const products = hits.map(hit => ({
    objectID: hit.objectID,
    // ...
  }));
  analytics.track('Product List Viewed', () => ({
    products
  }));
}, 500);

@Component({
  selector: 'app-tracker',
  template: ``
})
export class TrackerComponent extends BaseWidget implements OnInit {
  public state: {
    hits: any[];
  };

  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('Tracker');
  }

  public ngOnInit() {
    this.createWidget(connectHits, {});
    super.ngOnInit();
  }

  updateState = state => {
    if (!state.hits || state.hits.length === 0) {
      return;
    }
    track(state.hits);
  };
}

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<!-- Required: Vue InstantSearch >= 3.7.0 -->

<template>
  <ais-instant-search
    :index-name="<index-name>"
    :search-client="searchClient"
    :middlewares="middlewares"
  >
    <!-- widgets -->
  </ais-instant-search>
</template>

<script>
import {
  createInsightsMiddleware,
} from 'instantsearch.js/es/middlewares';

const insightsMiddleware = createInsightsMiddleware({
  insightsClient: aa,
  onEvent(event) {
    const { widgetType, eventType, payload, hits } = event;

    if (widgetType === 'ais.hits' && eventType === 'view') {
      analytics.track('Product List Viewed', {
        index: payload.index,
        products: hits.map(hit => ({
          objectID: hit.objectID,
          // the rest...
        })),
      });
    }
  }
});

export default {
  data() {
    return {
      // ...
      middlewares: [insightsMiddleware]
    }
  },
}
</script>

Product List Filtered

Segment spec

Segment parameters used by Algolia

filters.$.type: the facet name in the filter applied
filters.$.value: the facet value in the filter applied

filters map to filters in the Insights event payload.

Segment contextual parameters used by Algolia

userId: an identifier for logged-in users. Can be set through analytics.identify. Maps to userToken in the Insights event payload.
anonymousId: an identifier for non logged-in users. Maps to userToken in the Insights event payload when userId wasn’t set through analytics.identify.

You can read more about Segments Identities.

Extra parameters required by Algolia

index: Name of the targeted index. Maps to index in the Insights event payload.

Copy
analytics.identify('user-1'); // only if user is logged in

analytics.track('Product List Filtered', {
  filters: [
    {
      type: 'department',
      value: 'beauty'
    },
    {
      type: 'price',
      value: 'under-$25'
    },
  ],
  index: '<YOUR_ALGOLIA_INDEX>', // Algolia specific, required
  // ...
});

This code sends the following payload to the Insights REST API:

Copy
{
  "eventType": "click",
  "eventName": "Product List Filtered",
  "userToken": "user-1",
  "index": "<YOUR_ALGOLIA_INDEX>",
  "filters": [ "department:beauty", "price:under-$25" ]
}

You should to trigger Product List Filtered every time a user has interacted with a refinement widget. Example refinements widgets are refinementList and rangeSlider. See the full list of refinement widgets for more.

To hook a Product List Filtered event trigger to an InstantSearch refinement widget, it’s best to use the widget’s connector form. Here is an example using the refinementList.

Copy

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
27
28
29
30
31
32
33
34
index.search({ query: "my query", clickAnalytics: true }, (err, result) => {
  // Let's assume that `result.hits` are rendered
  // and our user has filtered the list.

  // And let's assume that `filters` contains what user filtered with.
  const filters = [
    {
      type: "brand",
      value: "..."
    }
  ];

  // The following code will send an event to Segment
  // along with the information of the list and the filters.
  analytics.track("Product List Filtered", {
    list_id: undefined,
    filters: filters, // Segment parameters used by Algolia
    products: result.hits.map(hit => ({
      product_id: hit.product_id,
      sku: hit.objectID,
      category: hit.categories[0],
      name: hit.name,
      brand: hit.brand,
      variant: undefined,
      price: hit.price,
      quantity: 1,
      coupon: undefined,
      position: hit.__position,
      url: undefined,
      image_url: hit.image
    })),
    index: indexName // Extra parameters required by Algolia
  });
});

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
27
28
29
30
31
32
33
34
35
36
37
38
index.search({ query: "my query", clickAnalytics: true }, (err, result) => {
  // Let's assume that `result.hits` are rendered
  // and our user has filtered the list.

  // And let's assume that `filters` contains what user filtered with.
  const filters = [
    {
      type: "brand",
      value: "..."
    }
  ];

  // The following code will send an event to Segment
  // along with the information of the list and the filters.
  analytics.track({
    userId: userId,
    event: "Product List Filtered",
    properties: {
      list_id: undefined,
      filters: filters, // Segment parameters used by Algolia
      products: result.hits.map(hit => ({
        product_id: hit.product_id,
        sku: hit.objectID,
        category: hit.categories[0],
        name: hit.name,
        brand: hit.brand,
        variant: undefined,
        price: hit.price,
        quantity: 1,
        coupon: undefined,
        position: hit.__position,
        url: undefined,
        image_url: hit.image
      })),
      index: indexName // Extra parameters required by Algolia
    }
  });
});

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Required: InstantSearch.js >= 4.8.3

search.use(
  instantsearch.middlewares.createInsightsMiddleware({
    insightsClient: null,
    onEvent(event) {
      const { widgetType, eventType, payload, attribute } = event;
      if (widgetType === 'ais.refinementList' && eventType === 'click') {
        analytics.track('Product List Filtered', {
          index: payload.index,
          filters: payload.filters.map(filter => ({
            type: attribute,
            value: filter,
          })),
        });
      }
    },
  })
);

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
27
28
29
30
const CustomRefinementList = connectRefinementList(({ items, refine }) => (
  <div>
    {items.map(item => (
      <label key={item.label}>
        <input
          type="checkbox"
          value={item.isRefined}
          onClick={event => {
            refine(item.value);

            if (!item.isRefined) {
              analytics.track("Product List Filtered", {
                filters: [
                  {
                    type: "brand",
                    value: item.value
                  }
                ],
                index: "..."
              });
            }
          }}
        />
        {item.label} ({item.count})
      </label>
    ))}
  </div>
));

<RefinementList attribute="brand" />;

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import { Component, Inject, forwardRef } from "@angular/core";
import { BaseWidget, NgAisInstantSearch } from "angular-instantsearch";
import { connectRefinementList } from "instantsearch.js/es/connectors";

@Component({
  selector: "app-refinement-list",
  template: `
    <label *ngFor="let item of state.items">
      <input
        type="checkbox"
        (click)="state.refine(item.value); track(item);"
        [checked]="item.isRefined"
      />
      {{ item.label }} ({{ item.count }})
    </label>
  `
})
export class RefinementList extends BaseWidget {
  public state: {
    items: object[];
    refine: Function;
    createURL: Function;
    isFromSearch: boolean;
    searchForItems: Function;
    isShowingMore: boolean;
    canToggleShowMore: boolean;
    toggleShowMore: Function;
    widgetParams: object;
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super("RefinementList");
  }
  ngOnInit() {
    this.createWidget(connectRefinementList, {
      attribute: "brands"
    });
    super.ngOnInit();
  }
  track(item) {
    analytics.track("Product List Filtered", {
      filters: [
        {
          type: "brand",
          value: elem.value
        }
      ],
      index: "..."
    });
  }
}

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<!-- Required: Vue InstantSearch >= 3.7.0 -->

<template>
  <ais-instant-search
    :index-name="<index-name>"
    :search-client="searchClient"
    :middlewares="middlewares"
  >
    <!-- widgets -->
  </ais-instant-search>
</template>

<script>
import {
  createInsightsMiddleware,
} from 'instantsearch.js/es/middlewares';

const insightsMiddleware = createInsightsMiddleware({
  insightsClient: aa,
  onEvent(event) {
    const { widgetType, eventType, payload, attribute } = event;

    if (widgetType === 'ais.refinementList' && eventType === 'click') {
      analytics.track('Product List Filtered', {
        index: payload.index,
        filters: payload.filters.map(filter => ({
          type: attribute,
          value: filter,
        })),
      });
    }
  }
});

export default {
  data() {
    return {
      // ...
      middlewares: [insightsMiddleware]
    }
  },
}
</script>

Product Clicked

Segment Spec

Segment parameters used by Algolia

position: the absolute position of the record. Maps to positions in the Insights event payload. The position starts with 1 (not 0).

Segment contextual parameters used by Algolia

userId: an identifier for logged-in users. Can be set through analytics.identify. Maps to userToken in the Insights event payload.
anonymousId: an identifier for non logged-in users. Maps to userToken in the Insights event payload when userId wasn’t set through analytics.identify.

You can read more about Segments Identities.

Extra parameters required by Algolia

queryID: Required only for Click Analytics. Algolia queryID that can be found in the search response when using clickAnalytics. Maps to queryID in the Insights event payload.
objectID: the objectID of the record. Maps to objectIDs in the Insights event payload.
index: Name of the targeted index. Maps to index in the Insights event payload.

Copy
analytics.identify('user-1'); // only if user is logged in

analytics.track('Product Clicked', {
  objectID: '507f1f77bcf86cd799439011',  // Algolia specific, required
  position: 3,
  index: "<YOUR_ALGOLIA_INDEX>",  // Algolia specific, required
  queryID: "<YOUR_QUERY_ID>",  // Algolia specific, required for Analytics, optional 
  // ...
});

This code sends the following payload to the Insights REST API:

Copy
{
  "eventType": "click",
  "eventName": "Product Clicked",
  "userToken": "user-1",
  "index": "<YOUR_ALGOLIA_INDEX>",
  "queryID": "<YOUR_QUERY_ID>",
  "objectIDs": [ "507f1f77bcf86cd799439011" ],
  "positions": [ 3 ]
}

objectID and queryID are both available for each hit exposed in the hits and infiniteHits widgets for InstantSearch.

Copy

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
27
index.search({ query: "my query", clickAnalytics: true }, (err, result) => {
  // Let's assume that `result.hits` are rendered
  // and our user has clicked the first item.

  // ...

  // The following code will send an event to Segment
  // along with the information of the first item.
  const hit = result.hits[0];
  analytics.track("Product Clicked", {
    objectID: hit.objectID, // Extra parameters required by Algolia
    product_id: hit.product_id,
    sku: hit.objectID,
    category: hit.categories[0],
    name: hit.name,
    brand: hit.brand,
    variant: undefined,
    price: hit.price,
    quantity: 1,
    coupon: undefined,
    position: 1, // Segment parameters used by Algolia
    url: undefined,
    image_url: hit.image,
    index: indexName, // Extra parameters required by Algolia
    queryID: result.queryID // Extra parameters required by Algolia
  });
});

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
27
28
29
30
31
index.search({ query: "my query", clickAnalytics: true }, (err, result) => {
  // Let's assume that `result.hits` are rendered
  // and our user has clicked the first item.

  // ...

  // The following code will send an event to Segment
  // along with the information of the first item.
  const hit = result.hits[0];
  analytics.track({
    userId: userId,
    event: "Product Clicked",
    properties: {
      objectID: hit.objectID, // Extra parameters required by Algolia
      product_id: hit.product_id,
      sku: hit.objectID,
      category: hit.categories[0],
      name: hit.name,
      brand: hit.brand,
      variant: undefined,
      price: hit.price,
      quantity: 1,
      coupon: undefined,
      position: 1, // Segment parameters used by Algolia
      url: undefined,
      image_url: hit.image,
      index: indexName, // Extra parameters required by Algolia
      queryID: result.queryID // Extra parameters required by Algolia
    }
  });
});

Copy

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
27
28
29
30
31
32
33
34
35
36
37
38
// Required: InstantSearch.js >= 4.8.3

search.addWidgets([
  hits({
    container: '#hits',
    templates: {
      item: (hit, bindEvent) => {
        const result = `
        <article>
          <h1>${instantsearch.highlight({ attribute: 'name', hit })}</h1>
          <button type="button" ${bindEvent('view', hit, 'View')}>
            View Product
          </button>
        </article>
      `;
        return result;
      },
    },
  }),
]);

search.use(
  instantsearch.middlewares.createInsightsMiddleware({
    insightsClient: null,
    onEvent(event) {
      const { payload } = event;
      if (payload.eventName === 'Favorite') {
        analytics.track('Product Clicked', {
          objectID: payload.objectIDs[0],
          position: payload.positions[0],
          index: payload.index,
          queryID: payload.queryID,
          // the rest...
        });
      }
    },
  })
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { Configure, Hits } from "react-instantsearch-dom";

const Hit = ({ hit }) => (
  <article>
    <h1>{hit.name}</h1>

    <button
      onClick={() =>
        analytics.track("Product Clicked", {
          objectID: hit.objectID,
          position: hit.__position,
          index: "...",
          queryID: hit.__queryID
        })
      }
    >
      Add to favorite
    </button>
  </article>
);

<Configure clickAnalytics />
<Hits hitComponent={Hit} />

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<ais-configure [searchParameters]="{ clickAnalytics: true }" />
<ais-hits>
  <ng-template let-hits="hits" let-results="results">
    <div *ngFor="let hit of hits">
      <ais-highlight attribute="name" [hit]="hit"></ais-highlight>
      <button
        (click)="
          analytics.track('Product Clicked', {
            objectID: hit.objectID,
            position: hit.__position,
            index: '...',
            queryID: hit.__queryID
          })
        "
      >
        Favorite
      </button>
    </div>
  </ng-template>
</ais-hits>

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
<!-- Required: Vue InstantSearch >= 3.7.0 -->

<template>
  <ais-instant-search
    :index-name="<index-name>"
    :search-client="searchClient"
    :middlewares="middlewares"
  >
    <ais-hits>
      <div slot-scope="{ items, sendEvent }">
        <div v-for="item in items">
          <h1>{{ item.name }}</h1>
          <button
            @click="
              sendEvent('click', hit, 'Favorite')
            "
          >
            Add to favorite
          </button>
        </div>
      </div>
    </ais-hits>
  </ais-instant-search>
</template>

<script>
import {
  createInsightsMiddleware,
} from 'instantsearch.js/es/middlewares';

const insightsMiddleware = createInsightsMiddleware({
  insightsClient: aa,
  onEvent(event) {
    const { widgetType, eventType, payload, hits } = event;

    if (payload.eventName === 'Favorite') {
      analytics.track('Product Clicked', {
        objectID: payload.objectIDs[0],
        position: payload.positions[0],
        index: payload.index,
        queryID: payload.queryID,
        // the rest...
      });
    }
  }
});

export default {
  data() {
    return {
      // ...
      middlewares: [insightsMiddleware]
    }
  },
}
</script>

Product Added

Segment spec

Segment contextual parameters used by Algolia

userId: an identifier for logged-in users. Can be set through analytics.identify. Maps to userToken in the Insights event payload.
anonymousId: an identifier for non logged-in users. Maps to userToken in the Insights event payload when userId wasn’t set through analytics.identify.

You can read more about Segments Identities.

Extra parameters required by Algolia

queryID: Required only for Click Analytics. Algolia queryID that can be found in the search response when using clickAnalytics. Maps to queryID in the Insights event payload.
objectID: the objectID of the record. Maps to objectIDs in the Insights event payload.
index: Name of the targeted index. Maps to index in the Insights event payload.

Copy
analytics.identify('user-1'); // only if user is logged in

analytics.track('Product Added', {
  objectID: '507f1f77bcf86cd799439011',  // Algolia specific, required
  index: "<YOUR_ALGOLIA_INDEX>",  // Algolia specific, required
  queryID: "<YOUR_QUERY_ID>",  // Algolia specific, required for Analytics, optional 
  // ...
});

This code sends the following payload to the Insights REST API:

Copy
{
  "eventType": "conversion",
  "eventName": "Product Added",
  "userToken": "user-1",
  "index": "<YOUR_ALGOLIA_INDEX>",
  "objectIDs": [ "507f1f77bcf86cd799439011" ]
}

Product Viewed

Segment spec

Segment contextual parameters used by Algolia

userId: an identifier for logged-in users. Can be set through analytics.identify. Maps to userToken in the Insights event payload.
anonymousId: an identifier for non logged-in users. Maps to userToken in the Insights event payload when userId wasn’t set through analytics.identify.

You can read more about Segments Identities.

Extra parameters required by Algolia

objectID: the objectID of the record. Maps to objectIDs in the Insights event payload.
index: Name of the targeted index. Maps to index in the Insights event payload.

Copy
analytics.identify('user-1'); // only if user is logged in

analytics.track('Product Viewed', {
  objectID: '507f1f77bcf86cd799439011',  // Algolia specific, required
  index: "<YOUR_ALGOLIA_INDEX>",  // Algolia specific, required
  // ...
});

This code sends the following payload to the Insights REST API:

Copy
{
  "eventType": "view",
  "eventName": "Product Viewed",
  "userToken": "user-1",
  "index": "<YOUR_ALGOLIA_INDEX>",
  "objectIDs": [ "507f1f77bcf86cd799439011" ]
}

Order Completed

Segment Spec

Segment contextual parameters used by Algolia

userId: an identifier for logged-in users. Can be set through analytics.identify. Maps to userToken in the Insights event payload.
anonymousId: an identifier for non logged-in users. Maps to userToken in the Insights event payload when userId wasn’t set through analytics.identify.

You can read more about Segments Identities.

Extra parameters required by Algolia

queryID: Required only for Click Analytics. Algolia queryID that can be found in the search response when using clickAnalytics. Maps to queryID in the Insights event payload.
producs.$.objectID: the objectID of the record. Maps to objectIDs in the Insights event payload.
index: Name of the targeted index. Maps to index in the Insights event payload.

Copy
analytics.identify('user-1'); // only if user is logged in

analytics.track('Order Completed', {
  products: [
    {
      objectID: '507f1f77bcf86cd799439011', // Algolia specific, required
      // ...
    },
    {
      objectID: '505bd76785ebb509fc183733',
      // ...
    }
  ],
  index: '<YOUR_ALGOLIA_INDEX>', // Algolia specific, required
  queryID: "<YOUR_QUERY_ID>", // Algolia specific, required for Analytics, optional for Personalization
  // ...
});

This code sends the following payload to the Insights REST API:

Copy
{
  "eventType": "conversion",
  "eventName": "Order Completed",
  "userToken": "user-1",
  "index": "<YOUR_ALGOLIA_INDEX>",
  "objectIDs": [ "507f1f77bcf86cd799439011", "505bd76785ebb509fc183733" ]
}

Since Order Completed usually occurs outside the context of InstantSearch, you have to persist the objectID, queryID and index of the records ordered. This will allow Algolia to bind a conversion event to its specific query.

objectID and queryID are both available for each hit exposed in the hits and infiniteHits widgets for InstantSearch. For example if you need to pass them through the URL you can do the following:

Copy

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
index.search({ query: "my query", clickAnalytics: true }, (err, result) => {
  // Let's assume that `result.hits` are rendered,
  // user added the first two items to their cart,
  // and they completed the order.

  // ...

  // The following code will send an event to Segment
  // along with the information of the two items.
  const cartItems = [result.hits[0], result.hits[1]];

  analytics.track("Order Completed", {
    checkout_id: "cvssd800083888004771002",
    order_id: "50314b8e9bcf000000000000",
    affiliation: "Google Store",
    total: 27.50,
    subtotal: 22.50,
    revenue: 25.00,
    shipping: 3,
    tax: 2,
    discount: 2.5,
    coupon: "hasbros",
    currency: "USD",
    products: cartItems.map(hit => ({
      objectID: hit.objectID, // Extra parameters required by Algolia
      product_id: hit.product_id,
      sku: hit.objectID,
      category: hit.categories[0],
      name: hit.name,
      brand: hit.brand,
      variant: undefined,
      price: hit.price,
      quantity: 1,
      coupon: undefined,
      position: hit.__position,
      url: undefined,
      image_url: hit.image
    })),
    index: indexName, // Extra parameters required by Algolia
    queryID: result.queryID // Extra parameters required by Algolia
  });
});

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
index.search({ query: "my query", clickAnalytics: true }, (err, result) => {
  // Let's assume that `result.hits` are rendered,
  // user added the first two items to their cart,
  // and they completed the order.

  // ...

  // The following code will send an event to Segment
  // along with the information of the two items.
  const cartItems = [result.hits[0], result.hits[1]];

  analytics.track({
    userId: userId,
    event: "Order Completed",
    properties: {
      checkout_id: "cvssd800083888004771002",
      order_id: "50314b8e9bcf000000000000",
      affiliation: "Google Store",
      total: 27.50,
      subtotal: 22.50,
      revenue: 25.00,
      shipping: 3,
      tax: 2,
      discount: 2.5,
      coupon: "hasbros",
      currency: "USD",
      products: cartItems.map(hit => ({
        objectID: hit.objectID, // Extra parameters required by Algolia
        product_id: hit.product_id,
        sku: hit.objectID,
        category: hit.categories[0],
        name: hit.name,
        brand: hit.brand,
        variant: undefined,
        price: hit.price,
        quantity: 1,
        coupon: undefined,
        position: hit.__position,
        url: undefined,
        image_url: hit.image
      })),
      index: indexName, // Extra parameters required by Algolia
      queryID: result.queryID // Extra parameters required by Algolia
    }
  });
});

Copy

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// Required: InstantSearch.js >= 4.8.3

search.addWidgets([
  hits({
    container: '#hits',
    templates: {
      item: (hit, bindEvent) => {
        const result = `
        <article>
          <h1>${instantsearch.highlight({ attribute: 'name', hit })}</h1>
          <button type="button" ${bindEvent('conversion', hit, 'Order')}>
            Order Now
          </button>
        </article>
      `;
        return result;
      },
    },
  }),
]);

search.use(
  instantsearch.middlewares.createInsightsMiddleware({
    insightsClient: null,
    onEvent(event) {
      const { payload, hits } = event;
      if (payload.eventName === 'Order') {
        analytics.track('Order Completed', {
          products: hits.map(hit => ({
            objectID: hit.objectID,
            // the rest...
          })),
          index: payload.index,
          queryID: hits[0].__queryID,
          // the rest...
        });
      }
    },
  })
);

1
2
3
4
5
6
7
8
9
// Pass the related data to the product page.
// Then, in the product page, you can send events by using `analytics.track()`.
const Hit = ({ hit }) => (
  <a href={`/product.html?objectID=${hit.objectID}&queryID=${hit.__queryID}&index=my-index`}>
    <h1>{hit.name}</h1>
  </a>
);

<Hits hitComponent={Hit} />

1
2
3
4
5
6
7
8
9
10
11
// Pass the related data to the product page.
// Then, in the product page, you can send events by using `analytics.track()`.
<ais-hits>
  <ng-template let-hits="hits">
    <div *ngFor="let hit of hits">
      <a href="/product?objectID={{hit.objectID}}&queryID={{hit.__queryID}}&index=my-index">
        <ais-highlight attribute="name" [hit]="hit"></ais-highlight>
      </a>
    </div>
  </ng-template>
</ais-hits>

1
2
3
4
5
6
7
8
9
10
11
<ais-hits>
  <div slot-scope="{ items }">
    <div v-for="item in items">
      // Pass the related data to the product page.
      // Then, in the product page, you can send events by using `analytics.track()`.
      <a href="/product?objectID={{item.objectID}}&queryID={{item.__queryID}}&index=my-index">
        <h1>{{item.name}}</h1>
      </a>
    </div>
  </div>
</ais-hits>

Segment

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

Supported Events

On this page

Product List Viewed

Product List Filtered

Product Clicked

Product Added

Product Viewed

Order Completed

Did you find this page helpful?

On this page