Identify users across subdomains

By default, the SDK stores identifiers in the browser's local storage, which is scoped to a single origin. This is a deliberate privacy-first choice: no external site can access the data, and there is no cross-site tracking. However, it also means that www.example.com and app.example.com each see a different anonymous user.

A first-party cookie solves this. Because cookies can be scoped to a parent domain, setting one on example.com makes it accessible from any subdomain, keeping the identity consistent everywhere.

First-party cookies are privacy-friendly

Unlike third-party cookies, first-party cookies are set by your own domain and are never shared with external sites. They are simply how your application remembers its own visitors, no different from keeping a user logged in.

Configure the cookie

The SDK uses two cookies: clientId identifies the browser, and userToken holds the user's token. Both need to be shared across subdomains for full continuity.

To enable this, pass the cookie option when initializing the SDK with the name, maxAge, domain, and path for both cookies. Make sure to apply this configuration on every domain and subdomain where the SDK runs. Otherwise, the cookies won't be shared consistently.

import croct from '@croct/plug';
croct.plug({  appId: 'APPLICATION_ID',  cookie: {    clientId: {        name: 'croct.id',        maxAge: 31536000,        domain: 'example.com',        path: '/'    },    userToken: {        name: 'croct.user_token',        maxAge: 31536000,        domain: 'example.com',        path: '/'    } }});

Always set the domain to your main domain (e.g., example.com), even when configuring a subdomain. This is what scopes the cookie to the parent domain and makes it available everywhere.

Try it out

Verify that the cookie is shared across subdomains:

1. Open your first subdomain

   Navigate to one subdomain (for example, www.example.com) and open the browser dev tools. Check the croct.id cookie value under Application > Cookies.

2. Open another subdomain

   Navigate to a different subdomain (for example, app.example.com) and check the same cookie.

3. Compare the values

   If both subdomains show the same croct.id value, the integration is working correctly.