Skip to main content
  • Customer Experience
    Customer Experience
  • Employee Experience
    Employee Experience
  • Brand Experience
    Brand Experience
  • Product Experience
    Product Experience
  • Core XM
    Core XM
  • Design XM
    Design XM

XM Directory Contact Frequency Rules for Digital Intercepts

What's on This Page:

Was this helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

The feedback you submit here is used only to help improve this page.

That’s great! Thank you for your feedback!

Thank you for your feedback!

About XM Directory Contact Frequency Rules for Digital Intercepts

Attention: To use this feature, your Qualtrics brand needs to be on the updated XM Directory infrastructure and you must request this feature be enabled for your brand. To check your brand’s status and to request this feature, contact your Customer Success Representative.

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:

  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

Qtip: For a video demonstration of using this feature and seeing it in action, check out this post on the Qualtrics Community!
  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.
    The interface on a Web/App Feedback project when connecting it with XM Directory

    Qtip: The steps are the same on mobile app intercepts, but you will see fewer intercept options.
    Mobile app options only include display sample rate, random action sets, and the link with xm directory 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

Attention: The following documentation requires programming knowledge to implement. We recommend passing this information to the team that will be implementing your deployment code. Our support team does not offer assistance or consultation on custom coding. You can always try asking our community of dedicated users instead. If you’d like to know more about our custom coding services you can commission, please contact your Qualtrics Account Executive.

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


Attention: Make sure that instead of extRef you specify the JavaScript expression that needs to be evaluated to obtain the appropriate External Reference ID (for example “UserID”). This expression may be as simple as a JavaScript variable or a JavaScript expression to evaluate a specific cookie.
Qtip: If an end-user logs on to your site with an External Reference ID that is not currently in XM Directory (i.e., this user’s record is not yet in XM Directory or they are an anonymous user), then the intercept will not appear for this user. For anonymous users, if you pass in an empty value (“”) for the externalReference setting, then they will always be shown the intercept.

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.
    image of the test intercept section of an 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:

    the console view of a webpage. the expression UserID="aaa123" has been entered here

    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

    image of the console view of a webpage with the associated JS snipped pasted in

  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.