XM Extension Deep Dive

Summary

This guide walks you through the what and how of XM Extensions.

Prerequisites

We recommend that you complete these items before continuing with this guide.

• Read through the XM Extension SDK overview
• Go through the XM Extension overview

Limitations

Just like the XM EXtension SDK, XM Extensions are available to registered Qualtrics XM Developers.

Fundamentals

Publish your Extension to the Qualtrics Marketplace

Follow these steps to get your XM Extension listed on the Qualtrics Marketplace:

Step	Description	Required	Links
1	Sign up to become an official Qualtrics Partner (if your company hasn't already)	Yes	Registration
2	Preview your Extension with a few joint customers to verify that it meets their use cases	No	Documentation
3	Certify your Extension	Yes	Documentation
4	Review and sign the Qualtrics Marketplace Agreement. This document has to be signed without any modifications	Yes	Agreement
5	Request the listing of your Extension on the Qualtrics Marketplace	Yes	Survey

Why Build XM Extensions?

Qualtrics is an open platform that developers can extend by building against its REST API and other built-in integration points.

Developing an Extension requires:

• Meeting the Qualtrics UX style guide
• Providing a native-like experience
• Marketing to existing and potential Qualtrics customers
• Managing the Extension (deploying, updating/upgrading, removing)

To make it easier to extend Qualtrics and to market those Extensions, we've created functionality and tooling to assist you with the above challenges.

What is an XM Extension?

An XM Extension is a set of configuration and UX components that organize and coordinate functionality to:

1. Extend One or More Parts of the Qualtrics Platform

An Extension's functionality is packaged into discrete components called XM Plugins.

2. Manage the Extension Through its Lifecycle Phases

• Creation
• Management
• Validation
• Submission
• Certification and Publishing
• Preview
• Discovery
• Support
• Re-certification
• Removal

Tech Stack Overview

XM Extensions run in a supported browser using HTML, JavaScript, and CSS. Plugin JavaScript dependencies are managed using npm (or Yarn).

Tech Stack Components

The table below summarizes the role and support commitment relevant to each tool, framework, or resource used in your local development environment or at runtime.

Component	Required?	Development only?	Qualtrics version support notes
browser / CSS / JavaScript	✔︎		See Qualtrics-supported browsers
Node.js	✔︎	✔︎	The Qualtrics SDK supports the latest stable LTS version of Node.js for development, and developers should only use LTS versions of Node.js (even releases, e.g. 14.x, 16.x, etc.) See Node.js website (releases)
npm	✔︎ (or Yarn)	✔︎	The Qualtrics SDK supports the latest stable version of npm (note that npm releases more frequently than Node.js)
Yarn	✔︎ (or npm)	✔︎	Yarn can be used as an alternative to npm
xmt	✔︎	✔︎	xmt.exe is the native SDK command-line tool for creating and managing XM Extension components (it auto-updates when needed every time it is executed)
React			Qualtrics provides optional, React-specific library components for developers using that framework

XM Extension Lifecycle

The lifecycle of an XM Extension consists of 10 phases. Let's walk through each phase below:

Phase 1: Extension Creation

In the Quick Start guide, you created an XM Extension with the command xmt create extension -n ‘Hello World’ That command automatically created an XM Extension template with these components:

1. An assets directory with default logos and the default translations file EN.json
2. A configuration file named manifest.json

Your Extension directory should look like this:

example_extension
├── assets
│   ├── images
│   │   └── logo.svg
│   └── translations
│       └── EN.json
└── manifest.json

Let's look at each directory and file in more detail:

assets >> images Directory

The assets/images directory is where you store your Extension's logo, which is displayed in various screens inside of the Qualtrics Platform.

One logo, logo.svg, serves as an examples of the dimensions and quality expectations of the company logo you provide.

Replace the Preloaded Logo Image

You can submit your Extension with the preloaded logo image but you must replace it with one from your product before your Extension can be certified.

Task Bar Example

Task Selection Example

assets >> translations Directory

The translations directory contains a file for each language you want to support.

Qualtrics products support many languages and dialects. For implementation details, see the Translations guide guide under the Step 2: Foundations section.

manifest.json File

This file contains important metadata and settings for your Extension.

manifest.json Schema

{
    "id": "APP_12345678-abcd-efgh-ijkl-123456789012",
    "version": "2.1.0",
    "schemaVersion": "0.0.5",
    "info": {
        "termsUrl": "https://example.com/terms",
        "privacyUrl": "https://example.com/privacy",
        "documentationUrl": "https://example.com/docs",
        "helpEmail": "help@example.com",
        "organizationName": "Example",
        "websiteUrl": "https://example.com/your-extension"        
    },
    "connections": [
        {
            "name": "Instagram",
            "scheme": "basic",
            "target": "instagram"
        }
    ],
    "validDomains": [
        "*.example.com"
    ],
    "adminControls": {
        "addValidDomains": true
    }
}

manifest.json Properties

Property Name	Type	Required	Editable	Description	Example
id	String	Yes	No	The unique Identifier for your Extension. This must be present and valid or no actions can be performed.	"APP_c17b43b9-019d-49e3-8122-5a43e74dcXXX"
info.privacyUrl	String	Yes	Yes	The URL to your company’s privacy policy	Qualtrics’ privacy policy
info.termsUrl	String	Yes	Yes	The URL to your company’s terms of service	Qualtrics’ terms of service
info.helpEmail	String	Yes	Yes	A support email address that customers can send questions/issues to	"support@qualtrics.com"
info.documentationUrl	String	Yes	Yes	The URL to the support documentation that instructs users on how to set up and use your Extension. It MUST be publicly accessible although it MAY require a login to access it.	SalesForce + Qualtrics integration
info.organizationName	String	Yes	Yes	Your company's name	"Qualtrics"
info.websiteUrl	String	No	Yes	The URL to a landing/marketing page for your Extension	SalesForce + Qualtrics
version	String	Yes	Yes	Your XM Extension version, which should follow the semantic versioning industry standard	“0.1.4”
schemaVersion	String	Yes	No	The semantic version of the manifest.json configuration file that gets created automatically	“0.0.5”
validDomains	Array of Strings	Yes	Yes	List of domains that your extension is allowed to communicate with, either from the user's browser or a backend proxy service. Follows the matching spec defined here	"*.your-domain.com"
adminControls.addValidDomains	boolean	No	Yes	Allows Brand Administrators to configure extra validDomains for the backend proxy service.	true
connections	Null / Object	Yes	Yes	Authentication settings for external APIs that get created by xmt create connection and automatically inserted into your manifest.json file. These authentication settings can be used by any plugins of your extension	See example above

Placeholder Required Fields

During development and testing you may provide placeholder values for some of the required fields (please remember to replace them with legitimate values before requesting certification)

plugins Directory

The plugins folder is created automatically when you create the first Plugin within your Extension. All the XM Plugins that make up your Extension's functionality will each have a subfolder within the plugins folder.

Phase 2: Extension Management

Based on the functionality of your Extension, you may need to update some of its settings and functionality on occasion.

Common Management Tasks

These FAQs explain how to perform common XM Extension management tasks:

Question	Answer
How do I remove a Connection?	Currently the way to remove an unwanted Connection is to make sure that no plugins reference it, then edit the manifest.json file, delete the connection object from the connections array, and then re-submit your Extension. We are working on adding functionality to remove Connections via xmt.
How do I change a Connection?	You cannot change a Connection directly. You must first remove the existing Connection (see How do I remove a connection above) then add a new one.
How do I rename my Extension?	Edit the assets/translations/EN.json file (and any other translation files you have) and change the value in the strings.name.text key to the new name.
How do I edit my Extension's description?	Edit the assets/translations/EN.json file (and any other translation files you have) and change the text in the strings.description.text key.
How do I edit my Extension's long description?	Edit the assets/translations/EN.json file (and any other translation files you have) and edit the text in the strings.longDescription.text key.
How do I update my Extension version?	Edit the manifest.json file and update the version key with an appropriately-incremented semantic version.

Phase 3: Extension Validation

Validating your Extension is an important step in verifying it's ready to submit to the XM Extension Registry. Running the xmt validate extension command checks that the Plugin meets basic requirements such as having a name and and icon, in addition to checking for general runtime errors.

Validate Your Extension

Run the validate command from within your Extension's root directory to perform the validation:

xmt validate extension

Validation Frequency

You should validate your Extension:

1. After you make changes to it (before version control commit)
2. Before submission

Phase 4: Extension Submission

After successfully submitting your Extension, it is stored automatically in the Qualtrics XM Extension Registry.

Increment Extension Version

Each time you submit your Extension you must increment the version property, as described in the Semantic Versioning specification.

Submit Your Extension

Run the submit command from within your Extension's root directory to submit your Extension:

xmt submit extension

Submission Process

Your Extension goes through this process during submission:

1. All the content in your Extension directory gets zipped into a compressed file, including all the Extension's Plugins
2. A check of the compressed file's size fails above a hard limit of 20 MB
   • Upon failure an informative error shows and the validation process terminates
   • Use the .xmtignore file to exclude folders and files from submission
3. The xmt CLI sends the compressed file to the Qualtrics XM Extension Registry, which tracks and manages all XM Extensions
4. More validations run
   • If they fail, an appropriate error message displays and the submission process terminates
   • If it succeeds, it’s on to the next step:
5. The XM Extension Registry either creates or updates an Extension entry

Troubleshooting Submission Issues

If your Extension fails validation during the submission process, you will receive a detailed explanation of the reason. The most common reasons are:

• Icons and Logos are missing or do not follow the guidelines
• A developer not on your XM Extension Team tries to submit the Extension
• The package exceeds size limits
• The configured default language is missing its corresponding translation file
• Required fields in the manifest.json file are missing or are otherwise invalid

Phase 5: Extension Certification

An XM Extension must obtain formal certification by Qualtrics before you can publish it to the XM Extension Marketplace.

Follow this guide to prepare your XM Extension for certification.

When to Skip Certification

If your Extension is meant for a single customer or brand, then it does not need to go through a certification review.

Phase 6: Extension Preview

While not required, you may preview your XM Extension with a few select customers to verify that the functionality works as they expect. To grant preview access to a customer, please submit a request via the Feedback & Support button in the lower right part of the Developer Portal.

Gathering customer feedback, reacting to that feedback, and generally supporting customers during this phase is the responsibility of your development team.

Be sure to use the feedback you receive in this phase to improve your XM Extension before publishing it to a wider audience/market.

You can also use the Feedback & Support button to ask any questions about best practices.

Phase 7: Helping Customers Discover & Enable Your Extension

Once your Extension is certified you have the option to make it Generally Available (GA) or to enable it only for select customers.

Access to GA Extensions is dependent on the license of Qualtrics customers. See the upcoming section called Extension Support for more details on how you will be expected to support your customers during their onboarding.

Should you choose to enable your Extension selectively, your team will be responsible for onboarding the customer and must notify either Developer Advocacy or the SDK Certification team of any new enablements.

For a legal perspective, please also review the Developer Terms and Partner Terms on the licensing and sharing of Extensions built on the Qualtrics platform.

Phase 8: Extension Support

Once your Extension is in use by customers (during both preview and full release), you will be the 1st-Level Support for any issue or unexpected behavior. You're not totally on your own, of course: Qualtrics supports your team and the underlying extension framework and runtime, so if you determine that the issue relates to the Qualtrics platform or the integration points, you can escalate it to us.

You will need to address any issues caused by your Extension in a timely manner and if necessary publish a new version, which requires requesting and passing a new Certification Review.

Section 7 of the XM Extension Certification page stipulates that you must provide a clear method of contact so that support requests can be made quickly and easily by your customers.

Phase 9: Extension Recertification

Every time you make updates you want to push to your customers, you must recertify your Extension.

Upon recertification, your customers automatically move to the newly certified version.

Phase 10: Extension Removal

The requirements and process for this phase in the XM Extension lifecycle are still being finalized.

Extension Versioning FAQs

These FAQs attempt to answer questions that you may have regarding developing and versioning your XM Extension.

Please submit any follow-up questions on these FAQs by clicking on the blue Feedback & Support button on this screen.

Extension Owner Perspective

These FAQs are written from the perspective of a software developer who is the Extension Owner, meaning that they either created the Extension or have been given the Owner role. See here for more details on roles.

Q1: How do I work on my Extension locally?

A1: XMT and QDB

1. Execute the xmt develop extension command and relevant npm scripts in the package.json file of your Plugins.

2. Share your Extension with either your Developer Brand or a sandbox brand.

3. Review and test your Extension with your Qualtrics Developer Brand ("QDB")

Q2: How do I collaborate with my coworkers on my Extension?

A2: Version Control, Team Management, and QDB

1. Ensure your Extension is maintained in a version control system (e.g. Git) and manage it with your team per the VCS conventions you follow
2. Invite your coworkers to join your Extension team with an appropriate Team Role (either Developer or Admin)
3. Each Extension Team member can share and launch the Extension in their Qualtrics Developer Brand via buttons on the Qualtrics Developer Portal Extensions Page

Log in to Developer Portal

You must be logged in to the Developer Portal to see the Extension and the share and launch buttons

Q3: How do I preview my Extension with select customers?

A3: Innovation Partners Only

1. Verify that your situation meets these criteria:
   1. The version of your Extension that you wish to preview has not already been published
   2. Your company is an official Qualtrics Innovation Partner
   3. You have an account on the Qualtrics Partner Portal
2. Submit your Extension with this command xmt submit extension
3. Share your Extension version with the appropriate customer brands per these instructions
4. Collect any feedback and usage data through your own mechanisms
5. Conclude the preview by revoking the sharing of your Extension

Q4: How do I deliver my Extension to a single customer?

A4: Same as Answer 2 above

See Answer 2 for details.

Q5: How do I deliver my Extension to many customers?

A5: Certification and Publishing

1. Follow these steps in fulfilling the XM Extension certification policies until your Extension attains a passed certification review.
2. For first-time Extension certifications: There may be a waiting period while your Extension is made available to previous and future customers.

Brands on Prior Certified Versions are Updated Automatically

If you have prior versions of your Extension that have been certified, published, and installed by customers, then those brands will automatically be upgraded to your newest published version.

How this behaves for individual users depends on the type of XM Plugins that your Extension contains.

Q6: How do I migrate users to newer non-breaking versions of my Extension?

A6: Bridge Functionality Gaps and Communicate

1. Reach out to Qualtrics Developer Advocacy via the blue Feedback & Support button to communicate your planned Extension version changes and ask any questions
2. Submit a new Extension version following Semantic Versioning (e.g. MINOR or PATCH version bump)
   1. For each changed Plugin, write code handles that handles functionality changes between the legacy and new versions
3. Ensure your new Extension version has been certified, if needed
4. (Optional) Communicate to each customer on older versions with instructions on how to upgrade
   1. Communicate whether the previous Extension version is being deprecated and corresponding timelines
5. (Optional) Follow-up with users on an as-needed basis to assist their version upgrade efforts

Q7: How do I migrate users to newer breaking versions of my Extension?

A7: Create New Plugins and Communicate

1. Complete these steps for each of your Extension Plugins that contain breaking changes:
   1. Create a new Plugin of the same type in the same Extension
   2. Copy the code from the legacy Plugin over into the new Plugin
   3. Add the breaking-change functionality
2. Submit a new Extension version following Semantic Versioning (e.g. MAJOR version bump)
3. Ensure your new Extension version has been certified, if needed
4. (Optional) Communicate to each customer on older versions with instructions on how to upgrade
   1. Communicate whether the previous Extension version is being deprecated and corresponding timelines
5. (Optional) Follow-up with users on an as-needed basis to assist their version upgrade efforts

Tips and Tricks

• Leverage the xmt develop extension command in conjunction with Prerelease versions instead of xmt=1 or submitting new versions.
• Authenticate with OAuth 2.0 and associated scopes
• Enable users to test their account credentials during the initial set up
• Ask questions on the Extension SDK XM Community page.
• For Public/Marketplace Extensions, thoroughly review Certification criteria and adhere to them before requesting a formal Certification Review.
• Specify https for all outbound network requests as they must be made over the TLS protocol.
• Learn how to share your Extension to different users for different scenarios (co-develop, test, preview, publish).

Recommended Content

Well done! You learned what XM Extensions are, why you should build them, and all about their lifecycle phases!