Integrating Sentinel in web applications

This guide covers how to add the Persona Sentinel iframe to your webpage.

Setup

Ask your Persona Account team to set up a Sentinel transaction type and a client token before you start. You need both values to build the collection URL below.

Instructions

Recommended usage and sample implementation

Embed the Sentinel URL in an iframe, and only load the iframe and send the Transaction as needed.

import React, { useState, useRef, useMemo, useEffect } from 'https://esm.sh/react@18'
import ReactDOM from 'https://esm.sh/react-dom@18'

function SentinelContainer() {
  const [iframeLoaded, setIframeLoaded] = useState(false)
  const [sentinelCollecting, setSentinelCollecting] = useState(false)
  // To store the callback result from Sentinel
  const [postResult, setPostResult] = useState(null)
  const iframeRef = useRef(null)
  const buttonRef = useRef(null)
  const memoizedIframe = useMemo(
    () => (
      <iframe
        style={{ display: 'none' }}
        ref={iframeRef}
        id="sentinel"
        src="https://withpersona.com/sentinel?client-token={CLIENT_TOKEN}&transaction-type-id={TXN_TYPE_ID}&context=referenceImplementation&account-reference-id={REFERENCE_ID}"
      />
    ),
    []
  )

  const handleIframeLoad = () => {
    setIframeLoaded(true)
  }

  const handleMessage = (message) => {
    if (message.origin === 'https://withpersona.com') {
      setPostResult(message.data)
      setSentinelCollecting(false)
    }
  }

  useEffect(() => {
    // Add a message event listener to your application to handle postMessage callbacks
    window.addEventListener('message', handleMessage)
    const iframeElement = iframeRef.current
    if (iframeElement) {
      // Add a load event listener to the iframe to detect when it has finished loading
      iframeElement.addEventListener('load', handleIframeLoad)
    }
    // Return value is used to provide a cleanup function for React's useEffect
    return () => {
      window.removeEventListener('message', handleMessage)
      if (iframeElement) {
        iframeElement.removeEventListener('load', handleIframeLoad)
      }
    }
  }, [])

  const handleClick = () => {
    if (iframeRef.current && iframeRef.current.contentWindow) {
      setSentinelCollecting(true)
      // Post a message to the Sentinel iframe to begin collection
      iframeRef.current.contentWindow.postMessage(
        // The origin refers to the domain in which the iframe is being embedded
        { type: 'persona/passive/collect', origin: 'https://mywebpage.com' },
        // The second parameter is the target origin, this should be https://withpersona.com
        // (or the domain matching the Sentinel endpoint being used for the iframe)
        'https://withpersona.com/'
      )
    }
  }

  useEffect(() => {
    // Add a click event listener to the button that starts collection
    const buttonElement = buttonRef.current
    if (buttonElement) buttonElement.addEventListener('click', handleClick)
    return () => {
      if (buttonElement) buttonElement.removeEventListener('click', handleClick)
    }
  }, [])

  return (
    <>
      {memoizedIframe}
      <h1>Hello World</h1>
      <p>Iframe loaded: {iframeLoaded.toString()}</p>
      <p>Sentinel result: {sentinelCollecting ? 'Loading...' : ''}</p>
      <pre>{postResult ? JSON.stringify(postResult, null, 2) : 'No data available'}</pre>
      <button ref={buttonRef} disabled={!iframeLoaded || sentinelCollecting}>
        Click Me
      </button>
    </>
  )
}

// Tells React to attach the SentinelContainer component to the 'root' HTML div
const root = ReactDOM.createRoot(document.getElementById('root'))
root.render(<SentinelContainer />)

Other parameters

Routing country

For end users and customers on the DE shard, taking advantage of geographical routing may be desired to reduce client-facing latencies. Since the /sentinel endpoint is fetched via a GET request when loaded via an iframe, you can specify an additional query string parameter:

https://withpersona.com/sentinel?client-token={{CLIENT_TOKEN}}&transaction-type-id={{TXN_TYPE_ID}}&routing-country=US

You can specify either US or DE for the routing-country query string parameter. Subsequent API calls made to Persona are routed accordingly.