Parallel Developer Documentation Legacy – v1.x

This is documentation for Parallel Developer Documentation Legacy – v1.x, which is no longer actively maintained.

For up-to-date documentation, see the latest version (Current – v2.x).

Version: Legacy – v1.x

On this page

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}</h2>

{/* 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 OAuth Access Tokens

If you're using the JS SDK, you do not need to worry about calling any APIs to fetch authentication tokens. The entire process for securely retrieving the OAuth access_token and refresh_token payload is entirely handled for you automatically (for all three of the flow_types whether you're using the default overlay, embed, or redirect option).

The result of any successful authentication event will include an authResponse field that contains the full OAuth Token API response which contains the access_token and refresh_token.

Here's an example of a few lines you can add to the example above if you want to do something with the resulting OAuth tokens (like send them to your backend so you can make ongoing Accreditation / Identity API calls over time from your servers).

const TokenSaver = () => {

const { loginStatus } = useParallel()

useEffect(() => {

if (loginStatus?.status !== 'connected') return

// The loginStatus.authResponse.access_token and loginStatus.authResponse.refresh_token
    // values could now be sent to your server if you want to make ongoing API calls from
    // your server environment. For example:

const body = JSON.stringify(loginStatus.authResponse)

fetch('/save-tokens', { method: 'POST', body: body })

}, [])

// 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

// pull the tokens out of the auth response and then show them in the interface (just as an
  // exercise in debugging / demoing what the tokens look like

const { access_token, refresh_token, expires_in, refresh_expires_in } = loginStatus.authResponse

return (

<p>

The access token {access_token} expires in {expires_in} seconds.

<br />

The refresh token {refresh_token} expires in {refresh_expires_in} seconds.

</p>

)

}