Returning visitors: recognise returning devices before sign-in

The problem

Without a stable ID, every cleared cookie makes a returning customer look new. Your welcome offers go to people who already have an account, your funnel numbers count the same device twice, and your fraud rules cannot tell a first visit from a hundredth.

What you get

The visitor ID refers to a browser or an app install, not to a person.

• isNew on every event: whether this visitor ID has been seen in your project before.
• A visitor ID that stays the same across sessions, without relying on a cookie.
• Your own user ID attached with linkedId once someone signs in, so anonymous visits and the account line up.
• The visit history of one visitor, read from your server.

Where teams use it

• Show a returning-customer banner, or skip the first-visit tour, before login.
• Tell first visits from repeat visits on sign-up and checkout, where fraud prevention is the purpose.
• Offer first-purchase discounts only to visitors who are new.
• Give your fraud rules a baseline: a new visitor at checkout is treated differently from a known one.

Tell new from returning on the server

// Server side, with the eventId the page got from identify
if (!/^ev_[0-9A-HJKMNP-TV-Z]{20}$/.test(eventId)) throw new Error('bad eventId'); // fail closed
const r = await (await fetch(`https://api.fpchecker.com/v1/events/${eventId}`, {
  headers: { 'X-Secret-Key': process.env.FPCHECKER_SECRET_KEY },
})).json();
if (!r.visitorId) throw new Error(r.error ?? r.reason);
if (r.eventId !== eventId || !(Date.now() - Date.parse(r.createdAt) <= 5 * 60_000)) throw new Error('stale or reused event'); // wrong or old event
if (!(await markEventUsed(eventId))) throw new Error('stale or reused event'); // your store: true only the first time
// r.isNew is true when this visitor ID has not been seen in your project before
return { visitorId: r.visitorId, returning: r.isNew === false };

Frequently asked questions