With visitor analytics, you can better understand how your individual customers are interacting with search on your site so that you can better optimize their experience.

Note: Depending on your local regulations, e.g. GDPR, you may be required to request consent from your users before performing any visitor level tracking.

Once you set this up, you will be able to build relevant analytics dashboards to view user engagement, such as the example below that showcases a single user's interaction with search result content.

Step 1: Identifying Your Visitors

In order to track what individual visitors are searching for and engaging with on your search experience, you first need to be able to uniquely identify them.

There are a few common ways to identify who is visiting your search experience:

1. With a Yext cookie
2. With your own visitor ID

With Yext Cookie

When using Yext's tag-based conversion tracking, a first party cookie called _yfpc is automatically generated for you and used to link clicks with any conversions which may have occurred.

You can use this same cookie for identifying visitors outside of conversion tracking if you don't already have your own method for doing so.

With Your Own ID

Oftentimes you will already have your own way of identifying a visitor whether that's based on a cookie, user email address, or some other unique identifier you may have.

If this is the case, you can use this ID as your visitor ID assuming it's available to your search experience at runtime e.g., when a search or click is being made.

See the reference sections at the end of this document for details on retrieving IDs from cookies or local storage.

Step 2: Attributing Analytics to Your Visitors

Overview

Once you've identified your visitor, you'll need to pass this information to your search experience so that they are attributed to searches and clicks.

Depending on how your search experience is integrated - either via iFrame, subdomain, or API - attributing analytics to a visitor can vary.

iFrame

1. Set your Search Experience to Initialize Manually

To ensure that your visitor ID is correctly passed with any searches or clicks, you need to make sure that your visitor ID is being set BEFORE your experience is initialized.

Set the initializeManually property in your config/global_config.json file to true:

{
  "sdkVersion": "{YOUR_SDK_VERSION}",
  "sessionTrackingEnabled": {TRUE_OR_FALSE},
  "analyticsEventsEnabled": {TRUE_OR_FALSE},
  "logo": "{YOUR_LOGO_URL}",
  "favicon": "{YOUR_FAVICON_URL}",
  "googleTagManagerName": "{YOUR_GOOGLE_TAG_MANAGER_NAME}",
  "googleTagManagerId": "{YOUR_GOOGLE_TAG_MANAGER_ID}",
  "googleAnalyticsId": "{YOUR_GOOGLE_ANALYTICS_ID}",
  "conversionTrackingEnabled": {TRUE_OR_FALSE},
  "initializeManually": true
}

2. Create a Visitor Object

Once you've set initializeManually: true, create a JSON object wherever your iFramed search experience lives.

This object consists of two properties:

var my_visitor_object = {
    id: "1404629222047",
    idMethod: "YEXT_CONVERSION_TRACKING_COOKIE"
}

3. Set Visitor Property in Runtime Config to Visitor Object

AnswersExperienceFrame.runtimeConfig.set("visitor", my_visitor_object);

Only set the visitor property when you have a visitor ID to associate with searches and clicks. If no visitor ID is available, this property should not be set.

4. Initialize your Search Experience

AnswersExperienceFrame.init({});

If you do not initialize your experience, searches will return no results and no visitor will be logged.

Putting it All Together

<div id="answers-container"></div>

/* insert code to retrieve and generate cookie */

<script src="REPLACE_ME_PRODUCTION_URL/iframe.js"></script>
<script>
   window.addEventListener("DOMContentLoaded", (event) => {
     AnswersExperienceFrame.runtimeConfig.set("querySource", "HELP_SITE");
  
     /* Set Visitor Object from Yext.com Cookie */
     if (getCookie("_yfpc") != null) {
       var visitor = {
         id: getCookie("_yfpc"),
         idMethod: "YEXT_CONVERSION_TRACKING_COOKIE"
       };
       AnswersExperienceFrame.runtimeConfig.set("visitor", visitor);
     }
     AnswersExperienceFrame.init({});
   });
</script>

Subdomain

1. Set your Search Experience to Initialize Manually

Set initializeManually: true in config/global_config.json (same as iFrame above).

2. Create a Visitor Object

Create the visitor JSON object in your script/on-document-load.js file. If this file does not already exist, create it via Jambo Commands > Override Theme.

var my_visitor_object = {
    id: "example@yext.com",
    idMethod: "VISITOR_EMAIL"
}

3. Set Visitor Property in Runtime Config

AnswersExperience.runtimeConfig.set('visitor', my_visitor_object);

4. Initialize your Search Experience

AnswersExperience.init();

Putting it All Together

/* insert code to retrieve and generate cookie */

if (getCookie("_yfpc") != null) {
   var visitor = {
      "id": getCookie("_yfpc"),
      "idMethod": "YEXT_CONVERSION_TRACKING_COOKIE"
   };
   AnswersExperience.runtimeConfig.set('visitor', visitor);
}

AnswersExperience.init();

API

1. Create a Visitor Object

var my_visitor_object = {
    id: "example@yext.com",
    idMethod: "VISITOR_EMAIL"
}

2. Set Visitor ID as Query Parameters with Universal Search

https://cdn.yextapis.com/v2/accounts/{YOUR_ACCOUNT_ID}/answers/query?visitorId={YOUR_VISITOR_ID}&visitorIdMethod={YOUR_VISITOR_ID_METHOD}

Set Visitor ID as Query Parameters with Vertical Search

https://cdn.yextapis.com/v2/accounts/{YOUR_ACCOUNT_ID}/answers/vertical/query?visitorId={YOUR_VISITOR_ID}&visitorIdMethod={YOUR_VISITOR_ID_METHOD}

Set Visitor ID in Request Body with Click

Make a POST request to:

https://realtimeanalytics.yext.com/realtimeanalytics/data/answers/{YOUR_ACCOUNT_ID}

{
  "data": {
    "eventType": "{YOUR_EVENT_TYPE}",
    "verticalKey": "{YOUR_VERTICAL_KEY}",
    "searcher": "{YOUR_SEARCHER}",
    "entityId": "{YOUR_ENTITY_ID}",
    "experienceKey": "{YOUR_EXPERIENCE_KEY}",
    "experienceVersion": "{YOUR_EXPERIENCE_VERSION_LABEL}",
    "visitor": {
      "id": "{YOUR_VISITOR_ID}",
      "idMethod": "{YOUR_VISITOR_ID_METHOD}"
    },
    "queryId": "{YOUR_QUERY_ID}"
  }
}

Step 3: QA & Debugging

Once you finish setting up your visitor analytics, you'll want to QA your work and confirm you're seeing visitor IDs getting passed in with your searches and clicks.

If visitor ID and visitor ID method aren't getting logged with your analytics, first rule out that no visitor ID was available for the user at the time of their search/click - e.g., if your implementation requires a logged-in user's email in local storage, confirm you're logged in and that data is present.

Validating Searches

1. Right click anywhere on your page and click Inspect.
2. Click the Network tab.
3. Type "live" into the filter bar.
4. Run a search.
5. You will see two requests starting with autocomplete? and query?.
6. Click the request starting with query?.
7. Click Payload.
8. If the visitor ID and visitor ID method were passed correctly, you should see visitorId and visitorIdMethod under Query String Parameters.

Validating Clicks

1. Right click anywhere on your page and click Inspect.
2. Click the Network tab.
3. Type "analytics" into the filter bar.
4. Run a search.
5. Click on an Entity CTA in the search results.
6. For each entity you've clicked, a request will appear labeled with your Yext account's business ID.
7. Click on a request.
8. Click Payload.
9. If the visitor ID and visitor ID method were passed correctly, you should see a visitor property with id and idMethod under Request Payload.

Step 4: View Visitor Analytics

Now that you have attributed a visitor param to each user engagement event, you can begin analyzing trends.

In Analytics, you can view analytics data dimensioned by and/or filtered by visitor attributes in Report Builder or via the API. Based on what you've passed in the visitor object, available attributes include Visitor ID, Visitor Name, Visitor ID Method, and Visitor Email.

Report Builder

Set visitor attributes as either dimensions or filters in Report Builder. Then select a metric or set of metrics and click Apply Changes to view the report.

Reports API

An example POST request to get visitor-dimensioned data from the Reports API:

{
    "metrics": [
        "ANSWERS_SEARCHES"
    ],
    "dimensions": [
        "VISITOR_ID",
        "VISITOR_ID_METHOD",
        "VISITOR_EMAIL",
        "VISITOR_NAME"
    ],
    "filters": {
        "startDate": "2022-02-01",
        "endDate": "2022-05-18"
    }
}

Reference: Code Examples

Using Multiple Visitor Methods

You may have cases where not all users are identified in the same way. For example, users may still be able to use your search experience without logging in, so you'd use the login for some users and a cookie for others.

Below is a subdomain integration example that creates the visitor object using the user ID from local storage if logged in, or the Yext conversion tracking cookie otherwise:

/* insert code to retrieve and generate cookie */

let user_id = window.localStorage.getItem("visitor");

if (user_id) {
  var visitor = {
    "id": JSON.parse(user_id)["id"],
    "idMethod": "USER_AUTH"
  };
  AnswersExperience.runtimeConfig.set('visitor', visitor);
} else if (getCookie("_yfpc") != null) {
  var visitor = {
    "id": getCookie("_yfpc"),
    "idMethod": "YEXT_CONVERSION_TRACKING_COOKIE"
  };
  AnswersExperience.runtimeConfig.set('visitor', visitor);
}

AnswersExperience.init();

Reference: Using Local Storage to Store Visitor IDs

Local storage is a popular method for storing attributes about visitors. This is commonly used when your search experience is behind a login and you'd like to identify a visitor based on that login information (e.g. an email or user ID).

Retrieving a Value from Local Storage

Let's say you're storing an attribute in local storage called visitor which contains an object with these properties:

You can retrieve the id value from local storage as follows:

var user_id = window.localStorage.getItem("visitor");
var user_id = JSON.parse(user_id)["id"]

If you're getting your visitor ID from local storage, your visitor object may look like:

var user_id = window.localStorage.getItem("visitor");
var user_id = JSON.parse(user_id)["id"]

var visitor = {
   "id": user_id,
   "idMethod": "USER_AUTH"
};

Setting a Value in Local Storage

For example, if you want to link employees from an internal portal to your search experience, you could append their email to the link URL (e.g. www.my-search-experience.com?email=bob@example.com) and then retrieve and store it on the search experience page:

const urlParams = new URLSearchParams(document.referrer);
var emailFromUrl = urlParams.get('email');
window.localStorage.setItem('visitorId', emailFromUrl);

This retrieves the email parameter from the referrer URL and stores it in local storage as visitorId.

Reference: Using Cookies to Identify Visitors

Cookies allow you to assign a unique ID to a user which can be used to identify a visitor each time they visit your search experience.

Note: Depending on your local regulations (e.g., GDPR), you may be required to request consent from your users before using a cookie to track them.

Retrieving a Cookie

function getCookie(cookie_name) {
  let name = cookie_name + "=";
  let decodedCookie = decodeURIComponent(document.cookie);
  let ca = decodedCookie.split(";");
  for (let i = 0; i < ca.length; i++) {
    let c = ca[i];
    while (c.charAt(0) == " ") {
      c = c.substring(1);
    }
    if (c.indexOf(name) == 0) {
      return c.substring(name.length, c.length);
    }
  }
  return "";
}

This function takes a cookie name and returns its value. For example, to retrieve the _yfpc cookie:

getCookie("_yfpc")

If you're getting your visitor ID from a cookie, your visitor object may look like:

var visitor = {
   "id": getCookie("_yfpc"),
   "idMethod": "YEXT_CONVERSION_TRACKING_COOKIE"
};

Generating a Cookie

If you need to generate your own cookie, follow these two steps.

Step 1 - Generate a unique ID (UUID):

function create_UUID() {
  var dt = new Date().getTime();
  var uuid = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
    var r = (dt + Math.random() * 16) % 16 | 0;
    dt = Math.floor(dt / 16);
    return (c == "x" ? r : (r & 0x3) | 0x8).toString(16);
  });
  return uuid;
}

Step 2 - Generate the cookie (only if one doesn't already exist):

function generateCookie(cookie_name) {
  let cookie = getCookie(cookie_name);
  if (cookie == "") {
    let cookie_id = create_UUID();
    let cookie_expiration = 365;

    const d = new Date();
    d.setTime(d.getTime() + cookie_expiration * 24 * 60 * 60 * 1000);
    let expires = ";expires=" + d.toUTCString();
    document.cookie =
      cookie_name +
      "=" +
      cookie_id +
      ";" +
      cookie_expiration +
      ";path=/" +
      expires;
  }
}

This function generates a new cookie expiring in 365 days if one does not already exist for the visitor.