@qualtrics/plugin-client 1.9.15-rc.2029.2a6f60 → 1.9.15-rc.2031.d40350

package/README.md

@@ -0,0 +1,175 @@
+# 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](#message-handlers)
+* [External requests](#making-requests)
+* [Text localization](#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:
+
+```json
+{
+  "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`.
+
+```javascript
+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](https://pdx1.qualtrics.com/developer/portal/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&mdash;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:
+
+```javascript
+// 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](https://api.qualtrics.com/76d1dbf1c7f54-language-codes) 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.
+
+```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:
+
+```javascript
+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](https://pdx1.qualtrics.com/developer/portal/documentation/e14ccbcbe824f-plugin-client-methods).
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qualtrics/plugin-client",
-  "version": "1.9.15-rc.2029.2a6f60",
+  "version": "1.9.15-rc.2031.d40350",
   "description": "Interface for XM Plugins to communicate with the environment they're rendered in",
   "scripts": {
     "ci-build": "yarn clean && yarn build",

package/src/lib/plugin/buildConfig.js

@@ -1,3 +1,3 @@
 // Provide configuration that is supplied at build time.
-export var getClientVersion = function () { return "1.9.15-rc.2029.2a6f60"; };
+export var getClientVersion = function () { return "1.9.15-rc.2031.d40350"; };
 //# sourceMappingURL=buildConfig.js.map