@qualtrics/plugin-client

Qualtrics Plugin Client

The Plugin Client provides a library of JavaScript methods that perform much of the low-level functionality common to all Qualtrics Plugins, including:

• Message handling
• External requests
• Text localization

Ensure that your index.html file references the latest version of the Plugin Client in all your Plugins, both as you start a new project and before you submit your Extension.

Using the Plugin Client

To use the Plugin Client library in your XM Plugin, declare it as a dependency in your package.json file:

{
  "name": "myPlugin",
  "version": "0.0.1",
  ...
  "dependencies": {
    "@qualtrics/plugin-client": "<version>"
  }
}

Message Handlers

Messages and Message Handlers are used to communicate between the Plugin Host page and the Plugin (to save changes, validate data, etc).

For example, you could send a canClose message from the Host page to indicate that the Plugin is ready to close.

You would do this by adding a handler for this message to a messageHandlers object which is then passed in during the initialization of the PluginClient.

const messageHandlers = {
  canClose: (input) => {
    // dataValid is a made-up function for this example
    return {canClose: dataValid()}
  },
}

// Initialize Plugin Client
window.PluginClient.initialize(eventHandlers).then((pluginClient) => {
  // Use the client
})

Based on the type of Plugin you are developing, your Plugin must handle various messages sent from the Host page. For a full list of messages, read the documentation for your Plugin Type.

NOTE Only one handler can be registered for a given message.

Making Requests

Your Plugin may need information at run-time from the Host, from an external API/resource, or from the Qualtrics API.

Supported Methods

The Plugin Client offers three methods to retrieve information:

• postMessage for Host requests
• fetch2 for external third-party API requests
• qualtricsApiFetch2 for Qualtrics API requests

Supported Host Messages

Messages specify functionality of requests to the Host—helper functions, data processing and storage, etc. To implement them, use the postMessage function in the Plugin Client.

When you need to request data from the Host, first look at the supported messages for your Plugin type. These are messages that the Host already has registered handlers for. You can find a list of supported messages for each Plugin type in its respective guide.

Example Message Request

For example, a Plugin Host might publish a handler for a getSurveyDef message, which returns the survey definition.

A Plugin could interface with that handler by sending a message like so:

// Plugin Client was initialized earlier
try {
  const surveyDef = await pluginClient
  .postMessage('getSurveyDef', {surveyId: 'SV_123'})
    // Use surveyDef
} catch (e) {
    // Report error
}

Localization

The Plugin Client provides helper functions for locating language-specific translations of Plugin content.

Defining Localized Content

The first step is to define a translation file in the Plugin's translations folder.

These are JSON files, each named using the Qualtrics Language Code for each language you intend to support. For example, the translation file for English is EN.json.

Below is an example translation file for English, EN.json.

{
  "meta": {
    "summary": "Plugin Language Strings - EN"
  },
  "strings": {
    "name": {
      "text": "Qualtrics Custom Plugin"
    },
    "description": {
      "text": "Qualtrics Custom Plugin"
    },
    "longDescription": {
      "text": "Qualtrics Plugin for experience management"
    },
    "title": {
      "text": "Facebook Plugin"
    },
    "likes": {
      "text": "You have {{number}} likes",
      "context": "For listing the number of likes the post has"
    },
    "comments.notification": {
      "text": "{{user}} got a comment from {{name}}"
    }
  }
}

You can use the meta section of the file to provide meta information about the translation at your discretion.

NOTE There is no enforced syntax for the meta section, only the requirement that it exists.

Reserved and Custom Keys

The strings section of the translation files is used to define templates for text that appears in your Plugin. The name, description, and longDescription keys are reserved for describing the Plugin to those who will be using it in this language.

Otherwise, you are free to define your own template strings in the strings section to provide localized content for your Plugin.

Fetching Localized Text

The platform automatically selects the appropriate .json file that matches the language selected at runtime.

Here are a few examples of how to read strings from the appropriate .json file in the translations folder:

client.getText('title')
// Returns "Facebook Plugin".

client.getText('likes', {number: 2})
// Returns "You have 2 likes".

client.getText('comments.notification', {user: 'Bob', name: 'Alice'})
// Returns "Bob got a comment from Alice".

client.getText('comments.reaction', {}, 'Thumbs Up')
// The translations don't include the key "comments.reaction", so this returns the provided default of "Thumbs Up".

You have access to your translations and getText once the Plugin Client has been initialized.

For further details on Plugin Client functionality see its method API documentation.