Show Developer Menu

Introduction

Custom Module

The Custom Module setting allows you to embed your own UI into the Re:amaze conversation admin. When a conversation is displayed in Re:amaze, your custom module will be invoked.

It works via an iframe to a URL that you can specify, which can serve up any web content desired. Re:amaze will provide contextual data to the specified URL so that you can display contextually sensitive data and actions.

Enabling the custom module is done via Settings and the only thing you need to provide is the iframe URL.

Module

Iframe Parameters

Contextual data is provided via URL query string parameters. Some parameters are guaranteed to be present, while others are optional and based on availability depending on data known about the customer.

Guaranteed Parameters

  • brand — The subdomain of the brand for this conversation.
  • staff — The email identifying the staff user currently viewing this module.
  • timestamp — The current epoch timestamp. For verification purposes.
  • hmac — A generated signature for this request. For verification purposes.

Contextually Available Parameters

  • id — The ID of the customer as previously provided through SSO.
  • email — The email identifying the customer for an email, form, or widget based conversation.
  • facebook — The Facebook ID identifying the customer for a Facebook channel conversation.
  • twitter — The Twitter username identifying the customer for a Twitter channel conversation.
  • slug — The unique identifier for the conversation in Reamaze. Fetchable using Conversation API.

Signature Verification

To authenticate the request as a genuine Re:amaze request, you should verify the provided hmac query parameter value.

The value is a SHA256 HMAC hexdigest computed using the query parameter as the message and your account SSO Secret (available under Account IDs and Secret from within your Account Settings) as the key.

The query parameters should be lexicographically sorted by the query parameter key and then serialized as a string. The hmac parameter should be removed for the computation. (e.g. brand=value&email=user@example.com&id=123&staff=staff@example.com&timestamp=1434876834)

As Re:amaze may introduce more parameters in the future, it is required that the signature is computed using all query parameters rather than a select list of parameters.

Iframe resizing

Because the module is loaded as a iframe, you will need to provide Re:amaze with the content height dynamically. This is done via Cross-Origin Communication.

Re:amaze expects the contents of postMesage call to be formatted as the following example.

<script type="text/javascript">
  window.onload = function() {
    window.parent.postMessage({
      message: 'reamaze:resize',
      height: document.body.scrollHeight
    }, "*");
  };
</script>

As Re:amaze may alter the placement of the custom module and also display the custom module differently depending on device, it is advised that the content is developed to be responsive to screen size.