Skip to main content

Connecting with XM Directory

When your Website / App Insights project is linked to XM Directory, you can target intercepts by contact segments, apply contact frequency rules, and create contacts automatically. The Web Feedback JavaScript APIs let you pass the External Reference ID (and optional contact data) to Qualtrics so website visitors can be matched to XM Directory contacts.

Prerequisites​

  • XM Directory and Website / App Insights enabled on your Qualtrics brand
  • An identity resolution rule in XM Directory based on External data reference
  • Your project linked to XM Directory (see XM Directory Integration with Digital Intercepts for setup)

Setting the External Reference ID​

To match website visitors with XM Directory contacts, set QSI.config.externalReference before the Website Feedback deployment code runs. The value must match the External Reference ID (Reference ID / ExternalDataReference) configured for contacts in XM Directory.

Important: The snippet below must appear above the project deployment code on each page where you target visitors with intercepts.

if (typeof QSI === "undefined") {
  QSI = {};
}
QSI.config = {
  externalReference: userId  // Replace with your JavaScript expression (e.g., variable, cookie)
};

Replace userId with the JavaScript expression that evaluates to the visitor's External Reference ID—for example, a variable from your auth system, a cookie, or a value from your page.

Example: From a Variable​

// Assume your app sets window.currentUserId when the user logs in
if (typeof QSI === "undefined") {
  QSI = {};
}
QSI.config = {
  externalReference: window.currentUserId
};
function getExternalRef() {
  var match = document.cookie.match(/externalRef=([^;]+)/);
  return match?.[1] ?? null;
}
if (typeof QSI === "undefined") {
  QSI = {};
}
QSI.config = {
  externalReference: getExternalRef()
};

Example: Config and Deployment in the Same Script Tag​

You can set QSI.config in the same <script> tag as the deployment snippet, as long as the config comes first:

<!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
<script type='text/javascript'>
  // Set config before the deployment code loads
  if (typeof QSI === "undefined") {
    QSI = {};
  }
  QSI.config = {
    externalReference: window.currentUserId
  };

  (function(){var g=function(g){
  this.go=function(){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)};
  this.start=function(){var t=this;"complete"!==document.readyState?window.addEventListener?window.addEventListener("load",function(){t.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){t.go()}):t.go()};};
  try{(new g("https://your-brand.qualtrics.com/SIE/?Q_ZID=ZN_YourZoneId")).start()}catch(i){}})();
</script>
<div id='ZN_YourZoneId'><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
<!--END WEBSITE FEEDBACK SNIPPET-->

Automatic Contact Creation​

When Automatic Contact Creation is enabled for your project, you can pass additional contact fields so new visitors are added to XM Directory. Set these in QSI.config before the deployment code runs:

if (typeof QSI === "undefined") {
  QSI = {};
}
QSI.config = {
  externalReference: userId,
  firstName: "Jane",
  lastName: "Smith",
  language: "English",
  contactEmbeddedData: {
    "Location": "Seattle",
    "Segment": "Premium"
  }
};

Supported fields include externalReference, firstName, lastName, email, phone, language, and contactEmbeddedData (key-value pairs). See the XM Directory Integration support page for limits and details.

Notes​

  • Case sensitivity: External Reference ID is case sensitive. Ensure the value matches XM Directory exactly.
  • Timing: Set QSI.config before the deployment snippet loads. You can set it in the same <script> tag as the deployment snippet (see Example: Config and Deployment in the Same Script Tag). If the value is not yet available (e.g., after async login), ensure it is set before any intercept evaluation.
  • jsExpressionValues in run(): Values passed to QSI.API.run(options) via jsExpressionValues do not populate externalReference. Use QSI.config.externalReference for XM Directory matching.

See Also​