Skip to main content

Customer User IDs

Customer User IDs.svg

Assign internal User IDs to tracked sessions

You can now assign your own internal user IDs to the visitors tracked by the fraud0 tag. This can support improved attribution, cross-session analysis, and help you connect data more effectively in your backend systems. The ID is sent client-side and linked to the current session on our servers — giving you a straightforward way to reference known users once they’ve been identified (e.g. after login).

What’s new? We’ve added a method to our Onsite script that allows you to send a customer_user_id once the user is known (e.g. after login). The ID is automatically associated with the session server-side.


1) How to use

Step 1: Include the fraud0 tag early on your page

HTML
<script async src="https://api.fraud0.com/api/v2/fz.js?cid=YOUR_TAG_ID"></script>

Step 2: Once the user logs in or is identified, call:

JS
login().then(() => {
  const userId = getCurrentUserId();
  window.fraud0?.setCustomerUserId?.(userId);
});

Step 3: Track conversions as usual

JS
window.fraud0 = window.fraud0 || [];
window.fraud0.push(["purchase", "order-123"]);

You can call setCustomerUserId() before or after a conversion — as long as it's in the same session, the ID will be included during session aggregation.

2) Customer User ID and Tag Readiness

To ensure that Fraud0 tag is ready to accept the customer user ID, you will need to implement one of the following solutions:

Option A: Set after the tag

If you set the customer user ID after the fraud0 tag is instantiated on the page (e.g. in a later <script>, React effect, or SPA route) then use window.onFraud0Ready(x). 

This will be invoked immediately if the tag is ready, otherwise it waits for readiness, then runs once.

HTML
<script src="https://api.fraud0.com/api/v2/fz.js?cid=YOUR_TAG_ID"></script>
<script>
  window.onFraud0Ready?.(() => {
    window.fraud0.setCustomerUserId('customer-123');
  });
</script>

Option B: Set before the tag

If you prefer to set the customer ID using callback before the fraud0 tag is fetched (e.g. in <head> or via GTM custom HTML) then use fraud0ReadyCallbacks. This will queue the callback; the tag flushes the queue when ready with no race conditions.

HTML
<script>
  window.fraud0ReadyCallbacks = window.fraud0ReadyCallbacks || [];
  window.fraud0ReadyCallbacks.push(() => {
    window.fraud0.setCustomerUserId('customer-123');
  });
</script>
<script src="https://api.fraud0.com/api/v2/fz.js?cid=YOUR_TAG_ID"></script>

Option C: Direct event listener

You can guarantee your listener executes before the tag (order known, both blocks in the same template).This is the lowest‑level API; fires exactly once. It must be attached before the tag loads.

HTML
<script>
  window.addEventListener('fraud0Ready', () => {
    window.fraud0.setCustomerUserId('customer-123');
  }, { once: true });
</script>
<script src="https://api.fraud0.com/api/v2/fz.js?cid=YOUR_TAG_ID"></script>

Note: fraud0Ready is a one‑shot event and is emitted exactly once – right after the tag finishes initialising. If you start listening after it has fired, the handler will never run. Use the best pattern below that matches when your own code executes.

3) Disabling the f0_uid cookie

Append customer_user_id_only=true to the script URL to skip creating the internal f0_uid cookie. A temporary ID is kept in memory so events on the same page can still be correlated.

HTML
<script src="https://api.fraud0.com/api/v2/fz.js?cid=YOUR_TAG_ID&customer_user_id_only=true"></script>

Notes

  • Uniqueness: customer_user_id must uniquely identify a single end‑user. Fraud0 does not deduplicate values, so it is the integrator’s responsibility to ensure IDs are not reused across different users.

  • You can call setCustomerUserId() multiple times; the latest value is used for the session.

  • The value must be a string, 1–255 characters long.

  • This feature is backward‑compatible with all existing conversion‑tracking methods (e.g., fraud0.push(['purchase'])).

The field is available in your sessions as customer_user_id, resolved during session aggregation.


Need support?

Do you still have questions or require further details? Contact our support team for assistance!

Send us an email →

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.