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.

Test the integration

Open your browser's dev tools on one subdomain and note the croct.id cookie value. Then navigate to a different subdomain and check the same cookie. If the value matches, the integration is working correctly.