PLuG integration

PLuG widget installation#

Before getting started, you need access to your code base and understanding of your code base sufficient to know where to place the PLuG widget code. You also need access to the Support settings page in the DevRev app.

Tokens#

The app token uniquely identifies your organization. It is sensitive and should not be exposed outside your organization. You can find your app token from the Settings page in the DevRev app.

A rev token is a session token which identifies the rev user when they interact with the widget. The widget allows them to see previous conversations and tickets in the PLuG widget and allows you to identify them in the PLuG Inbox.

The rev token is generated using the app token and rev user information. It should be generated on your backend since the app token needs to be kept hidden.

Front-end installation: Integrating in your app#

To initialize the PLuG widget, copy and paste the following code into your application before the closing body tag. Ideally, this will be in a common file which is already included in all pages (such as index.js).

const sessionToken = '<SESSION_TOKEN>'
<script src="https://plug.devrev.ai/{YOUR_ORG_NAME}/widget.js"></script>
<script>
  window.addEventListener('load', function () {
    const widget = new window.Plug({
        auth: {
            sessionToken: sessionToken
        }
     });
  });
</script>

If the PLuG widget is flickering, the app token is invalid or expired. You can check whether the token is valid at jwt.io.

Back-end installation: Generating the session token#

The example below shows how you could use DevRev's token API to get a session token for a rev user by using your dev org's app token.

Note: For security reasons, this call must be made from the server side so that the dev org's app token is not exposed.

This sample code is in JavaScript.

// The user info object for whom you are obtaining a session token for logging into the plug widget.
var rev_info = {
  user_ref: '123456789', // [Required] Unique identifier for the user in your platform. Must strictly be of type 'string'.
  org_ref: 'org-123', // [Optional] Unique identifier of the organization the user belongs to. Can be any string.
  // [Optional] Additional user attributes for the user specified in `user_ref`
  user_traits: {
    email: 'user@example.org',
    display_name: 'user',
    full_name: 'User Name',
  },
  // [Optional] Additional org attributes for the organization specified in `org_ref`
  org_traits: {
    display_name: 'example', // Display name of the customer organization.
    domain: 'example.com', // Domain of the customer organization. During email support the `domain` helps resolving customer email address to this organization.
  },
};

export async function getSessionTokenForRevUser(rev_info) {
  // Token endpoint to call for obtaining session token.
  const url = 'https://api.devrev.ai/auth-tokens.create';
  // Your Org's Application token which is required for provisioning a RevUser.
  const appToken = '<DEVORG_APP_TOKEN>';

  const headers = {
    Authorization: appToken,
  };

  const response = await axios.post(
    url,
    {
      rev_info,
    },
    { headers },
  );
  const sessionToken = response.data['access_token'];
  return sessionToken;
}

PLuG widget configuration#

You can configure various style properties and callbacks while initializing the widget. Please refer to the table below for more details.

Configuration options#

Auth

Configuration optionTypeRequiredDefault valueDescription
sessionTokenstringYesnullSession token of the Rev user

Style

Configuration optionTypeRequiredDefault valueDescription
alignmentstringNoleftChoose the side of the screen you want the widget to show on. Possible values: left/ right
horizontalOffsetstringNo1.5remSpecify the horizontal distance from the left/right corner of the screen. All CSS units are accepted.
verticalOffsetstringNo1.5remSpecify the vertical distance from the bottom of the screen. All CSS units are accepted.
hideFloatingToggleButtonbooleanNofalseHide the default floating toggle button (DevRev logo).
This can be used to create a custom trigger which uses the open/close methods directly.
themestringNosystemChoose the theme of the widget. Possible values: light dark
logo stringNoCustomize the display logo of the widget. A 20x20 image is preferred.

Configuring the PLuG widget#

const config = {
  auth: {
    sessionToken: '<REV_SESSION_TOKEN>',
  },
  style: {
    alignment: 'right',
    hideFloatingToggleButton: false,
    horizontalOffset: '20px',
    verticalOffset: '20px',
    theme: 'dark',
    logo: 'https://app.devrev.ai/static/profile-circle-black.png',
  },
};

const callbacks = {
  onReady: () => {
    console.log('widget is ready!');
  },
  onOpen: () => {
    console.log('widget opened');
  },
  onClose: () => {
    console.log('widget closed');
  },
};
const widget = new window.Plug(config, callbacks);

Interface#

interface DevRevSDKConfig {
  auth: {
    sessionToken: string;
  };
  style?: {
    hideFloatingToggleButton?: boolean;
    alignment?: 'left' | 'right';
    horizontalOffset?: string;
    verticalOffset?: string;
  };
}

interface DevRevSDKCallbacks {
  onReady?(): void;
  onOpen?(): void;
  onClose?(): void;
}

PLuG JavaScript API#

The PLuG widget exposes methods and callbacks which can be used to customize the widget behavior further.

For example, if you want a custom button, you can set hideFloatingToggleButton to true along with appropriate offset values, And then have your own button in your website call widget.open() and widget.close() methods directly.

Attributes

AttributeTypeReturn value
isReadybooleantrue if all the widget JavaScript files have been downloaded and the widget has been initialized successfully.

Methods

MethodTypeReturn valueDescription
open()booleantrue if widget was opened, false if widget was not readyOpen the widget
close()booleantrue if widget was closed, false if widget was not readyClose the widget
destroy()voidN/ACompletely removes the widget
reInitialize(config: DevRevSDKConfig, callbacks?: DevRevSDKCallbacks)voidReinitialize the widget with new config and callbacks

Callbacks

EventCallback
The widget is readyonReady(callback: () => void)
The widget is openedonOpen(callback: () => void)
The widget is closedonClose(callback: () => void)

Note: A callback passed during initialization will be overwritten if the same callback is redefined using the above method

Full-screen widget#

If you want the PLuG widget to be in full-screen mode, set the page background color to #202020 and add the following code after widget.open().

document.querySelector('iframe').style.maxHeight = null;
document.querySelector('iframe').style.maxWidth = null;
document.querySelector('iframe').style.width = '100vw';
document.querySelector('iframe').style.height = '100vh';