AI Search Analytics Integration

This article will guide you through integrating client-side analytics into the AI Search feature.

The Help Center theme provides events and URL tracking to easily integrate into your existing analytics software, such as Google Analytics and Matomo.

You can also bring your own advanced logging solution and hook into AI search events.

Please note, we do not log any user queries or AI Search responses on our end, ensuring full user privacy.

Quick Integration Guides

Use the following guides to quick start integrating the AI Search data into your existing analytics system using Scroll Viewport’s custom JavaScript editor.

The analytics integration described here will report user queries but not give you the corresponding AI responses. To review AI responses, enter the user query into the AI search or use our advanced integration.

Integrate with Google Analytics

1. Activate Google Analytics under Edit theme → Integrations → Analytics. Read more on Analytics integrations.

2. Open the JavaScript editor under Edit theme → Templates → JavaScript

3. In the editor, insert the following custom code:

   JS

   /* Custom JavaScript */
   
   addEventListener('ai_search_response', (event) => {
     gtag('event', event.type, {
       'id': event.detail.id,
       'query': event.detail.query
     }); 
   });
   
   addEventListener('ai_search_user_feedback', (event) => {
     gtag('event', event.type, {
       'id': event.detail.id,
       'query': event.detail.query,
       'rating': String(event.detail.rating)
     });
   });

4. Click ‘Save' and close the theme editor.

5. Click ‘Update site’ and ‘Go live’

References:

• [GA4] Custom events - Analytics Help

• [GA4] About custom dimensions and metrics - Analytics Help

Integrate with Matomo

1. Open the JavaScript editor under Edit theme → Templates → JavaScript

2. If you haven’t done yet: In the editor, first insert your Matomo tracking code to enable Matomo tracking.
   See how to find the tracking code in Matomo or copy-paste the below example and replace YOUR_MATOMO_URL with your URL and YOUR_SITE_ID with your site ID:

   JS

   /* Custom JavaScript */
   
   var _paq = window._paq = window._paq || [];
   _paq.push(["setExcludedQueryParams", ["\/^vgo_ee.*\/","\/^cql.*\/"]]);
   _paq.push(['trackPageView']);
   _paq.push(['enableLinkTracking']);
   (function() {
     var u=YOUR_MATOMO_URL;
     _paq.push(['setTrackerUrl', u+'matomo.php']);
     _paq.push(['setSiteId', YOUR_SITE_ID]);
     var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
     g.async=true; g.src='https://cdn.matomo.cloud/k15t.matomo.cloud/matomo.js'; s.parentNode.insertBefore(g,s);
   })();

3. In the same JavaScript editor, add the event handler code for the AI Search:

   JS

   /* Custom JavaScript */
   
   addEventListener('ai_search_response', (event) => {
     _paq.push(['trackEvent', 'ai_search', event.type, event.detail.query]);  
   });
   
   addEventListener('ai_search_user_feedback', (event) => {
     _paq.push(['trackEvent', 'ai_search', event.type, event.detail.query, event.detail.rating]);
   });

4. Click ‘Save' and close the theme editor.

5. Click ‘Update site’ and ‘Go live’

The AI Search events (ai_search) will now be collected in your Matomo Dashboard under Matomo Dashboard → Behavior → Events.

Generally it takes up to a day for Matomo to show any information in the dashboard.

References:

• JavaScript Tracking Client - Matomo Analytics (formerly Piwik Analytics) - Developer Docs - v5

• JavaScript Tracking Client - Integrate - Matomo Analytics (formerly Piwik Analytics) - Developer Docs - v5

• JavaScript Tracking Client - API Reference - Matomo Analytics (formerly Piwik Analytics) - Developer Docs - v5

Advanced Integration

URL Tracking Parameter

The AI Search appends the tracking parameter ?utm_source=ai_search to each generated link, allowing you to track user flows coming from an AI Search result.

Theme Events

The theme emits event objects when interacting with Search AI. These contain additional data about the search.

By listening for these events, custom logging services can be integrated to store and analyze user interactions later on.

Available events:

• ai_search_response

• ai_search_user_feedback

Access event data

By leveraging Scroll Viewport’s custom JavaScript editor, the integration is straightforward.

1. Listen for one or more of the supported events.

2. Access the event data through the event’s detail property.

3. Forward the data to your service provider.

/* Custom JavaScript */

addEventListener('ai_search_response', (event) => {
  console.log('>> [ai search]', event.detail);
});

addEventListener('ai_search_user_feedback', (event) => {
  console.log('>> [ai search]', event.detail);
});

When sending the data to a analytics service provider or to your own solution consider using the window.scrollHelpCenter.areCookiesEnabled flag to first check if the user has confirmed the cookie notice and has accepted the use of analytics software.

AI Search response event: ai_search_response

AI Search user feedback event: ai_search_user_feedback

Related Articles