Yext Analytics
A Typescript library for sending Yext Analytics events.
Full Documentation
Features
- Works in both the browser and Node.js
- 100% TypeScript, with detailed analytics event models
- Compatible with both CommonJS and ES6 imports
Getting Started
First, install the library via npm:
npm install @yext/analytics
Next, import and initialize the library in your application. Yext currently has different analytics reporting features between Search and Pages and so they have slightly different interfaces for working with them. There is also a combined interface that you can use when you are building a Search experience entirely on Pages (e.g. a Locator or a Help Site).
Search Analytics
import { provideSearchAnalytics } from '@yext/analytics';
const searchAnalytics = provideSearchAnalytics({
experienceKey: '<your experience key>',
experienceVersion: 'PRODUCTION',
businessId: 123456,
});
To use the library with Node, use the following import instead:
const { provideSearchAnalytics } = require('@yext/analytics');
Now that the search analytics reporter is initialized, let's fire off an event:
searchAnalytics.report({
type: 'CTA_CLICK',
entityId: '1',
verticalKey: 'people',
searcher: 'VERTICAL',
queryId: '12345678-1234-1234-1234-123456789012'
});
Search Analytics Event Types
When specifying the analytics type, either the SearchAnalyticsEventType enum or its corresponding string can be specified. For example, you can specify the 'CTA_CLICK' event with either 'CTA_CLICK' or
with AnalyticsEventType.CtaClick
. Once the event type is specified, TypeScript is able to enforce the required and
optional properties for that event type.
Pages Analytics
import { providePagesAnalytics } from '@yext/analytics';
const pagesAnalytics = providePagesAnalytics({
debug: false,
pageType: {
pageSetId: 'My Page Set',
id: 90210,
name: 'static',
},
pagesReferrer: 'https://www.google.com',
path: '/foo/bar',
businessId: 12345,
production: false,
siteId: 654321,
});
Now that the pages analytics reporter is initialized, we can fire a pageview:
pagesAnalytics.pageView();
If a user clicks on a CTA, we can track a CTA Click Event
import { CtaClick } from '@yext/analytics';
pagesAnalytics.track(CtaClick);
We can also fire an event on any other type of user interaction and give it a custom name:
pagesAnalytics.track({eventType: 'C_MY_CUSTOM_EVENT'});
Chat Analytics
Chat Analytics work somewhat differently. For Chat Analytics, you only need to provide an API Key, and other attributes such as your business ID will be automatically inferred. You can acquire this API key in the developer console of the Yext Platform.
When sessionTrackingEnabled
is set to true, Chat Analytics will automatically generate a ULID for sessionId
and append to events from the same browser session. User may also provide their own sessionId
, which takes precedence over the auto-generated id by Chat Analytics.
import { provideChatAnalytics } from '@yext/analytics';
const chatAnalytics = provideChatAnalytics({
apiKey: '<your api key>',
});
analytics.report({
action: 'CHAT_IMPRESSION',
sessionId: 'e790f75d-4f1e-4a1b-b57b-9a456019b176',
sessionTrackingEnabled: true,
chat: {
botId: 'my-chat-bot',
}
})
Conversion Tracking
Yext offers conversion tracking that can attribute values to conversion events that are driven by user interaction
with Yext's products. Once you have setup conversion tracking
you can create a conversionTracking provider like so:
import { provideConversionTrackingAnalytics } from '@yext/analytics';
const conversionTracker = provideConversionTrackingAnalytics();
In order to track conversions, you will need to set a Cookie on your users and pass the id of that cookie to the
conversion tracker when a conversion event occurs. Which can be done like so:
conversionTracker.trackConversion({
cookieId: '12466678',
cid: '12345-abcde-67890-fghij',
cv: 10,
})
Additionally, if you are implementing Conversion tracking on a pages site, once you have setup the pages analytics tracker, you should turn on conversion tracking so that interactions on your pages site can be properly credited with conversions. That can be done like so:
pagesAnalytics.setConversionTrackingEnabled(true, 'cookie id of the user goes here');
Then, when you track a page view it will automatically be credited for conversion tracking purposes. Additionally, if an event on your pages should be treated as a conversion, you would track it like so:
pagesAnalytics.track('event_to_track', {
cid: '12345-abcde-67890-fghij',
cv: 10,
});
And that's it! See our documentation for a full list of analytics events.
Module support
- The ESM (ES6) build will be used automatically by module bundlers that support it (e.g. Webpack). It can be specified directly by importing
@yext/analytics/lib/esm
- The CommonJS build will be used automatically by Node, but it can be specified directly by importing
@yext/analytics/lib/commonjs
License
Yext Analytics is an open-sourced library licensed under the BSD-3 License.
Third Party Licenses
The licenses of our 3rd party dependencies are collected here: THIRD-PARTY-NOTICES.