Add search analytics for Matomo

[ngulden]

Describe the problem

I use typesense-docsearch.js as search interface to a product documentation site at https://docs.software-univention.de.

I like the interface and how quickly I could get it productive.

I use Matomo for website analytics. To further improve our documentation, I'd also like to use search analytics together with Matomo.

Describe the solution

I need a way to capture the search term in the UI and send it for search analytics to Matomo. For using website tracking with Matomo, see https://developer.matomo.org/guides/tracking-javascript-guide#internal-search-tracking

I just want to configure it as parameter for docsearch in JavaScript.

Alternatives you've considered

One alternative would be building my own search UI with InstantSearch.js. To me this looks like an overkill, because I would need to duplicate the logic and the design within typesense-docsearch.js.

Which solutions do you have in mind?

[jasonbosco]

I found this comment that talks about an approach to hook into autocomplete.js with a plugin. It talks about sending the events to Algolia, but may be you could build a custom plugin to send the data to Matamo.

[ngulden]

Thanks for the hint @jasonbosco .

I spent some time today to build the typesense-docsearch.js artifact locally on my own. The build seemed to work, but I couldn't find the file. I also couldn't get along yet diving into the code and adding some stuff.

Can you point to a resource that helps me with onboarding to build locally, where to find the built artifacts and where to start hacking? Thanks.

[jasonbosco]

The build should be just running:

yarn install
yarn build

The build artifacts will then be inside packages/<package_name>/dist

[ngulden]

Thanks. For packages/docsearch-js, I have the following structure after the build:

.
├── esm
│   ├── docsearch.d.ts
│   ├── index.d.ts
│   ├── index.js
│   └── index.js.map
└── umd
    ├── index.js
    └── index.js.map

Which file best fits to <script src="https://cdn.jsdelivr.net/npm/[email protected]"></script> as outlined at https://typesense.org/docs/guide/docsearch.html#option-c-custom-docs-framework-with-docsearch-js-v3-modal-layout?

[jasonbosco]

You'd want to use the umd version in script tags.

[ngulden]

@jasonbosco

Thanks for your tips. I hacked around a bit these days and came up with #17. In my local setup it works so far and I receive the site search keywords in Matomo.

I'm not very familiar with React and TypeScript. Can you please have a look at the lines and give feedback? That would be great, thanks.

[jasonbosco]

@ngulden Your approach seems reasonable and minimally invasive IMO, so looks good to me!

Although, I'd prefer to not merge the code into this repo because it's very Matamo specific. But I think your PR can still be a great reference point for others to implement their own FE-based analytics tracking, so thank you for documenting your approach in the PR.

[ngulden]

The PR is a prototype as starting point. I'd like to have it more configurable. I envision to activate it through a parameter to the docsearch() function that I or other users just add when integrating typesense-docsearch.js to their <script> section in their HTML file.

Do you have a hint how I could accomplish it?

[ngulden]

I added a parameter to configure the Matomo plugin. Per default, it's deactivated. Maybe, this implementation fits better.

[jasonbosco]

Since this hooks into autocomplete-js, I think it might be better to publish the matamo specific pieces as a separate autocomplete-js plugin, and then in DocSearch, only add the ability to use any autocomplete-js plugin.

[ngulden]

I'm not familiar with the ecosystem and publishing my contribution as separate piece of work. Furthermore, I don't have the capacity for maintenance. Thanks for your assistance @jasonbosco .

To me, the piece of code works and I use it productively for some days now. It's available as a pull request for others interested in the same topic.