Home Original page

JavaScript ES Module | Parallel Developer Documentation

If you're not able to use our React Module, you can load the Parallel SDK directly either via a <script> element or via our ES Module.

Three Minute Setup

If you're looking for the fastest way to test things out, check out our Example ES Module Site.

Manually load the parallel.js script​

This example uses the most basic <script> integration method for an HTML page with limited JavaScript, but we also provide NPM modules (see below).

Copy the following code into the <body> of your website where you want the button to appear. You'll want to call the Parallel.init() function with your configuration options.

<!-- a space for messaging -->
<div id="message"></div>

<!-- any element with this class will get a button -->
<div class="parallel-login-button"></div>

<script src="https://app.parallelmarkets.com/sdk/v2/parallel.js"></script>
<script>
  // Initialize the Parallel SDK with config options.  This example uses our "demo" sandbox.
  Parallel.init({ client_id: 'your_client_id', environment: 'demo', flow_type: 'overlay' })

  // on success - user agreed to share status
  function success(result) {
    document.getElementById('message').innerHTML = 'Thanks for sharing your info.'
    // You could also call Parallel.getProfile() to get the Parallel ID for the subject
    // that just completed a flow - see the example below for more details
  }

  function failure(result) {
    var msg = document.getElementById('message')
    if (result.status == 'not_authorized') {
      // the user denied access to their information
      msg.innerHTML = 'Please consent to access to complete your onboarding.'
    } else {
      // there was an issue in the configuration / flow initiation process
      console.error(result)
      msg.innerHTML = 'Looks like there was an issue.'
    }
  }

  Parallel.subscribeWithButton(success, failure)
</script>

After calling Parallel.init, you just need to call Parallel.subscribeWithButton with two functions:

  1. A function to be called on successful login and consent to sharing the details requested.
  2. A function to be called if the user does not consent to sharing their details.

This call to Parallel.subscribeWithButton will also handle showing the Parallel Passport button (in any div with the class parallel-login-button) and then hiding it when the user authenticates.

info

To best leverage Parallel's fraud detection, include the script on every page, not just the page where you would like a user to go through the Parallel flow(s). This allows Parallel to detect suspicious behavior that may be indicative of fraud as users interact with your website.

Load parallel.js as an ES Module​

You can also import the loader as an ES Module and load the SDK asynchronously.

Installation​

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

npm install --save @parallelmarkets/vanilla

Usage​

The loadParallel function returns a promise that resolves once the SDK is loaded and ready. See below for an example using the async/await syntax in vanilla JavaScript.

import { loadParallel } from '@parallelmarkets/vanilla'

// load the parallel library with the given configuration information
const parallel = await loadParallel({ client_id: '123', environment: 'demo' })

// any element with the "parallel-login-button" class will render a button
parallel.showButton()

// at this point, all of the SDK functions can be called - i.e.,
// parallel.login(), parallel.subscribe(), etc.

See the package page for more information and examples.

Initiating a Parallel Flow​

After the Parallel SDK has been initialized (either via Parallel.init() if manually loaded, or via loadParallel() via the ES Module), you can show a Parallel button or explicitly initiate a flow.

To automatically load a Parallel Passport button on your page, just follow these steps:

  1. Add the HTML class parallel-login-button to the parent element where you want the button to appear.
  2. Call showButton(), which will then find any elements with that class and render a login button child element for each.

For instance, to add a "Parallel Passport" button somewhere on your page:

  • ES Module
  • Manual Loading
<div class="parallel-login-button"></div>
import { loadParallel } from '@parallelmarkets/vanilla'

// wait for the loading to finish before calling any functions
const parallel = await loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })

parallel.showButton()

Alternatively, you can provide your own button or link and call Parallel.login() when you're ready to send the user into an authentication flow. For instance:

  • ES Module
  • Manual Loading
<a href="#" onClick="showParallelFlow()"> Log in with Parallel </a>
import { loadParallel } from '@parallelmarkets/vanilla'

// wait for the loading to finish before calling any functions
const parallel = await loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })

const showParallelFlow = () => {
  parallel.login()
}

Upon completion, the user will be on the same page on your site where the authentication flow was initiated regardless of flow_type. This must be the same URL as the redirect_uri you provided when your account was first set up. This URL must match only for the initial authentication process. After that, you can call the getLoginStatus() and getProfile() functions on any page in your domain that has the Parallel JavaScript SDK loaded.

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 JS SDK fires an auth.login event, 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 after initializing the vanilla ES Module.

import { loadParallel } from '@parallelmarkets/vanilla'

const parallel = await loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })

parallel.showButton()

parallel.subscribe('auth.login', () => {
  // 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.

  parallel.getProfile((response) => {
    // 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.

    // 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',
      },
    })
  })
})