Have ideas to improve npm?Join in the discussion! »

    search-insights
    TypeScript icon, indicating that this package has built-in type declarations

    1.8.0 • Public • Published

    Search Insights

    Build Status npm version

    Search Insights lets you report click, conversion and view metrics using the Algolia Insights API.

    Table of Contents

    Getting started

    Are you using Google Tag Manager in your app? We provide a custom template to ease the integration.

    Browser

    1. Load the library

    The Search Insights library can be either loaded via jsDelivr CDN or directly bundled with your application. We recommend loading the library by adding the snippet below to all pages where you wish to track search analytics.

    <script>
    var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/search-insights@1.8.0";
    
    !function(e,a,t,n,s,i,c){e.AlgoliaAnalyticsObject=s,e[s]=e[s]||function(){
    (e[s].queue=e[s].queue||[]).push(arguments)},i=a.createElement(t),c=a.getElementsByTagName(t)[0],
    i.async=1,i.src=n,c.parentNode.insertBefore(i,c)
    }(window,document,"script",ALGOLIA_INSIGHTS_SRC,"aa");
    </script>

    2. Initialize the library

    aa('init', {
      appId: 'APP_ID',
      apiKey: 'SEARCH_API_KEY',
    });
    
    // Optional: set the analytics user ID
    aa('setUserToken', 'USER_ID');
    Option Type Default Description
    appId string None (required) The identifier of your Algolia application
    apiKey string None (required) The search API key of your Algolia application
    userHasOptedOut boolean false Whether to exclude users from analytics
    region 'de' | 'us' Automatic The DNS server to target
    useCookie boolean true Whether to use cookie in browser environment. The anonymous user token will not be set if false. When useCookie is false and setUserToken is not called yet, sending events will throw errors because there is no user token to attach to the events.
    cookieDuration number 15552000000 (6 months) The cookie duration in milliseconds
    userToken string undefined (optional) Initial userToken. When given, anonymous userToken will not be set.

    Node.js

    (Node.js >= 8.16.0 required)

    1. Install the library

    Insights library can be used on the backend as a Node.js module.

    npm install search-insights
    # or
    yarn add search-insights

    2. Initialize the library

    const aa = require('search-insights');
    
    aa('init', {
      appId: 'APPLICATION_ID',
      apiKey: 'SEARCH_API_KEY'
    });

    Add userToken

    On the Node.js environment, unlike the browser environment, userToken must be specified when sending any event.

    aa('clickedObjectIDs', {
      userToken: 'USER_ID',
      // ...
    });

    Customize the client

    If you want to customize the way to send events, you can create a custom Insights client.

    // via ESM
    import { createInsightsClient } from "search-insights";
    // OR in commonJS
    const { createInsightsClient } = require("search-insights");
    // OR via the UMD
    const createInsightsClient = window.AlgoliaAnalytics.createInsightsClient;
    
    function requestFn(url, data) {
      const serializedData = JSON.stringify(data);
      const { protocol, host, path } = require("url").parse(url);
      const options = {
        protocol,
        host,
        path,
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Content-Length": serializedData.length
        }
      };
    
      const { request: nodeRequest } =
        url.indexOf("https://") === 0 ? require("https") : require("http");
      const req = nodeRequest(options);
    
      req.on("error", error => {
        console.error(error);
      });
    
      req.write(serializedData);
      req.end();
    };
    
    const aa = createInsightsClient(requestFn);

    Use cases

    The Search Insights library supports both Search and Personalization Algolia features.

    Search (Click Analytics and A/B testing)

    Initialize

    To enable click analytics, the search parameter clickAnalytics must be set to true. This tells the Algolia engine to return a queryID on each search request.

    const searchClient = algoliasearch('APPLICATION_ID', 'SEARCH_API_KEY');
    const search = instantsearch({
      indexName: 'INDEX_NAME',
      searchClient,
      searchParameters: {
        clickAnalytics: true,
      },
    });
    
    function getQueryID() {
      return search.helper.lastResults.queryID;
    }

    Report a click event

    aa('clickedObjectIDsAfterSearch', {
      index: 'INDEX_NAME',
      eventName: 'Click item',
      queryID: getQueryID(),
      objectIDs: ['object1'],
      positions: [42],
    });
    Option Type Description
    index string The name of the index related to the event
    eventName string The name of the event
    objectIDs string[] The list of IDs of the result that was clicked
    positions number[] The list of the absolute positions of the HTML element that was clicked (1-based and not 0-based)
    queryID string The queryID of the search sent from Algolia

    Report a conversion event

    aa('convertedObjectIDsAfterSearch', {
      index: 'INDEX_NAME',
      eventName: 'Add to basket',
      queryID: getQueryID(),
      objectIDs: ['object1'],
    });
    Option Type Description
    index string The name of the index related to the event
    eventName string The name of the event
    objectIDs string[] The list of IDs of the result that was clicked
    queryID string The queryID of the search sent from Algolia

    Personalization

    Initialize

    To enable personalization, the search parameter enablePersonalization must be set to true.

    const searchClient = algoliasearch('APPLICATION_ID', 'SEARCH_API_KEY');
    const search = instantsearch({
      indexName: 'INDEX_NAME',
      searchClient,
      searchParameters: {
        enablePersonalization: true,
      },
    });

    Access userToken

    In cases where the userToken is generated, you need a way to access the userToken so that you can pass it to the searchClient.

    const searchClient = algoliasearch('APPLICATION_ID', 'SEARCH_API_KEY');
    
    aa('getUserToken', null, (err, userToken) => {
      // for algoliasearch v3.x
      searchClient.setExtraHeader('X-Algolia-UserToken', userToken);
    
      // for algoliasearch v4.x
      searchClient.transporter.headers['X-Algolia-UserToken'] = userToken;
    });

    Listen to userToken change

    If you want to attach a listener for userToken change, you can call onUserTokenChange.

    aa('onUserTokenChange', (userToken) => {
      console.log("userToken has changed: ", userToken);
    });

    onUserTokenChange accepts callback(required) and options(optional).

    aa('onUserTokenChange', callback, options);
    Option Type Description
    immediate boolean Fire the callback as soon as it's attached
    aa('init', { ... });  // ← This sets an anonymous user token if cookie is available.
    
    aa('onUserTokenChange', (userToken) => {
      console.log(userToken);  // prints out the anonymous user token
    }, { immediate: true });
    aa('init', { ... });
    aa('setUserToken', 'my-user-id-1');
    
    aa('onUserTokenChange', (userToken) => {
      console.log(userToken); // prints out 'my-user-id-1'
    }, { immediate: true })

    With immediate: true, onUserTokenChange will be immediately fired with the token which is set beforehand.

    Report a click event

    aa('clickedObjectIDs', {
      index: 'INDEX_NAME',
      eventName: 'Add to basket',
      objectIDs: ['object1'],
    });
    Option Type Description
    index string The name of the index related to the event
    eventName string The name of the event
    objectIDs string[] The list of IDs of the result that was clicked
    aa('clickedFilters', {
      index: 'INDEX_NAME',
      eventName: 'Filter on facet',
      filters: ['brand:Apple'],
    });
    Option Type Description
    index string The name of the index related to the event
    eventName string The name of the event
    filters string[] The list of filters that was clicked as '${attr}${op}${value}'

    Report a conversion event

    aa('convertedObjectIDs', {
      index: 'INDEX_NAME',
      eventName: 'Add to basket',
      objectIDs: ['object1'],
    });
    Option Type Description
    index string The name of the index related to the event
    eventName string The name of the event
    objectIDs string[] The list of IDs of the result that was clicked
    aa('convertedFilters', {
      index: 'INDEX_NAME',
      eventName: 'Filter on facet',
      filters: ['brand:Apple'],
    });
    Option Type Description
    index string The name of the index related to the event
    eventName string The name of the event
    filters string[] The list of filters that was clicked as '${attr}${op}${value}'

    Report a view event

    aa('viewedObjectIDs', {
      index: 'INDEX_NAME',
      eventName: 'Add to basket',
      objectIDs: ['object1'],
    });
    Option Type Description
    index string The name of the index related to the event
    eventName string The name of the event
    objectIDs string[] The list of IDs of the result that was clicked
    aa('viewedFilters', {
      index: 'INDEX_NAME',
      eventName: 'Filter on facet',
      filters: ['brand:Apple'],
    });
    Option Type Description
    index string The name of the index related to the event
    eventName string The name of the event
    filters string[] The list of filters that was clicked as '${attr}${op}${value}'

    Examples

    The following examples assume that the Search Insights library is loaded.

    Contributing

    To run the examples and the code, you need to run two separate commands:

    • yarn dev runs webpack and the Node.js server
    • yarn build:dev runs Rollup in watch mode

    To release, go on master (git checkout master) and use:

    yarn run release

    It will create a pull request for the next release. When it's reviewed, approved and merged, then CircleCI will automatically publish it to npm.

    License

    Search Insights is MIT licensed.

    Keywords

    none

    Install

    npm i search-insights

    DownloadsWeekly Downloads

    19,696

    Version

    1.8.0

    License

    MIT

    Unpacked Size

    112 kB

    Total Files

    64

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar