Create a Cross-Device Session

A cross-device session enables an authentication or signing flow initiated in a web application to be completed on a mobile device.

To start a cross-device session for authentication or document signing, call the createCrossDeviceSession method of the MIRACL Trust Client JS Library. The method accepts a configuration object containing the following parameters:

# Session for Document Signing

To create a session for signing, include the signingHash property:

try {
  const crossDeviceSession = await mcl.createCrossDeviceSession(
    userId,
    description,
    signingHash,
  );
  console.log(crossDeviceSession);
} catch (err) {
  // Handle any potential errors
}

# Session for Authentication

For authentication, omit signingHash. Once initiated, poll the session status to verify completion:

async function generateQR() {
  let session;

  try {
    session = await mcl.createCrossDeviceSession(userId, description);
  } catch (err) {
    console.error(err);

    return;
  }

  // Generate QR code using a QR library
  // new QRCode(crossDeviceSession.url);
  // Or display the session URL directly for deep linking
  // displayLink(crossDeviceSession.url);
  // Or send a push notification
  // await mcl.sendPushNotification(session);

  // Start polling for session status
  poll(session);
}

async function poll(session) {
  let data;

  try {
    data = await mcl.checkCrossDeviceSessionStatus(session);
  } catch (err) {
    console.error(err);

    return;
  }

  if (data.status === "authenticated") {
    // The JWT in the result needs to be verified by your back end
    // to ensure that the authentication was successful
    console.log(data.jwt);

    return;
  }

  if (data.status === "expired") {
    console.info("the authentication session has expired");

    return;
  }

  // Poll again after 2s
  setTimeout(() => {
    poll(session);
  }, 2000);
}

Calling the createCrossDeviceSession initiates the cross-device session. As a result, the response returns crossDeviceSession.url that can be used for authentication and signing sessions via QR codes and deep linking.

Once you create a session, you can deliver it from one device to another via deep linking, QR code or push notification.

## Deep Linking

Display crossDeviceSession.url directly for deep linking (as a link or, preferably, as a button) into a mobile application.

Clicking the link/button opens your mobile application (if already installed); otherwise, it takes the end user to the mobile landing page, where there are links to the Google Play Store and Apple App Store.

To configure the landing page to display links to your application in the app stores:

1. Go to your project in the MIRACL Trust Portal.
2. In the Configuration section, go to Mobile Applications.
3. Type the links to your app in the Google Play Store URL and Apple App Store URL fields.

If the application is installed and SDKs initialised, when the end user clicks the link/button and opens the app, the method for fetching the cross-device session is called. It makes a connection to the session created in the browser and then authenticates the user with the M-PIN protocol.

## QR Code

Generate a QR code that will be displayed and scanned by another device.

The crossDeviceSession.url is not encoded as a QR code; therefore, you must use an external library to encode it.

You can display the generated and encoded QR code anywhere on your website.

Scanning the QR code with a mobile device or clicking the link/button opens your mobile application (if already installed); otherwise, it takes the end user to the mobile landing page, where there are links to the Google Play Store and Apple App Store.

To configure the landing page to display links to your application in the app stores:

1. Go to your project in the MIRACL Trust Portal.
2. In the Configuration section, go to Mobile Applications.
3. Type the links to your app in the Google Play Store URL and Apple App Store URL fields.

If the application is installed and SDKs initialised, when the end user scans the QR code and opens the app, the getCrossDeviceSessionFromQRCode method is called. It makes a connection to the session created in the browser and then authenticates the user with the M-PIN protocol.

## Push Notification

Call the sendPushNotification method to send a request for authentication/signing to a registered mobile device:

Promise:

try {
  await mcl.sendPushNotification(crossDeviceSession);
} catch (err) {
  // Handle any potential errors
}

Callback:

mcl.sendPushNotification(crossDeviceSession, function (err, result) {
  if (err) {
    // Handle any potential errors
    return;
  }
});

As MIRACL Trust uses Firebase Cloud Messaging (FCM) to send notifications, you must provide your Firebase Service Account Private Key to authorise MIRACL Trust to send push notifications to your end users on your behalf. To do so:

1. Go to your project in the MIRACL Trust Portal.
2. In the Configuration section, go to Mobile Applications.
3. Check Enable Push Notification.
4. Upload your Firebase Service Account Private Key.

It is important to do this as a first step so as to provide an FCM registration token.

When the sendPushNotification method is called, it calls an endpoint that checks the User ID for an FCM registration token. If it is not present, an error is returned. If it is present, a request is made to Firebase Cloud Messaging to send a push notification. If Firebase returns an error, MIRACL Trust returns an error too.

When a push notification is sent successfully, and the end user clicks the link in it, your mobile application opens. The notification’s payload is then passed to the getCrossDeviceSessionFromNotificationPayload method in the SDK. It makes a connection to the session created in the browser and authenticates the user with the M-PIN protocol.