Tag New and Returning Users

Analytics tags let you view subsets of your analytics data. This lets you better understand your user’s behavior. Analytics tags are strings that you conditionally assign to specific searches. These strings identify an aspect of the searches that clarify the behavior of a specific group of users.

Imagine you’re running a documentation website, and you want to see how your users interact with your search depending on their level of experience with it. A good way of measuring this is to differentiate between new and returning users.

Later on, when you consult your Algolia analytics data, you can better understand the behavior and needs of both your first time users, and your regular visitors.

This guide outlines the process step by step. It illustrates two ways of implementing analyticsTags: with InstantSearch and with the API clients.

Identifying new and returning users

There are many ways to determine whether a user is coming to your site for the first time or not. One way is by storing a cookie on the end users’ computer when they visit your website. When people visit your site, you can check for the cookie: if it’s there, then they visited your site before; otherwise, they’re likely new.

Your logic should first check for the presence of the cookie. If it’s there, you can set the current visitor as returning, and send this tag to Algolia when they make a search. Otherwise, you can mark them as new, and set the cookie so they’re identified as returning the next time.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const decodedCookies = decodeURIComponent(document.cookie).split(';');

const { myCookie: isReturning } = Object.assign(
  {},
  ...decodedCookies.map(cookie => {
    const [key, value] = cookie.split('=');
    return { [key.trim()]: value };
  })
);

const visitingStatus = isReturning ? 'Returning' : 'New';

if (!isReturning) {
  document.cookie = 'myCookie=1';
}

Determining new and returning users makes more sense on the front end, which is why there are no back-end snippets. Note that cookies aren’t a bulletproof way to store information, because users can tamper with them, delete them, or use different devices. Use this solution only if you don’t have a better one, such as user accounts with data stored in a database.

Assigning an analytics tag to a search

Whenever a user makes a search, you want to send whether they’re new or returning along with the query. You can do it whether you’re using InstantSearch, or an API client directly.

Using InstantSearch

If you’re using InstantSearch to build your front end, you can pass the analyticsTags parameter when making the query.

1
2
3
let query = Query()
query.analyticsTags = ["visitingStatus"]
let searcher = HitsSearcher(index: index, query: query)

1
2
3
4
5
6
7
val query = query {
    analyticsTags {
        +"visitingStatus"
    }
}

val searcher = HitsSearcher(client, index, query)

1
2
3
instantsearch.widgets.configure({
  analyticsTags: [visitingStatus]
});

1
2
3
<Configure
  analyticsTags={[visitingStatus]}
/>

1
2
3
<ais-configure
  :analytics-tags.camel="[visitingStatus]"
/>

1
2
3
<ais-configure
  [searchParameters]="{ analyticsTags: [visitingStatus] }"
></ais-configure>

Using an API client

You can also pass the analyticsTags parameter if you’re using one of the API clients.

1
2
3
index.search('', {
  analyticsTags: [visitingStatus]
});

Viewing segmented analytics data

After you’ve implemented, tested, and released your app with new and returning analyticsTags, you can start segmenting your new analytics data based on your user’s platform.

You can do this from the Analytics section of your Algolia dashboard. In the header of the Analytics tab you can find the Tags input field.

Once your users start making searches in your new search implementation, the new and returning analyticsTags appear in the Tags field. If you select returning, you only see analytics for searches with the returning tag. This is true for all Analytics subsections.

Depending on your traffic, you may have to wait to get enough tagged data to start drawing meaningful conclusions.