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).
- From Applications , click Add application .
- Add the friendly application name to display in the Admin Portal.
-
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.
Note
Transmit recommends testing changes in a development theme before publishing.
- Navigate to Online Store > Themes > Edit Code .
- Locate the layout/theme.liquid file.
-
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.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>
Notes
Transmit recommends wrapping the code in a function scope for:
- Scope isolation: any variables (like script) don’t leak into the global window scope.
- Safety in liquid templates: Shopify themes often have multiple scripts embedded inline.
-
Cleaner debugging: variables won’t show up in global scope during debugging (e.g., in
window.script
)
Important: Ensure the external domain is secure (uses HTTPS).
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.
Note
For an alternative approach that directly utilizes our backend API instead, refer to our Backend API implementation guide.
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]');
Note
For an alternative approach that directly utilizes our backend API instead, refer to our Backend API implementation guide.
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 %}