docs: Update search.mdx - Algolia insights:true #11012
Conversation
We (Algolia) recommend that DocSearch users utilize insights by default now. This will give DocSearch customers better insights out of the box into what users are doing with their searches, without having to turn it on later and then wait some period of time to get good data. It's OK if the default is still false, if you prefer, we recommend it to be true. If desired, you could change the code to have it true by default and then mention here it can be turned off.
✅ [V2]Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
⚡️ Lighthouse report for the deploy preview of this PR
|
|
Thanks I'm ok to merge this docs PR About an insight default change, I'm open to it but please explain to me exactly what this means to turn it on by default for our users. Is it fine if Docusaurus users get this enabled automatically by upgrading their site? Can it be a cause of trouble? Should it be considered a breaking change? Honestly I have no idea what this flag does, and did a quick search, it doesn't seem easy to find documentation about it, apart API ref. What I'd like to know is what's the impact, and it doesn't seem to be explained anywhere super clearly what this means for a Docusaurus docs site. |
Great!
Here is the main overview page on the insights paramter for Autocomplete (which DocSearch is built on top of): https://www.algolia.com/doc/ui-libraries/autocomplete/guides/sending-algolia-insights-events/. It is just a way to turn on sending click and conversion events (https://www.algolia.com/doc/guides/sending-events/getting-started/). Since DocSearch is fairly bare bones in terms of Algolia features, the main benefit to DocSearch users is better analytics about what users are searching for (https://www.algolia.com/doc/guides/search-analytics/overview/) with tracking of view and click events (https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/).
The implications of having it on by default just means that if they ever want to go look at their Algolia analytics, view and click information will already exist for them to look at. Otherwise, they'd need to turn it on, and then depending on traffic wait a period of time to get metrics to analyze.
I do not see a problem with this. Their site will just start getting view and click events in their analytics data.
Events are a cornerstone feature of Algolia which unlocks basically all other advanced features of Algolia to paid customers. With respect to DocSearch and Docusaurus users, the only benefit is better analytics from the start.
Site implementors and users will feel no impact whether this is on or off. The benefit is to site implementors, when or if they want to view the search analytics, they will be there and ready to be viewed and acted upon.
Searching docs.algolia.com for "insights" yields a lot of results, the top two are references to the API, the third page is the overview of the feature.
The overview page here https://www.algolia.com/doc/ui-libraries/autocomplete/guides/sending-algolia-insights-events/ talks about Autocomplete, which DocSearch is built on, and Docusaurus leverages. The impact to autocomplete users is that view and click events are captured from the start, enabling better analytics if/when you want to see them about your site. Events are a typical feature that Algolia paid users will turn on to start with in order to leverage other features, one of which is better analytics. To be super conservative on this matter, one idea is to make only the doc change for now. If neither of us hear of any issues after some period of time, say three months, I can ping you on this and we can revisit turning it on by default in the code. |
We (Algolia) recommend that DocSearch users utilize insights by default now. This will give DocSearch customers better insights out of the box into what users are doing with their searches, without having to turn it on later and then wait some period of time to get good data.
It's OK if the default is still false, if you prefer, we recommend it to be true. If desired, you could change the code to have it true by default and then mention here it can be turned off.
I took this approach assuming you'd prefer to keep it as-is for your users (false by default) unless they specifically turn it on as indicated by the docs here.
Pre-flight checklist
Motivation
The Algolia recommendation is to have insights:true by default now.
Test Plan
None
Test links
None
Related issues/PRs
None