r1-ext-client

v0.0.13

Published

3 years ago

Client library to talk to the ReplyOne UI via inter-frame communication

Downloads

0High
0Medium
0Low

jbedersdorfer

ReplyOne Web Extension Client Library

Note: This is a preview of the Web Extension API. It might change significantly. Use at your own risk

Use this library to create extensions of the ReplyOne UI.

Extensions are web applications that can be embedded in various places of the ReplyOne Desk, Chat or Control UI.

Wireframe

Extensions are embedded as an iframe and communicate via Messages.

They are informed of important lifecycle events, data updates and can also change data like document properties. They run with the same rights as the currently logged in user, that means any actions done by the Extension are subject to the roles and permissions of that user.

Extensions can be very small additions (like showing a map for addresses of the current user) or be complete enterprise application integration systems, where data can be exchanged to update ReplyOne data and vice-versa.
Most importantly, they are fun to write, we hope!

Quick Start

Grab your favorite web site or web application builder, then:

npm install r1-ext-client
Add import * as r1Ext from 'r1-ext-client'
or add <script src="node_modules/r1-ext-client/dist/r1-extension.js">

const r1Location = "http://my-replyone.com"; // origin (i.e. scheme + host + port) where your ReplyDesk instance is running 
const api = r1Ext.register(r1Location, { processingStart: doc => { ... }});

Receive those sweet events or use one of the api functions to request information from the ReplyOne UI

Slow Start / Tutorial

Pre-requisites

R1 Web Extensions are just regular web sites or web applications that are embedded inside the ReplyOne UI using an iframe. So any tool to build a web site can be used. On the fancy end, feel free to use TypeScript, Webpack, React, Vue, lit-html, svelte, re-frame or even Angular to create an extension.

For this tutorial, we'll use old-school Vanilla JavaScript and NPM to download the r1-ext-client library. Thus if you haven't done so already, install Node.js (For Windows, make sure npm ends up in your PATH variable. Instructions here)

Your first extension

If you know your way around the command line, follow along as we create a simple extension that just displays events received. (On windows replace calls to nano with notepad or whatever editor you are comfortable with)

Make a folder, start an npm project

mkdir my-extension
cd my-extension
npm init

Hit Return 10 times. Yup. That'll do! This will create a package.json file which we'll use to add our dependencies.

npm install r1-ext-client

This will download and install the R1 Web Extension library in the node_modules folder.

Fling some HTML

With this out of the way, let's add a simple HTML file and some basic JavaScript to finish our extension!

mkdir public
cd public
nano index.html

Copy&Paste this starter template and save the file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Extension</title>
  <script src="../node_modules/r1-ext-client/dist/r1-extension.js"></script>
</head>
<body>
<pre id="status">Registering Extension...</pre>
<script>
let origin = "https://my-replyone.com"; // the origin [scheme + host + port] of the ReplyOne system you plan to integrate with
let api = r1Ext.register(origin,
            { processingStart: (msg, api) => { 
                document.getElementById("status").textContent = JSON.stringify(msg, null, 2)
            }});
document.getElementById("status").textContent = "Extension loaded"
</script>
</body>
</html>

You are done!

This extension won't do much, but all parts of the puzzle are there:

let origin = "https://my-replyone.com";

This is an important security feature. Make sure origin is set to the origin (i.e. scheme + host + port) of your ReplyOne installation.

Behind the scenes, the r1-ext-client library uses window.parent.postMessage to communicate with ReplyOne. Read the security section for more information.

let api = r1Ext.register(origin,
            { processingStart: (msg, api) => { 
                document.getElementById("status").textContent = JSON.stringify(msg, null, 2)
            }});

This will register the Extension to the ReplyOne counterpart of the Extension API. This also subscribes this Extension to any processingStart event. (See the API documentation for available subscriptions.)

Whenever a document is being processed by the current user, a processingStart message is sent to the extension, which leads to the <pre> tag being updated with the JSON data sent by ReplyOne.

Use the api object to ask for additional information or update information. Requests like that usually return a Promise object, so asking information about the current user could look like this:

api.getUserInfo().then(userInfo => {
    console.log(userInfo);
})

Add the Extension to ReplyOne

In order to use the Extension from ReplyOne, it needs to be hosted on a web server. It is up to the Extension to set up the necessary environment. We prefer using https for all Extensions.

For development purposes, the quickest way to an HTTP server is this:

python -m SimpleHTTPServer

that is: if you have python installed. Some IDEs also come with their built-in web service.

No matter how, but at the end, we need an URL to your Extension to add to ReplyOne.

Go to the Configuration section of the ReplyOne Administration screen, find the Webx plugin and add the URL to an Extension Point. Extension Points also indicate on which part of the UI your Extension is being embedded.

And that's it!

Build all the Extensions!

Notes

This is a preview alpha version of the Extension API, use at your own risk!

The nature of the communication between the ReplyOne UI and an Extension is asynchronous. When an Extension is loaded, it is expected to load quickly and register to ReplyOne whenever it is ready to receive events.

For some lifecycle events, like processingStart, the Extension might load too slow. In that case, the event is being kept und sent out when the Extension finally registers.

Regardless, the Extension should not rely on all the events being received all the time. It also needs to cope with replies not being received at all, i.e. Promise.then might not be called. Later versions of this API will support a timeout mechanism to at least call Promise.catch if the ReplyOne UI is not responding anymore.

Plans

We want to provide a simple simulator to test your Extension, so you don't need access to a ReplyOne system.

We also want to add more Extension Points to the ReplyOne portfolio of UIs.

Debugging

To see all messages being sent to your Extension, add this to your code:

window.addEventListener("message", evt => console.log(evt));

To see all messages being sent from your Extension, add a third parameter to register with {debug:true}, i.e.

r1Ext.register(origin, subscriptions, {debug:true});

Typescript

If you like to use Typescript to develop your front-end code, the npm package comes with the Typescript sources in ../node_modules/r1-ext-client/src.

Developing r1-ext-client

This section is for developers who would like to contribute to this tiny library.

Build

npm run build

Two artifacts are generated in dist: dist/index.es.js to use with CommonJS module loaders as well as dist/r1-extension.js which is a UMD module, i.e. you can load it with a simple <script> tag. In that case, a new global symbol r1Ext is available

Run tests

npm run test

Build interactively

npm run watch

Documentation

npm run docs

Documentation is available in /docs