React Integration

If you're using React, you can use our React hooks library to make integration quick and easy.

Three Minute Setup

If you're looking for the fastest way to test things out, check out our Example React App.

Setup

Install the Parallel React library and the vanilla loader from the npm public registry.

npm install --save @parallelmarkets/react @parallelmarkets/vanilla

ParallelProvider

The ParallelProvider allows you to use our hooks and access the Parallel object in any nested component. Render a ParallelProvider at the root of your React app so that it is available everywhere you need it.

To use the ParallelProvider, call loadParallel from @parallelmarkets/vanilla with your configuration options. The loadParallel function asynchronously loads the parallel.js script and initializes a Parallel object. Pass the returned Promise to ParallelProvider.

import { loadParallel } from '@parallelmarkets/vanilla'
import { ParallelProvider } from '@parallelmarkets/react'

// Start loading the parallel library with the given configuration information. Make sure
// you call this outside of a component's render to avoid recreating a `Parallel` object
// on every render. Also - you should not "await" the resulting promise, just pass directly
// to the ParallelProvider in the "parallel" property
const parallel = loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })

const App = () => (
  <ParallelProvider parallel={parallel}>
    <YourRootComponent />
  </ParallelProvider>
)

const app = document.getElementById('main')
const root = createRoot(app)
root.render(<App />)

info

To best leverage Parallel's fraud detection, include the call to loadParallel across your app/site. This allows Parallel to detect suspicious behavior that may be indicative of fraud as users interact with your website.

Initiating a Parallel Flow

This is a more complete example, showing use of the useParallel hook in a child component. Additionally, this example shows use of the PassportButton component, that, when clicked, initiates a Parallel flow. You can simply call parallel.login() as an alternative to showing the PassportButton component.

import React
import { loadParallel } from '@parallelmarkets/vanilla'
import { ParallelProvider, useParallel, PassportButton } from '@parallelmarkets/react'

const AccreditationArea = () => {
  // the parallel variable provides access to the full SDK
  const { parallel, loginStatus } = useParallel()

  // we may render before the loginStatus is available
  if (!loginStatus) return null

  return (
    <>
      <h1>Status: {loginStatus.status}</h1>
      {/* Only show the login button if the user hasn't logged in yet */}
      {loginStatus.status !== 'connected' ? (
        <PassportButton />
      ) : (
        <button onClick={parallel.logout}>Log Out</button>
      )}
    </>
  )
}

// start loading the parallel library with the given configuration information
const parallel = loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })

const App = () => (
  <ParallelProvider parallel={parallel}>
    <AccreditationArea />
  </ParallelProvider>
)

const app = document.getElementById('main')
const root = createRoot(app)
root.render(<App />)

Getting the Parallel ID

The result of any successful authentication event will include an authResponse field that indicates the status of the handoff. Once the status is connected, you can call the getProfile() function to get the Parallel ID for the user or business that completed the flow (along with other profile information). That ID should be saved to your backend along with your internal ID for the current session so your server can make ongoing calls to get/update information for the user/business.

Here's an implementation that demonstrates persisting the Parallel ID to an example backend endpoint.

const ParallelIDSaver = () => {
  const { loginStatus, getProfile } = useParallel()

  useEffect(() => {
    if (loginStatus?.status !== 'connected') return
    // Once the JS SDK reports that the user's session is connected, you should fetch and save
    // the resulting Parallel ID to your backend. That will allow you to make ongoing API calls
    // to react to webhooks and fetch or update information about this individual/business.

    // This example demonstrates POST-ing the returned profile information for the individual/business
    // alongside your internal ID for the browser session. This permanently associates your internal ID
    // and Parallel ID to the same entity.
    getProfile().then((response) => {
      // This example assumes that your backend exposes a /save-parallel-id endpoint to accept JSON
      // to persist an internal session ID alongside the Parallel profile data.
      fetch('/save-parallel-id', {
        // Here, your implementation of getInvestorId() would return your internal, unique ID for the individual or business.
        body: JSON.stringify({
          parallelId: response['profile']['id'],
          internalId: getInvestorId(),
        }),
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
      })
    })
  }, [loginStatus, getProfile])

  // if the user hasn't connected yet or the library isn't yet loaded, we can't
  // show anything yet
  if (loginStatus?.status !== 'connected') return null

  return <p>Thanks for providing your information!</p>
}