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()orshowButton()
Once that experience is initiated, users are directed through a few steps:
- The user will be asked to log in or create an account if they are not already logged in to Parallel Markets.
- The user will be asked to consent to share information (if they have not previously provided consent) with you.
- 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_statusscope and a user does not have an active accreditation, they will be asked to complete an accreditation flow. - 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(() => {
// library hasn't loaded yet
if (!parallel) return
parallel.subscribe('auth.statusChange', setStatus)
// cleanup on unmount
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
}
info
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 (the experience on mobile, for instance), 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 | Description |
|---|---|
auth.login | Fires after a user authenticates (after a call to Parallel.login()) and completes all steps in the Parallel experience |
auth.logout | Fires after a user is logged out via a call to Parallel.logout() |
auth.statusChange | Fires when the user's authentication status changes after the full completion of the flow in a Parallel experience or when the user is logged out |
auth.authResponseChange | Fires when the authResponse object has changed, which indicates that the user's access token has changed in some way. See Event Callback Argument for more information. |
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:
| Property | Description |
|---|---|
| status | This will be one of:
|
| error | An error code (if an error occurred) - see this list for possible codes |
| errorDescription | An error description (if an error occurred) |
| authResponse | If a user has authenticated and consented to sharing the requested data, this will contain an access_token and refresh_token. If you'd like to make ongoing API calls from your server environment, you can now call getProfile() to get the Parallel ID for the subject (individual or business) that completed the flow. |
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: