Iota Browser

Integrate Affinidi Iota Framework on your applications to request and receive data from Affinidi Vault.

Supported Languages

Package: @affinidi-tdk/iota-browser

npm install @affinidi-tdk/iota-browser --save

Implementation Note

The Iota Browser library is a browser-only module; make sure to invoke the library on the client side. It creates a WebSocket connection and requires access to the browser window object to initiate a data request to the Affinidi Vault.

If you are using a framework that has a server-side rendering like NextJS, you can do the following:

Check the availability of the Window object when rendering.

useEffect(() => {
    if (typeof window !== 'undefined') {
        const initIota = async () => {
            const iotaSession = new Session({ credentials: iotaCredentials });
            await iotaSession.initialize();

        }
        initIota()
    }
}

Wrap the Iota Browser code in a component and disable the SSR with NextJS Dynamic Imports

import dynamic from 'next/dynamic'

const IotaClientComponent = dynamic(() => import('components/Iota/IotaClientComponent'), {
  ssr: false,
})

export default function Page() {
  return <IotaClientComponent />
}

Classes and Methods

Session

Used to setup and manage the request to Affinidi Iota Framework. To initialise the Session, generate the Iota Credential using the iota-core package and pass the credential as a parameter.

Parameters

SessionParams [Object]

JSON object that requires the Iota Credentials as a parameter.

Example
const credentials = await getIotaCredentials(configurationId);
const iotaSession = new Session({ credentials });

The getIotaCredentials is an async function that calls an exposed API endpoint from the backend to generate the Iota Credentials.

initialize

Initialises the Iota Session, which opens a WebSocket that listens to callback events from the Affinidi Iota Framework service.

Parameters

No Parameters Required

Example
const iotaSession = new Session({ credentials })

await iotaSession.initialize()

prepareRequest

Creates the IotaRequest object from the initialised Iota Session. The response contains the signed Request Token for the Affinidi Vault to request data.

Parameters

PrepareRequestParams [Object]

JSON object containing the Query ID as a required parameter, and optionally accepts the Correlation ID, and Audience.

Example
const request = await iotaSession.prepareRequest({ queryId })

IotaRequest

The class that initiates the data-sharing flow between the application and the Affinidi Vault is initialised from the prepareRequest method containing the signed Request Token.

openVault

Opens the Affinidi Vault with the signed Request Token and queries the data.

Parameters

OpenVaultParams [Object]

JSON object that optionally accepts the link to the Affinidi Vault, including the mode to open the Affinidi Vault, either a browser popup or new tab. The NewTab is the default open mode.

Example
const iotaRequest = await iotaSession.prepareRequest({ queryId })

iotaRequest.openVault({ mode: openMode })

getResponse

Gets the response from the Affinidi Vault through the open WebSocket from the initialised Iota Session.

Parameters

No Parameters Required

Example
const iotaRequest = await iotaSession.prepareRequest({ queryId });
iotaRequest.openVault({ mode: openMode });

const response = await iotaRequest.getResponse();

Check for Iota Request Response

To check if Iota Request is a valid response and parse the Verifiable Presentation (verifiablePresentation), use the IotaResponse instance.

Example
const iotaRequest = await iotaSession.prepareRequest({ queryId })
iotaRequest.openVault({ mode: openMode })

const response = await iotaRequest.getResponse()

if (response instanceof IotaResponse) {
    // parse the Verifiable Presentation and do business logic
}

Check for Iota Request Error

To check if there’s an error on the Iota Request and parse the relevant information about the error, use the IotaError instance.

Example
try {
    const iotaCredentials = await getIotaCredentials();
    const iotaSession = new Session({ credentials: iotaCredentials });
    await iotaSession.initialize();
} catch (error) {
    if (error instanceof IotaError) {
        console.log(error.code);
    }
}