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

Subscribing to Events

The Parallel experience can be initiated in two ways:

• Via a call to login() directly
• A Parallel button click on a button shown after a call to subscribeWithButton() or showButton()

Once that experience is initiated, users are directed through a few steps:

1. The user will be asked to log in or create an account if they are not already logged in to Parallel Markets.
2. The user will be asked to consent to share information (if they have not previously provided consent) with you.
3. The user will be asked to provide information to fulfill any scopes you requested (if they haven't provided the information before). For instance, if you request the accreditation_status scope and a user does not have an active accreditation, they will be asked to complete an accreditation flow.
4. The user will complete the experience and the overlay will disappear (or the user will be redirected back to your site).

After these steps are completed, a few different events are fired by the SDK to provide you with the results of the user flow. You can subscribe to these events to know when a user has completed the steps.

For instance, to execute code whenever a user completes or cancels a flow:

• React Module
• ES Module
• Manual Loading

AuthStatusChangeMessage is a complete example component that subscribes to events and handles unsubscribing on unmount. SimplerAuthStatusChangeMessage demonstrates a simplification by pulling the loginStatus out of the useParallel() hook.

import { useParallel } from '@parallelmarkets/react'
const AuthStatusChangeMessage = () => {
  const { parallel } = useParallel()
  const [status, setStatus] = useState(null)
  useEffect(() => {
    if (!parallel) return
    parallel.subscribe('auth.statusChange', setStatus)
    return () => {
      parallel.unsubscribe('auth.statusChange', setStatus)
    }
  }, [parallel])
  return status ? <p>Status changed to: {status.status}</p> : null
}
// simpler version of the above using the hook's existing subscription to auth status changes
const SimplerAuthStatusChangeMessage = () => {
  const { loginStatus } = useParallel()
  return loginStatus ? <p>Status changed to: {loginStatus.status}</p> : null
}

// wait for the loading to finish before calling any functions
const parallel = await loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })
parallel.subscribe('auth.statusChange', function (result) {
  if (result.status === 'connected') {
    // the user is logged in and you can call the API now
  } else if (result.status === 'not_authorized') {
    // the user canceled authentication or failed
    // to consent to sharing with your site
  } else {
    // the user authentication is unknown (i.e., the user
    // is not logged in) - so show the login button
    parallel.showButton()
  }
})

Parallel.subscribe('auth.statusChange', function (result) {
  if (result.status === 'connected') {
    // the user is logged in and you can call the API now
  } else if (result.status === 'not_authorized') {
    // the user canceled authentication or failed
    // to consent to sharing with your site
  } else {
    // the user authentication is unknown (i.e., the user
    // is not logged in) - so show the login button
    Parallel.showButton()
  }
})

The only way to know when users have successfully authorized sharing their data with your site is to subscribe to an auth event (or use the loginStatus from the useParallel React hook). This is because a user may have authorized via a redirect flow, which fires an auth.login and an auth.statusChange event. Also note that authentication "status" refers to the user's status from the perspective of your site, not their authentication status on parallelmarkets.com or within the experience in the iframe that is embedded or shown in an overlay.

Auth Events

The following events can be tracked using Parallel.subscribe():

List of Events

Event Callback Arguments

When events are triggered, the callback function will be called with a single argument with details about the event. The argument will be an object with the following properties:

For instance, here's a successful authentication / consent granted object:

{
  status: "connected",
  authResponse: {
    access_token: "MVXoULzTSdmDINFf",
    token_type: "bearer",
    expires_in: 86400,
    refresh_token: "dmDINFfULzTSdMVXoU",
    refresh_expires_in: 345600
  }
}

And here's an example where a user declined consent:

{
  status: 'not_authorized'
}

And here's an example object when the user is not currently logged in:

{
  status: 'unknown'
}

Handoff Events

List of Events

Event Callback Arguments