Integrate with Shopify storefront

This guide describes how to integrate Fraud Prevention into a Shopify storefront by modifying the theme code. This integration enables collection of risk signals and user context directly from the storefront.

Prerequisites

Make sure you have completed the Shopify setup and have admin access to your Shopify store and Shopify theme code. For more information on Shopify storefront, see Shopify documentation.

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 an OIDC client, specify the client secret as an authentication method, and your website URL (e.g., https://your-domain.com ).

   Note

   These fields are required for all Mosaic apps, but won’t be used for Fraud Prevention.

This will automatically generate your client credentials.

Step 2: Modify Shopify theme

Modify your Shopify theme (theme.liquid) by inserting a script loader. The loader will invoke the Mosaic SDK.

1. Navigate to Online Store > Themes > Edit Code .
2. Locate the layout/theme.liquid file.
3. Add the following code before the </body> . The [CLIENT_ID] is your client ID obtained in Step 1 .

<script>
  (function() {
    var tsScript = document.createElement('script');
    tsScript.src = 'https://platform-websdk.transmitsecurity.io/platform-websdk/1.x/ts-platform-websdk.js';
    tsScript.id = 'ts-platform-script';
    tsScript.defer = true; // using defer for not block the rendering, and run after HTML parsing completed

    document.head.appendChild(tsScript);
document.getElementById("ts-platform-script").addEventListener("load", function() {
// the following code will run after the script was initialized:
    window.tsPlatform.initialize({
      clientId: "[CLIENT_ID]", // Replace with client ID obtained in Step 1
      drs: {
        serverPath: "https://api.transmitsecurity.io/risk-collect/", // For US and global. For EU, use "https://api.eu.transmitsecurity.io/risk-collect/"; for Canada, use "https://api.ca.transmitsecurity.io/risk-collect/"
      }
    });
  });

})();
</script>

Step 3: Trigger actions

To obtain risk recommendations for sensitive actions, your application should report these actions using the Platform SDK. Configure the relevant button onclick events to trigger action events as described below. Replace [ACTION_TYPE] with the appropriate action type from our list of actions. To improve Fraud Prevention, optionally pass the correlation ID, and claimed user ID and its type (for users that haven't authenticated yet).

This call returns actionToken that you should pass your backend to obtain the recommendation in the next step.

const actionResponse = await window.tsPlatform.drs.triggerActionEvent("[ACTION_TYPE]", { correlationId: "[CORRELATION_ID]", claimedUserId: "[CLAIMED_USER_ID]" } });
const actionToken = actionResponse.actionToken;
// Add code here to send the received actionToken to your backend

Step 4: Fetch recommendation

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

These APIs are authorized using an OAuth access token so you'll need to fetch a token using your client credentials (from Step 1). The token should target the following resource: https://risk.identity.security. To do this, send the following request:

const formData = {
  client_id: '[CLIENT_ID]', // Obtained in Step 1
  client_secret: '[CLIENT_SECRET]', // Obtained in Step 1
  grant_type: 'client_credentials',
  resource: 'https://risk.identity.security'
};

const resp = await fetch(
  `https://api.transmitsecurity.io/oidc/token`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams(formData).toString()
  }
);

From your backend, invoke the Recommendation API by sending a request like the one below. The [ACCESS_TOKEN] is the authorization token you obtained using your client credentials and [ACTION_TOKEN] is the actionToken received from the SDK in Step 3.

const query = new URLSearchParams({
  action_token: '[ACTION_TOKEN]', // Obtained in Step 3
}).toString();

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

Step 5: Set user

A user identifier must be reported to Mosaic after you've fully authenticated the user (including, for example, any required 2FA that was done). This will set the user for all subsequent events in the current device session, or until the app prompts the user to re-login, or until the user is explicitly cleared.

To do this, add the JS code below after your application has authenticated a user (or after SDK initialization if you already have the user context of the authenticated user when loading the page). The [USER_ID] is an opaque identifier for the user in your system and must not include personal user identifiers, such as email, in plain text. When the customer is authenticated, the __st.cid variable can be used as a reliable user ID value, as it reflects the Shopify customer ID.

await window.tsPlatform.drs.setAuthenticatedUser('[USER_ID]');

Step 6: Clear user

The user gets automatically cleared once the session or in case of a new login action. After the user logs out, you should clear the set user so they are not associated with future actions. To clear the user, call the clearUser() method:

await window.tsPlatform.drs.clearUser();

Next steps

Fine-tune your integration to only load the script on specific pages, such as the home page or product page:

{% if template == 'index' %}
<!-- Script loader here -->
{% endif %}

or
{% if template contains 'product' %}
<!-- Script loader here -->
{% endif %}