feat(insights): POC click analytics integration #3547

tkrugg · 2019-02-20T17:01:25Z

This POC demonstrating a possible integration between our clickAnalytics and InstantSearchJS.

How we currently do it: https://www.algolia.com/doc/guides/building-search-ui/going-further/plug-analytics/js/?language=js#using-algolia-insights-with-instantsearchjs

Test this out

Go on https://deploy-preview-3547--instantsearchjs.netlify.com/stories/?selectedKind=ClickAnalytics&selectedStory=with%20function%20template&full=0&addons=1&stories=1&panelRight=0&addonPanel=storybook%2Factions%2Factions-panel
open your browser console
click on add to cart

How it is used

For instant search user, sending click events (or other events types) can be done with the following way

import * as analytics from "../src/helpers/analytics";

// initialize the search-insights clients
aa("init", {
  appId: "APPLICATION_ID",
  apiKey: "SEARCH_API_KEY",
  userHasOptedOut: false
});
aa("setUserToken", "xxx");

const search = instantsearch({
  indexName: "instant_search",
  /* ... */
  insightsClient: aa
});

// add the hits widget
search.addWidgets([
  instantsearch.widgets.configure({
    clickAnalytics: true
  }),
  instantsearch.widgets.hits({
    container,
    templates: {
      item: item => `
        <h3> ${item.name} </h3>
        <button ${analytics.clickedObjectIDsAfterSearch(item.objectID, {
          eventName: "Add to basket"
        })}>
           Add to basket
        </button>
      `
    }
  })
]);

This is going to call the clickedObjectIDsAfterSearch in the following way:

aa("clickedObjectIDsAfterSearch", {
  eventName: "Add to basket", // user provided
  index: "instant_search", // infered from `results`,
  queryID: "***", // infered from `results`,
  objectIDs: ["1"], // infered from `hit`,
  positions: [1] // computed and infered from `hit` and `results`,
});

With Hogan

<button
  {{#helpers.clickedObjectIDsAfterSearch}}{
    eventName: 'Add to cart'
  }{{/helpers.clickedObjectIDsAfterSearch}}>
  Add to basket
</button>

How it works

There are three parts:

connectHits is using createAnalyticsHelpers():
- exposes analytics object with methods that call the insights client directly (useful for other flavours)
- inject in every hit hit.__analytics = { index: "instant_search", queryID: "xxx", objectIDs: ["1"], positions: [10] }
helpers analytics.clickedObjectIDsAfterSearch are helpers generates data attributes
the WithClickAnalyticsWrapper wraps the Hits component and sets a click listener that reads data attribute and calls connector analytics methods

Possible improvements and unresolved questions

Conversion events are often sent outside the contexte of instantsearch. Can we help in that situation?
We expose the queryID so the user can extract the queryID in the following way:

  <a href="https://mywebsite.com/?queryID=${item.__analytics.queryID}"> Add to basket </a>

  <a href="https://mywebsite.com/?queryID={{__analytics.queryID}}"> Add to basket </a>

This POC is intended to work on InfiniteHits as well.

algobot · 2019-02-20T17:10:33Z

Deploy preview for instantsearchjs ready!

Built with commit 0094cce

https://deploy-preview-3547--instantsearchjs.netlify.com

stories/clickAnalytics.stories.js

samouss · 2019-02-21T15:18:36Z

src/components/Hits/withClickAnalytics.js

+            };
+            return `
+              data-analytics-event="clickedObjectIDsAfterSearch"
+              data-analytics-payload='${JSON.stringify(payload)}'


To avoid issue with quotes or whatever we can encode/decode the value in base64.

samouss · 2019-02-21T15:23:53Z

src/components/Hits/withClickAnalytics.js

+        __index: index,
+        __queryID: queryID,
+        analytics: {
+          clickedObjectIDsAfterSearch: eventName => {


We expose the analytics attribute on the hit why not follow the same convention than we have with the highlight helper? It's an external function that takes the required parameters as input. We could use an external function that takes eventName, results, hits to create the payload and/or another function to create the attributes. Which means that we can re-use it to expose the Hogan version.

If I understand your point well, this would require to pass results to the Template component inside data so that we can use it in the helpers, which also means exposing the results in every hit. Is this what you had in mind?

src/components/Hits/withClickAnalytics.js

francoischalifour

There's a lot of assumptions in the code because we want to support multiple data types (string and objects). I think this should be stricter. It makes it confusing for the users and it makes the code hard to follow.

I don't find the way the higher-order component is made intuitive in the widget. We could abstract this logic by creating a proxy hit component that uses HitsWithAnalytics if the analytics prop is passed, the basic Hits component otherwise.

There's more things I've noticed but I'll keep it short in the first place :)

Do you plan on adding tests?

src/helpers/analytics.js

francoischalifour · 2019-02-27T14:34:06Z

src/connectors/hits/connectHits.js

@@ -76,6 +78,16 @@ export default function connectHits(renderFn, unmountFn) {
          results.hits = escapeHits(results.hits);
        }

+        // should we expose this only if instantSearchInstance contains clickAnalytics: true?


Yes, I would say so.

francoischalifour · 2019-02-27T14:37:51Z

src/helpers/analytics.js

+// we could decide to have more specific helpers to make the code lighter for func templates
+// clickedObjectIDsAfterSearch(payload)
+// etc
+export function clickedObjectIDsAfterSearch(objectID, payload) {


Shouldn't objectID be part of the payload?

This is the helper layer, we only pass the data we want to override.
the exact payload is build by the connector layer so that it can benefit all the flavours.

francoischalifour · 2019-02-27T14:39:04Z

src/helpers/analytics.js

+      serializedPayload = JSON.stringify(payload);
+    } catch (e) {
+      throw new Error(
+        `The analytics helper expects payload to be either a string or a JSON object`


Shouldn't we accept a single type? (I'd go for string)

Answered in your next comment 😄 #3547 (comment)

francoischalifour · 2019-02-27T14:40:37Z

src/helpers/analytics.js

+    payload = JSON.parse(serializedPayload);
+  } catch (e) {
+    // assume it's the eventName
+    payload = { eventName: serializedPayload };


Why this assumption?

I want to allow the shorthand

<button ${analytics.clickedObjectIDsAfterSearch(item.objectID, 'Add to basket')}> Add to basket </button>  <button ${analytics.clickedObjectIDsAfterSearch(item.objectID, {eventName: 'Add to basket'})}> Add to basket </button>

but it's debatable and I'm not holding on it

francoischalifour · 2019-02-27T14:43:59Z

src/lib/utils.js

@@ -1,13 +1,15 @@
 import reduce from 'lodash/reduce';
 import forEach from 'lodash/forEach';
 import find from 'lodash/find';
+import findIndex from 'lodash/findIndex';


That's a new dependency – I think we can avoid it.

you're right but I think it has no extra cost here because we are already using find it depends on findIndex https://github.com/lodash/lodash/blob/4.17.11-npm/find.js#L2

francoischalifour · 2019-02-27T14:48:51Z

src/lib/utils.js

@@ -496,6 +498,58 @@ function createDocumentationMessageGenerator(...widgets) {
  };
 }

+function createAnalyticsHelpers(instantSearchInstance, results) {


This can be moved to its own file.

francoischalifour · 2019-02-27T14:52:52Z

src/widgets/hits/hits.js

+  };
+
+  const hasClickAnalytics =
+    instantSearchInstance.searchParameters.clickAnalytics;


We could either go explicit with:

const hasClickAnalytics = Boolean(instantSearchInstance.searchParameters.clickAnalytics);

Or more strict (needs to be aligned in the codebase):

const hasClickAnalytics = instantSearchInstance.searchParameters.clickAnalytics === true;

francoischalifour · 2019-02-27T15:00:30Z

stories/clickAnalytics.stories.js

+import { withHits } from '../.storybook/decorators';
+import * as analyticsHelpers from '../src/helpers/analytics';
+
+const insightsClientMock = (eventName, payload) => {


You can use the action from Storybook (see Analytics story).

Co-Authored-By: tkrugg <tkrugg@users.noreply.github.com>

tkrugg · 2019-02-27T15:48:12Z

@francoischalifour

There's a lot of assumptions in the code because we want to support multiple data types (string and objects). I think this should be stricter. It makes it confusing for the users and it makes the code hard to follow.

As I answered to your comment:
I want to allow the shorthand

<button ${analytics.clickedObjectIDsAfterSearch(item.objectID, 'Add to basket')}>
    Add to basket
</button>
<!-- vs -->
<button ${analytics.clickedObjectIDsAfterSearch(item.objectID, {eventName: 'Add to basket'})}>
    Add to basket
</button>

but it's debatable and I'm not holding on it

I don't find the way the higher-order component is made intuitive in the widget. We could abstract this logic by creating a proxy hit component that uses HitsWithAnalytics if the analytics prop is passed, the basic Hits component otherwise.

The HOC component here acts like the "proxy", do I'm not sure what you mean.
I wanted to keep this PR short but this same HOC will be used to add analytics on infinite-hits

const HitsWithAnalytics = withClickAnalytics(Hits)
const InfiniteHitsWithAnalytics = withClickAnalytics(InfiniteHits)

Do you plan on adding tests

Of course! also rewriting the new code in TS as much as possible.

tkrugg · 2019-03-11T17:48:08Z

closing this. Replaced by #3598

feat(insights): click analytics integration

3de262f

tkrugg requested a review from a team February 20, 2019 17:02

Haroenv reviewed Feb 21, 2019

View reviewed changes

stories/clickAnalytics.stories.js Outdated Show resolved Hide resolved

samouss reviewed Feb 21, 2019

View reviewed changes

francoischalifour reviewed Feb 22, 2019

View reviewed changes

src/components/Hits/withClickAnalytics.js Outdated Show resolved Hide resolved

feat(insights): click analytics integration -- reloaded

d33efe6

francoischalifour reviewed Feb 27, 2019

View reviewed changes

tkrugg and others added 2 commits February 27, 2019 16:21

removed unused isEqual

f3f7245

Update src/helpers/analytics.js

0094cce

Co-Authored-By: tkrugg <tkrugg@users.noreply.github.com>

tkrugg requested review from Haroenv and samouss February 27, 2019 15:49

tkrugg mentioned this pull request Mar 11, 2019

feat(Insights): Insights inside Instantsearch #3598

Merged

tkrugg closed this Mar 11, 2019

Haroenv deleted the clickAnalytics branch October 26, 2021 07:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(insights): POC click analytics integration #3547

feat(insights): POC click analytics integration #3547

tkrugg commented Feb 20, 2019 •

edited

Loading

algobot commented Feb 20, 2019 •

edited

Loading

samouss Feb 21, 2019

samouss Feb 21, 2019

tkrugg Feb 25, 2019 •

edited

Loading

francoischalifour left a comment

francoischalifour Feb 27, 2019

francoischalifour Feb 27, 2019

tkrugg Feb 27, 2019

francoischalifour Feb 27, 2019

tkrugg Feb 27, 2019

francoischalifour Feb 27, 2019

tkrugg Feb 27, 2019

francoischalifour Feb 27, 2019

tkrugg Feb 27, 2019 •

edited

Loading

francoischalifour Feb 27, 2019

francoischalifour Feb 27, 2019

francoischalifour Feb 27, 2019

tkrugg commented Feb 27, 2019

tkrugg commented Mar 11, 2019

feat(insights): POC click analytics integration #3547

feat(insights): POC click analytics integration #3547

Conversation

tkrugg commented Feb 20, 2019 • edited Loading

Test this out

How it is used

With Hogan

How it works

Possible improvements and unresolved questions

algobot commented Feb 20, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tkrugg Feb 25, 2019 • edited Loading

Choose a reason for hiding this comment

francoischalifour left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tkrugg Feb 27, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tkrugg commented Feb 27, 2019

tkrugg commented Mar 11, 2019

tkrugg commented Feb 20, 2019 •

edited

Loading

algobot commented Feb 20, 2019 •

edited

Loading

tkrugg Feb 25, 2019 •

edited

Loading

tkrugg Feb 27, 2019 •

edited

Loading