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. You will also want to set up analytics for your search bar.

iFrame

If your search experience is integrated via an iFrame, you can collect visitor analytics by doing the following:

1. Set your Search Experience to Initialize Manually

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

To do so you will set the initializeManually property in your config/global_config.json file to true, like below:

{
  "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 your search experience to initializeManually: true the next thing you’ll need to do is create a JSON object wherever your iFramed search experience lives.

This object will consist of the following two properties:

Using the example, this object would look like the following:

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

You can read more about how to get your visitor ID from a cookie here and from local storage here.

3. Set Visitor Property in Runtime Config to Visitor Object

Once you’ve constructed your visitor object, you’ll want to set the visitor property in your runtime config to this object.

For example, using the visitor object above called my_visitor_object, you would do this as follows:

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

You should only set the visitor property on your runtime config when you have a visitor ID you want to associate with your searches and clicks. If no visitor ID is available (because a customer did not opt into cookies, log in to your experience, etc.) then this property should not be set.

4. Initialize your Search Experience

Finally, once your visitor has been correctly set you’ll want to initialize your search experience with the following code:

AnswersExperienceFrame.init({});

This will ensure your search experience returns results and attributes searches and clicks to your visitor. Note that if you do not initialize your experience, searches will return no results and no visitor will be logged with your searches.

Putting it All Together

If you’re using the cookie method for getting your visitor ID, you might customize your standard iFrame integration search results page (step 3) like below:

<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

If your search experience is integrated via a subdomain, you can collect visitor analytics by doing the following:

1. Set your Search Experience to Initialize Manually

To ensure that your visitor ID is correctly passed with any searches or clicks that are conducted on your search experience you need to make sure that your visitor ID is being set before your experience is initialized.

To do so you will 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 your search experience to initializeManually: true the next thing you’ll need to do is create a JSON object in your script/on-document-load.js file. If this file does not already exist you can create one yourself by going to Jambo Commands > Override Theme and selecting this file.

This object will consist of the following two properties:

Using the example, this object would look like the following:

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

You can read more about how to get your visitor ID from a cookie here and from local storage here.

3. Set Visitor Property in Runtime Config to Visitor Object

Once you’ve constructed your visitor object, you’ll want to set the visitor property in your runtime config to this object.

For example, using the visitor object above called my_visitor_object, you would do this as follows:

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

You should only set the visitor property on your runtime config when you have a visitor ID you want to associate with your searches and clicks. If no visitor ID is available (because a customer did not opt into cookies, login to your experience, etc) then this property should not be set.

4. Initialize your Search Experience

Finally, once your visitor has been correctly set you’ll want to initialize your search experience with the following code:

AnswersExperience.init();

This will ensure your search experience returns results and attributes searches and clicks to your visitor. Note that if you do not initialize your experience, searches will return no results and no visitor will be logged with your searches.

Putting it All Together

If you’re using the cookie method to get your visitor ID, your script/on-document-load.js file may look like the following:

/* 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

If your Search experience is integrated with the API directly, you can collect visitor analytics by doing the following:

1. Create a Visitor Object

Once you’ve set your search experience to initializeManually: true the next thing you’ll need to do is create a JSON object in your script/on-document-load.js. If this file does not already exist you can create one yourself by going to Jambo Commands > Override Theme and selecting this file.

This object will consist of the following two properties:

Using the example, this object would look like the following:

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

You can read more about how to get your visitor ID from a cookie here and from local storage here.

2. Set Visitor ID and Visitor ID Method as Query Parameters with Universal Search

Once you’ve constructed your object you’ll need to pass this in with your Universal Search API call.

You can do so as follows:

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

You can learn more about the Universal Search API here .

Set Visitor ID and Visitor ID Method as Query Parameters with Vertical Search

Once you’ve constructed your object you’ll need to pass this in with your Vertical Search API call.

You can do so as follows:

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

You can learn more about the Vertical Search API here .

Set Visitor ID and Visitor ID Method in Request Body with Click

Once you’ve constructed your object you’ll need to pass this in with your Search Events API call.

You can do so by making a POST request to the following endpoint:

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}"
  }
}