How-to integrate QR/Web-link to trigger Interaction

\uD83D\uDCD8 Instructions

1. Library options
   ssi-auth-lib library shows QR for desktop browsers and Web-link button for mobile browsers to trigger the interaction. It has two options:

   1. Show QR/Web-link to trigger an interaction with QR initiation media selected.

   2. Show QR/Web-link to trigger an interaction with QR initiation media selected and support SSI OAuth flow configured on the dashboard for this particular interaction.
      

2. Library can be included

   1. as builded bundle

      <script src="<path_to_lib>/wl.js"></script>
      

   2. or as npm library https://www.npmjs.com/package/ssi-auth-lib
      npm install ssi-auth-lib –save
const ProofSpace = require(‘ssi-auth-lib’)
      

3. Usage

   1. For the pure interaction without SSI OAuth flow

      ProofSpace.WebLinker.start(elem, {
       serviceDid: <YOUR_SERVICE_DID>,
       interactionId: <YOUR_OAUTH_ACTION_ID>,
       instanceId: <YOUR_OAUTH_INSTANCE_ID>,
       size: 300 // size of QR code in pixels
      }).then(() => {
       console.log(‘QR Initialized’);
      });

   2. For the interaction with SSI OAuth flow

      ProofSpace.WebLinker.startWithSSIOAuth(elem, {
       clientId: <OAUHT_EXTENSION_ID>
       serviceDid: <YOUR_SERVICE_DID>,
       interactionId: <YOUR_OAUTH_ACTION_ID>,
       instanceId: <YOUR_OAUTH_INSTANCE_ID>,
       size: 300 // size of QR code in pixels
      }).then((result) => {
       console.log(result.access_token);
      });

To find the “clientId”, install the “SSI OAuth Extension” to your service, then add it to the desired interaction. Click on the installed “SSI OAuth Extension” in the interaction. The first line will be “clientId.”

To find the “serviceDid”, go to the “Service Info” page. The first line on the new page will be “Service Public DID.”

To find the “interactionId”, click the “Interactions” tab. One of the columns on the “Interactions” page is “ID.” Find the interaction where you added the “SSI OAuth Extension.”

To find the “instanceId”, click on the “Interactions” tab. On the new page, click on the desired interaction’s name. Then, on the “Interactions/YOUR_INTERACTION_NAME” page, select the “Instances” tab and choose the Interaction Instance ID.

4. Both start and startWithSSIOAuth has 3 parameters:

start(element, config, preFilledCredentials)

where

• element - HTMLDivElement to show QR code (or button in case mobile device)
  If you want to use popOverMode, then element must contain some visible elements like button or image 

• config - structure

{
  size?: number; // size of QR-code in pixels
  env?: Env; // environment config, used for test, stage or local environment. Prod by default
  serviceDid: string; // your service did
  interactionId: string; // id of your interaction
  instanceId: string; // id of your interaction instance 
  button?: BtnConfig; // config for styling button for mobile web link
  timer?: Style; // style for timer element (for SSIOAuth)
  qr?: Style; // style for QR element
  returnToBrowser?: boolean; // use callback for return to browser page
  popOverMode?: boolean; // use PopOver with QR code for desktop
  log?: LogFn; // function for logs (debug info)
}

• preFilledCredentials - array of Pre-filled Credential structures
  
  This section is used when the interaction contains Self-Attested credentials that should be pre-filled from QR/Web-link e.g. Session ID or User ID to match your user with the credentials shared by ProofSpace App user and received by your backend via webhook.

   

  {
    credentialId: '<YOUR_CREDENTIAL_ID>',
    attributes: [
      {name: '<Attribute1 name>', value: '<Attribute1 value>'},
      {name: '<Attribute2 name>', value: '<Attribute2 value>'},
      // ... other pre-filled attributes
    ]
  }

• env : Env is required if you want to use own OAuth server or service container, by default it uses ProofSpace PROD URIs.
  Env template:

{
  containerURIPrefix: string
  SSIAuthenticationCredDefId: string;
  authServiceUrl: string;
  nativeURIPrefix: string
}

Or you can use predefined TEST and STAGE ProofSpace env if you have your services up and running there:

ProofSpace.ENV.TEST for the Testing Environment

ProofSpace.ENV.STAGE for the Staging Environment

Example:

1. ProofSpace.WebLinker.start(elem, {
    env: ProofSpace.ENV.STAGE,
    serviceDid: <YOUR_SERVICE_DID>,
    interactionId: <YOUR_OAUTH_ACTION_ID>,
    instanceId: <YOUR_OAUTH_INSTANCE_ID>,
    size: 300 // size of QR code in pixels
   }).then(() => {
    console.log(‘QR Initialized’);
   });

• BtnConfig structure
  

  {
    class?: string; // css class
    style?: string; // css class
    text?: string; // button text. Default is 'Start interaction'
    icon?: string; // image url for button icon
    textStyle?: Style;
    iconStyle?: Style;
    target?: string; // browser target. Default is _self
  }

• Style structure:
  

{
  class?: string; // css class
  style?: string; // css class
}

To simplify the integration ProofSpace Dashboard can show the test QR and generate the code to embed for your interactions.

Example:

5. You may find a few examples through the links:

Pre-filled credentials

SSI OAuth Demo

\uD83D\uDCCB Related articles