Embedding Anvil UIs in React with AnvilEmbedFrame

Anvil supports embedding several of our UIs in your app or website. Capture data from your users by embedding a Workflow's webforms, let your users sign documents by embedding the e-sign UI, and allow your users to build PDF templates, e-sign packets, and Workflows by embedding our builder UIs.

We've just released an AnvilEmbedFrame React component to make embedding easier. AnvilEmbedFrame works with all of our embeddable UIs. It will embed the Anvil page of your choice in an iframe, then emit events when the user has performed actions such as finishing a webform, signing, etc.

Usage

First install the component:

yarn add @anvilco/anvil-embed-frame
# OR
npm install @anvilco/anvil-embed-frame

Then add it to your app:

import AnvilEmbedFrame from '@anvilco/anvil-embed-frame'

const MyEmbeddedAnvilComponent = () => {
  const url = theURLYouWantToEmbed
  return (
    <AnvilEmbedFrame
      iframeURL={url}
      onEvent={(event) => console.log('Event object:', event)}
      className="anvil-embed-frame"
    />
  )
}

Easy!

Handling events

Each embedded UI will emit events through the component's onEvent callback. All events emitted will be an object with a similar shape: an action attribute, then IDs and other information to help you determine on which object the event happened. The action strings and IDs in the event will vary with the UI you have embedded. See the embedding section of the docs on the product of your choice for event details, e.g. Embedded Workflow docs and embedded e-sign docs.

Here's an example of an event when a signer finishes signing:

{
  action: 'signerComplete',
  signerStatus: 'completed',
  signerEid: 'Jc1ZJisPnpF5lHyfyqBW',
  nextSignerEid: 'WBqyfyHl5FpnPsiJZ1cJ',
  documentGroupStatus: 'partial',
  documentGroupEid: 'nEKq2eGim0ijSqKd98nG',
  etchPacketEid: 'XzfmVPfGUEyBc1XyylFo',
}

Error events share a similar shape with an action attribute plus other attributes to give you error context:

{
  action: 'embeddedError',
  errorType: "tokenExpired",
  error: "Token Expired",
  message: "This token has expired",
  requestTokenEid: "YFizcDAV4XH09UCkQ4LI",
}

Upgrading from ReactSignatureFrame

AnvilEmbedFrame is intended to replace our existing ReactSignatureFrame component. ReactSignatureFrame only allows embedding our e-sign UIs while AnvilEmbedFrame works with all of our embeddable UIs.

Upgrading is straightforward: change the name of the signURL prop to iframeURL, and use the onEvent callback handler.

Before:

import AnvilSignatureFrame from '@anvilco/react-signature-frame'
<AnvilSignatureFrame
  signURL={signURL}
  onFinishSigning={(payload) => console.log(payload)}
  onError={(errorPayload) => console.log(errorPayload)}
/>

After:

import AnvilEmbedFrame from '@anvilco/anvil-embed-frame'
<AnvilEmbedFrame
  iframeURL={signURL}
  onEvent={(event) => {
    if (event.errorType) {
      console.log('Error', event)
    } else {
      console.log('Success', event)
    }
  }}
/>

Questions?

If you have any questions or run into any issues, don't hesitate to reach out to support@useanvil.com.