Leverage data for BI analytics

To gain visibility into every step of the identity verification process and enrich your BI analytics data, consider integrating Mosaic with external analytics system. By feeding identity verification events into your SIEMs (Security Information and Event Management), you'll be able to keep track of security events in real-time while collecting business analytics data needed to improve your app UX and better understand customer behavior patterns.

This guide explains how to set up event streaming using Mosaic APIs and provides a reference of the parameters available in IDV events.

Note

This guide assumes you have already integrated identity verification in your app. For integration instructions, refer to quickstart guides.

Step 1: Collect events

Leverage Event streaming APIs to collect identity verification activity.

  1. Enable event collection as described below.
Copy
Copied
import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({
    type: 'verify',
  }).toString();

  const resp = await fetch(
    `https://api.transmitsecurity.io/activities/v1/activities/start-collect?${query}`,
    {
      method: 'PUT',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>' // Client access token
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
  1. Create an event stream for identity verification events. Make sure to provide an ID to identify the stream. The stream ID should be a continuous string, without spaces, and unique for each stream.
Copy
Copied
import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({
    type: 'verify', //
    stream_id: '<YOUR_STREAM_ID>', // Unique stream ID, without spaces
  }).toString();

  const resp = await fetch(
    `https://api.transmitsecurity.io/activities/v1/activities/stream?${query}`,
    {
      method: 'PUT',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>' // Client access token
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();

Step 2: Feed to BI tool

Depending on the BI analytics tool you use, you might need to configure it to pull events from Mosaic or implement a job that retrieves events from Mosaic and forwards them to your BI system. To retrieve events, query the following endpoint as described below:

Copy
Copied
import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({
    type: 'verify', // Event type. One of cis, admin, risk, verify
    stream_id: '<YOUR_STREAM_ID>', // Unique stream ID
    batch_size: '100' // The number of events to return in each batch
  }).toString();

  const resp = await fetch(
    `https://api.transmitsecurity.io/activities/v1/activities/collect?${query}`,
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'  // Client access token
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();

Step 3: Review events

Below is example of identity verification event.

Copy
Copied
{
  "activity": "page_loaded",
  "appId": "gGyeOFH8LUdjefuwPei5JIl",
  "userId": "fHDV8gsIdJoid1br",
  "ip": "54.220.197.207",
  "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Mobile Safari/537.36",
  "timestamp": 1727005080107,
  "additionalParams": {
    "sessionId": "fHDV8gsIdJoid1br",
    "pageName": "document_front",
    "sdkVersion": "1.3.37",
    "platform": "web-sdk",
    "osVersion": "6.0",
    "deviceModel": "Nexus 5",
    "browser": "Chrome"
  }
}

Each activity event returned by Event Streaming APIs contains basic fields such as activity, appId, etc. Note that userId is populated with identity verification session ID (sessionID). Below are activity types related to identity verification and additional parameters returned for these activity types.

Activity Description Additional parameters
page_loaded Indicates a page load. sessionId ,platform sdkVersion, osVersion ,deviceModel, browser, pageName
user_action_performed Indicates an action was performed by the user, such as a button click. sessionId ,platform sdkVersion, osVersion ,deviceModel, browser, pageName, userActionType
image_uploaded_info Indicates an image upload, including metadata information (processing time, etc.). sessionId ,platform sdkVersion, osVersion ,deviceModel, browser, processResult, requestProcessingTimeMs, imageType
error Indicates an error on frontend, such as "something went wrong" page. sessionId ,platform sdkVersion, osVersion ,deviceModel, browser,error, errorDescription
redirect Indicates redirection to callback URL. sessionId ,platform sdkVersion, osVersion ,deviceModel, browser, redirectUrl
session_created Indicates creating a new verification session.
session_started Indicates starting a verification session.
consent_approved Indicates saving a consent info.
check_image_quality Indicates checking the image quality after capturing an image. imageType, checkResult
verification_status_updated Indicates the status of the internal verification process. result
allow_by_restriction_criterion Indicates the verification can continue according to the restriction criteria.
deny_by_restriction_criterion Indicates the verification was rejected based on restriction criteria.
session_deleted Indicates a session deletion (via API or by retention).

For identity verification events, Mosaic also returns additional parameters depending on specific activity type. View below available additional parameters and their values.

Parameter Description
sessionId Identity verification session ID.
sdkVersion SDK version used by the app.
osVersion Operating system version of the device that generated the event.
platform The platform the event originated from, for example web-sdk.
deviceModel The model of the physical device used for verification.
browser The browser name.
pageName The name of the page in the identity verification flow. One of: intro, qr, consent, timeout, permission_denied, permission_denied_no_refresh_button, document_back, document_front, selfie, instructions_screen, verification_completed_screen, error.
userActionType The action performed by user. One of: cancel, capture_image, accept_and_start_clicked, consent_checked, start_button_clicked.
processResult The result of image processing. One of: success, failure.
requestProcessingTimeMs The time it took to process the image.
imageType The type of image. One of: back, front, selfie.
redirectUrl The redirect URI for this flow.
result The identity verification result. One of:
- Success: verification completed successfully
- Pending: verification in progress (after all images have been captured)
- Rejected: verification completed as rejected
- Resubmit: verification could not completed, the user has to resubmit (recapture)
- Error: an error occurred during verification
- Uncertain: a resubmission was requested due to uncertain result
checkResult The result of the checking procedure.
errorName The name or type of the error.
errorDescription Error description.