Integrate using Google Tag Manager

This guide describes how to use Google Tag Manager (GTM) to integrate Detection and Response services into your web app. For more information about GTM, refer to Google's documentation. See:

• Creating user-defined variables
• Creating custom tags
• Configuring triggers

Prerequisites

Your web application must be integrated with Google Tag Manager (see Quick-start for Web), and send it the user identifier (for authenticated users) and the user actions you want to evaluate with Mosaic.

The examples in this guide use the data layer to send information to Google tags.

Step 1: Get client credentials

Client credentials are used to identify your app and generate access tokens for authorizing Mosaic requests. To obtain them, you'll need to create an application in the Admin Portal (if you don’t have one yet).

1. From Applications , click Add application .
2. Add the friendly application name to display in the Admin Portal.
3. Add a client display name, and your website URL as a redirect URI (e.g., https://your-domain.com ).

   Note

   These fields are required for all Mosaic apps, but won’t be used for Detection and Response.

4. Click Add to create your application. This will automatically generate your client credentials.

Step 2: Create GTM variables

To send the user identifier and action to Mosaic, you'll need GTM variables that store these values. Create a variable for the user identifier and another one for the user action you want to report.

For example, create a new User-Defined Variable, set its title (e.g., Mosaic user ID) and configuration to Data Layer Variable, and then provide the name of the variable that your web app sends to GTM (e.g., userID).

Step 3: Load SDK via GTM

Create a new custom tag with the HTML script that loads and initializes the Platform SDK. This tag should be triggered for all pages.

In the snippet below, the SDK is initialized with the user ID (for users that are fully authenticated, including, for example, any required 2FA that was done).

 // Loads the latest SDK within the major version 1
 // See changelog for details and update version if necessary
 <script src="https://platform-websdk.transmitsecurity.io/platform-websdk/1.x/ts-platform-websdk.js" id="ts-platform-script" defer="true" ></script>
    <script>
      console.log("Start event listener for tsPlatform script");
      document.getElementById("ts-platform-script").addEventListener("load", function() {
          window.tsPlatform.initialize({
            clientId: "[CLIENT_ID]", // Client ID found in the app settings
            drs: { userId: "[USER_ID]" }, // GTM variable; if user ID exists
          });
      });
    </script>

Step 4: Report actions via GTM

To obtain risk recommendations for sensitive actions, your application should report these actions using the Platform SDK. To do this with GTM, you need to create a custom tag to send the action to Mosaic. The tag should be triggered every time a user performs a sensitive action. To improve detection and response, pass the correlation ID as well (optional).

For example, create a custom tag (e.g., Mosaic action) with the following code where [mosaic_action] is the GTM variable you created for storing user actions in step 2. This tag should be triggered when a sensitive action is requested in your application.

    <script>
      function saveActionTokenToDataLayer(actionResponse) {
            dataLayer.push({"mosaic_action":actionResponse.actionToken}); // mosaic_action - GTM variable that stores user actions
      }
      window.tsPlatform.drs.triggerActionEvent("[mosaic_action]", { correlationId: "[correlation_id]" }).then(saveActionTokenToDataLayer);
    </script>

Step 5: Fetch recommendation

You can fetch recommendations for the reported action using the Recommendation API.

  const { access_token } = await fetch(
    `https://api.transmitsecurity.io/oidc/token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      }
      body: new URLSearchParams({
        grant_type: client_credentials,
        client_id: [CLIENT_ID], // Client ID found in the app settings
        client_secret: [CLIENT_SECRET], // Client secret found in the app settings
        resource: 'https://risk.identity.security' //DRS resource
      })
    }
  );

From your backend, invoke the Recommendation API by sending a request like the one below:

const query = new URLSearchParams({
  action_token: '[ACTION_TOKEN]', // 'actionToken' received from the SDK
}).toString();

const resp = await fetch(
  `https://api.transmitsecurity.io/risk/v1/recommendation?${query}`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer [ACCESS_TOKEN]', // Authorization token you obtained using your client credentials
    },
  }
);

Step 6: Clear user

After the user logs out or the user session expires, you should clear the set user so they are not associated with future actions. To clear the user with GTM, you need to create a custom tag to send the clearUser() event to Mosaic.

For example, create a new custom tag (e.g., Mosaic clear user) that invokes the sample code and is triggered when the user logs out (i.e., clicking the Logout button is specified in the trigger configuration).

<script>
  document.getElementById("ts-platform-script").addEventListener("load", function() {
    window.tsPlatform.drs.clearUser();
    console.log("Mosaic user cleared");
  });
</script>