Yext Analytics

A Typescript library for sending Yext Analytics events.

Full Documentation

Yext Analytics

Yext Analytics is a Typescript library for sending analytics events that occur on your digital experiences to the Yext Analytics platform. You can record user actions that we offer out-of-the-box, such as page views and clicks, or custom actions that are unique to your business! Yext uses the same analytics reporting features across Search, Pages, and Chat so these products all use one interface.

• Works in the browser only.
• 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

Initialize Analytics Reporter

Next, import and initialize the library in your application. When initializing your analytics reporter, you only need to provide an API Key that has access to the Events API. 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.

import { analytics } from '@yext/analytics';

// Root analytics service with no defaults.
const rootAnalytics = analytics({
  authorizationType: 'apiKey',
  authorization: 'MY_API_KEY'
});

In many cases, you might need to repeatedly specify the same properties, such as a Pages site ID or Chat bot ID. Yext Analytics allows you to avoid having to repeatedly specify the same code by allowing you to set default values.

You can add a .with() method to the root analytics service you initialized, which returns a new analytics object with the specified JSON merged on top of the existing defaults.

import { analytics } from '@yext/analytics';

// Root analytics service with no defaults.
const rootAnalytics = analytics({
  authorizationType: 'apiKey',
  authorization: 'MY_API_KEY'
});

// Pages analytics service with Pages defaults.
const pageAnalytics = rootAnalytics.with({ pages: { siteId: 123 } });

// Chat analytics service with both Chat **and** Pages defaults.
const chatAnalytics = pageAnalytics.with({ chat: { botId: 'my-bot' } });

Calling pageAnalytics.report() sends an event with the pages object, plus anything passed to report. Calling chatAnalytics.report() sends an event with both the pages and chat objects, plus anything passed to report. You can override the default values defined in the .with() method by sending them along with the event.

For other configuration features, see AnalyticsConfig.ts

Fire an Event

Now that we’ve initialized our analytics reporter, we can fire an event! This sends a CHAT_IMPRESSION event type, along with a sessionId, a pages.siteId, and a chat.botId.

chatAnalytics.report({
  action: 'CHAT_IMPRESSION'
});

Additional Configuration

Session Tracking

Session tracking is now available for Chat, Pages, and Search. Yext uses a browser-based method (sessionStorage) to track this. By default, session tracking is enabled in both the US and EU environments. This can be disabled by setting sessionTrackingEnabled to false.

When sessionTrackingEnabled is set to true, Analytics will automatically generate a ULID for sessionId and bind that ULID to events from the same browser session. Users may also provide their own sessionId, which takes precedence over the auto-generated ID by Analytics. To read more about how we generate ULIDs, check out ulidx.

Custom Events

You can also send custom analytics events.

pagesAnalytics.report({
  action: 'C_MY_CUSTOM_EVENT'
});

Additionally, you can send arbitrary conversion events by specifying a value JSON object with a dollar amount and a currency in ISO format.

chatAnalytics.report({
  action: 'C_CONVERSION_EVENT',
  value: {
    amount: 10,
    currency: 'USD'
  }
});

To learn more about sending conversion events, see our API documentation.

Custom Properties

You can attach custom properties to your analytics events by specifying either customTags or customValues with your request. customTags represent up to ten string key-value pairs and customValues represent up to ten numeric key-value pairs.

For example, if I set up an ORDER event for my restaurant and wanted to track whether a promotional code was used on the order, I could add an promoCode custom tag to the event.

pagesAnalytics.report({
  action: 'C_CONVERSION_EVENT',
  sessionId: 'e790f75d-4f1e-4a1b-b57b-9a456019b176',
  value: {
    amount: 35.5,
    currency: 'USD'
  },
  customTags: {
    promoCode: 'SPRING15OFF'
  }
});

Additionally, if I wanted to record the discount amount of the promotion, I could add a promoDiscount custom value to the ORDER event.

pagesAnalytics.report({
  action: 'C_CONVERSION_EVENT',
  sessionId: 'e790f75d-4f1e-4a1b-b57b-9a456019b176',
  value: {
    amount: 35.5,
    currency: 'USD'
  },
  customTags: {
    promoCode: 'SPRING15OFF'
  },
  customValues: {
    promoDiscount: 41.76
  }
});

Debugging

Debug Mode

The SDK has a debug mode which can be activated by setting the debug property in your AnalyticsConfig to true. This will prevent report() from sending a real request to the Yext Events API. Instead it will print the EventPayload and AnalyticsConfig to console.

fetch + keepalive

We use fetch() + keepalive by default in supported browsers to make debugging easier. For browsers like Firefox that do not support keepalive, we use the Beacon API. Users can set forceFetch: true in their config, which will make these browsers use fetch() instead of the Beacon API. Be warned, since forceFetch uses fetch() without keepalive, requests in progress for browsers like FireFox will be canceled if the page is unloaded.

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.