XM Directory Contact Frequency Rules for Digital Intercepts

About XM Directory Contact Frequency Rules for Digital Intercepts

The XM Directory lets you establish contact frequency rules for any digital intercepts you may have created. This feature helps enable cross-browser and cross-device contact frequency control for digital intercepts. Before you can use this feature, you need access to the following:

1. Access to XM Directory and Website / App Feedback.
2. Contacts or segments within one of your directories.
3. XM Directory automatic de-duplication should be enabled for the External Data Reference field to ensure each contact has a unique value.
   Qtip: Each of those contacts will need the Reference ID (ExternalDataReference) field specified. This value will need to be available within the logged in session for visitors on your website or app, and is used to determine if the intercept is displayed.

   Qtip: There are a number of options to ensure that your logged-in web visitors already exist in XM Directory as contacts:

   • Use the Contact Import Automation to keep XM Directory synced with your customer lists.
   • Within your new user creation flow, you can work with your development team to also create the contacts within XM Directory using the following APIs: create a new contact and update a contact.
4. Contact Frequency rules configured to limit how often the intercept is shown. You may use general directory rules as well as custom rules for specific surveys.
   Attention: At this time, Custom rules that apply to Lists are not supported. If multiple intercepts on the same page use XM directory rules based on lists (same directory or different directories), we will only show one of those intercepts. The displayed intercept will be the oldest one.
5. A web developer resource. Your methodology will differ depending on whether you want to use contact frequency functionality with a mobile app or a website.
   • App: Partner with your Mobile App development team in order to integrate with the latest version of the Qualtrics Mobile App SDK. See the API documentation.
   • Website: You will need to work with your web development team to ensure that the contact’s Reference ID is made available within their logged in session and able to be extracted through a JavaScript expression or a Cookie. Read the JavaScript Expression for Retrieving Reference ID section for information about retrieving the Reference ID value through JavaScript.

     Qtip: Additionally, if you enable the checkbox in Intercept options for contact frequency, but fail to set the externalReference using the client side JS code, then the intercept will behave as if contact frequency rules are not enabled. This means the intercept display will only be governed by the sampling and cookies-based prevent repeated display rules.

      

     However, if you pass in an externalReference using client side JS code, such that this ID does not match the Reference ID for any contact in your directory, the intercept will NOT be displayed. This is because we will not know how to apply XM Directory Contact Frequency rules for this user.

Setting up Contact Frequency Rules for Intercepts

1. Open one of your existing Website / App Feedback projects, or create a new project.
2. Open one of your existing intercepts, or create a new intercept.
3. Click on the intercept’s Options.
   
   Qtip: The steps are the same on mobile app intercepts, but you will see fewer intercept options.
   
4. Enable Link With XM Directory.
5. Choose the directory.
6. Enable Contact frequency rules and choose the directory in which the contacts are saved.
7. Publish your changes.
8. The next steps differ based on whether you are implementing this functionality on a website or a mobile app.
   • Website: On your website where you will launch the intercept, specify the JavaScript expression that will be evaluated in the user’s logged in session to obtain the External Reference ID for the contact. This External Reference ID is used to look up the visitor in the XM Directory and track if they’ve seen your intercept. See the below section for more details on the JavaScript expression.
   • App: On the app where you will launch the intercept, you will need to make an update to your mobile app SDK in order to retrieve the reference ID. See the API documentation.

JavaScript Expression for Retrieving Reference ID on a Website

To make sure your intercept is obeying your contact frequency rules, you will need to specify the JavaScript expression that is evaluated in the user’s logged in session to obtain the External Reference ID for the contact.

To do so, you will need to set the externalReference variable within your code such that it is above and available to the Qualtrics Website / App Feedback snippet that is also on your site. Below is an example of such an expression:

if(typeof QSI === "undefined") {

QSI = {};

QSI.config = {

externalReference: extRef

};

}

Retrieving Reference ID on an App

In order to retrieve the Reference ID for a mobile app intercept, you will need to make an update to your mobile app SDK. See the API documentation.

Testing Contact Frequency Rules for Website Intercepts

Before launching your intercept on your website, you should test it to make sure the display based on contact frequency rules have been implemented correctly.

In your real deployment, your site visitor’s External Reference ID will be available in the context of their logged session through a Javascript expression or a cookie.

The below steps allow you to perform an end to end scenario using test data and web browser workarounds.

1. In your XM Directory, create a new contact and specify a unique Reference ID for that contact.
   Example: We’ll be using aaa123 as our example Reference ID. Any time you see ID number in these steps, replace it with the Reference ID you specified.
2. Follow the steps in the Setting up Contact Frequency for Intercepts section to configure an intercept to follow contact frequency rules.
3. Go to Test Intercept.
   
4. Drag the bookmarklet to your Browser Bookmarks bar.
5. Go to a web page that you want to use for testing.
6. Go to the Developer Console. Depending on your web browser, you’ll reach it differently:
   • Google Chrome: In the Chrome menu bar, go to View → Developer → Developer Tools. In the window that appears, go to the Console.
   • Apple Safari: Ensure the Develop menu is enabled for Safari. To do this, go to Preferences → Advanced → Show Develop menu in menu bar. Click Develop in the Safari menu and select Show Web Inspector. In the window that appears, go to the Console
   • Mozilla Firefox: Click the menu icon and then select Web Developer. In the Web Developer menu, select the Console
   • Microsoft Edge: In the menu bar, go to Tools → Developer → Developer Tools. In the window that opens, go to the Console
   • Internet Explorer: Click the Gear icon and select Developer Tools. In the window that opens, go to the Console.
7. In the Console menu, type this expression and then press Enter:

   UserID="aaa123"

   

   Qtip: aaa123 is our example Reference ID value and should be replaced with the value you assigned to the contact in step 1.
8. Paste the JavaScript snippet below to set up the externalReference JavaScript variable to be your JavaScript expression.

   
   if(typeof QSI === "undefined") {
   
   QSI = {};
   
   QSI.config = {
   
   externalReference: UserID
   
   };
   
   }
   

   

9. Press Enter.
10. Click the bookmarklet and you will see that the contact frequency rules will be appropriately honored to determine if the intercept should or should not be displayed.

To repeat these steps for additional testing, please do the following between tests:

1. Refresh your browser each time.
2. Set up the JavaScript expression within your Console.
3. Run your bookmarklet again.