Skip to main content

Integrate Blockpass widget on primary website

Incorporate this widget into your public website on the page you want individuals to start the KYC process with Blockpass.

The widget displays an iframe that individual users can use to upload their Identity and register with your service.

tip

You can test the widget from the Service detail page on the Admin Console.

Get the Blockpass Widget​

Select the service you want from the Services List to open the service details. From the menu of service options (•••) above the service details tabs, select "Widget integration"

A popup will show an example of integration of the Widget code for the selected Service

Adapt the code into your public website's html page

Usage​

(1) Load the script in the <header> section of your html

<script src="https://cdn.blockpass.org/widget/scripts/release/3.0.2/blockpass-kyc-connect.prod.js"></script>

(2) Add the Blockpass KYC Connect button and the javascript below in the location of your choice in the <body> of your html

<button id="blockpass-kyc-connect">Connect with Blockpass</button>
<script>
  const blockpass = new BlockpassKYCConnect("YOUR_CLIENT_ID");
  // `client_id` of your service
  // To get from the Blockpass Admin Console

  blockpass.startKYCConnect();
</script>

The button is not styled by default, you can apply your own branding and label.
You can also apply id="blockpass-kyc-connect" to a <div> or <a> tag

Optional parameters​

<button id="blockpass-kyc-connect">Connect with Blockpass</button>
<script>
  const blockpass = new BlockpassKYCConnect( 'YOUR_CLIENT_ID',
    {
      refId: 'xxx-yyy-zzz' // optional
      elementId: 'dom_id_of_your_choice' // optional. Specify a different ID for the button (default: blockpass-kyc-connect)
      mainColor: '800080' // optional. Html color code or hex code without the #
      email: '[email protected]' // optional. Prefill the email address of the user to onboard
    })

  blockpass.startKYCConnect()
</script>

refId (string)​

If your users are authentified on your platform when they register Blockpass, you can assign their identifier to this parameter.

Example:

  • Alice login on your platform, her identifier is xxx-yyy-zzz
  • Assign xxx-yyy-zzz to the refId parameter of the widget
  • xxx-yyy-zzz will be imported in the KYC Connect Dashboard and you can use this identifier to get Alice's KYC status with our APIs.
caution

This value must be unique for each user. The widget will throw an error if the same refId is used for different accounts

refId format

Accepted characters:

  • letters lowercase or uppercase
  • numbers 0 to 9
  • -, _, ., +, @
  • maximum 200 characters

regex: /^[a-zA-Z0-9-_.+@]{1,200}$/

Example of valid strings:
28bdf5e7-2d6f-42d3-89dd-5046c87ffe6b, 0x9e2df3677620f7a7b74710e998172f3f9537b0e1, [email protected], ...

See also how to define who can register with your service

elementId (string)​

You can customize the id of the button to launch the widget by specifying the elementId parameter.
Useful if you have several Blockpass buttons on the same page.

mainColor (string)​

Customize the background color of the widget to match your branding. Buttons, links, background color will use the color code provided here. You can use html color codes (Red, DarkSlateGrey, ...) or the hex value without the # (006400, B22222, ...)

If you pick a color too light, it will be auto-darken to make sure the texts are readable.

email (string)​

If you know the email address of the user being onboarding, you can add it as parameter. The email field will be autofilled with this value.

Advanced usage​

You can automatically trigger the execution of your custom code based on event notifications that the widget will send.
Example: auto-redirect to a different url when KYC data have been sent.

The widget currently supports the following events:

Event: Data submitted successfully to the KYC Connect service​

<button id="blockpass-kyc-connect">Verify with Blockpass</button>
<script>
  const blockpass = new BlockpassKYCConnect("YOUR_CLIENT_ID");
  blockpass.startKYCConnect();

  blockpass.on("KYCConnectSuccess", () => {
    //add code that will trigger when data have been sent. ex:
    //alert('Success!')
  });
</script>

This event is triggered immediately after user's data have been sent successfully to the KYC Connect service.

Event: Registration workflow is successfully terminated​

<button id="blockpass-kyc-connect">Verify with Blockpass</button>
<script>
  const blockpass = new BlockpassKYCConnect("YOUR_CLIENT_ID");
  blockpass.startKYCConnect();

  blockpass.on("KYCConnectClose", () => {
    //add code that will trigger when the workflow is finished. ex:
    //alert('Finished!')
  });
</script>

This event is triggered when the widget popup is closed (manually by the user or automatically by code).

Event: User aborted the workflow before data were sent to the KYC Connect service​

<button id="blockpass-kyc-connect">Verify with Blockpass</button>
<script>
  const blockpass = new BlockpassKYCConnect("YOUR_CLIENT_ID");
  blockpass.startKYCConnect();

  blockpass.on("KYCConnectCancel", () => {
    //add code that will trigger when the workflow is aborted. ex:
    //alert('Cancelled!')
  });
</script>

This event is triggered when the user clicks the Cancel button or hit the ESC key.

Event: Widget is loaded​

<button id="blockpass-kyc-connect">Verify with Blockpass</button>
<script>
  const blockpass = new BlockpassKYCConnect("YOUR_CLIENT_ID");
  blockpass.startKYCConnect();

  blockpass.on("KYCConnectLoad", () => {
    //add code that will trigger when the iframe is loaded.
    //ex: stop loading animation
  });
</script>

This event is triggered when the widget iframe is fully loaded

Integration with a React app​

Load the Javascript in your main html file.

    <...>
    <script src= 'https://cdn.blockpass.org/widget/scripts/release/3.0.2/blockpass-kyc-connect.prod.js'></script>
  </head>
  <body>
    <...>
  </body>

Component:


  ...

  componentDidMount() {
    this.loadBlockpassWidget()
  }

  loadBlockpassWidget = () => {
    const blockpass = new window.BlockpassKYCConnect(
      'your_clientId', // service client_id from the admin console
      {
        refId: refId, // assign the local user_id of the connected user
      }
    )

    blockpass.startKYCConnect()

    blockpass.on('KYCConnectSuccess', () => {
      //add code that will trigger when data have been sent.
    })
  }

  render() {
    return (
      <button id="blockpass-kyc-connect">
        Verify with Blockpass
      </button>
    )
  }

  ...

Users on mobile​

Users on mobile phone cannot scan the QR code, obviously.

The widget will automatically suggest to use the app-link if the screen width is smaller than 615px (QR code option is still showing)

The app-link redirects to Blockpass Mobile App if the app is installed on the device.

See app-links and deep-links for more info about how the app-links work.