Skip to content
RoutingCatRoutingCatRoutingCat Docs

Auth providers

However your site creates accounts, it identifies and tracks where it learns that an account exists. This guide shows where, from your server or from the page, then the provider’s webhook, and two pitfalls. It builds on Track conversions, whose HTTP recipe each step below uses.

Choose where to record the sign-up

  • Where your server creates its own record of the account, such as its user row after sign-up: identify, then track signup there, through the HTTP events API, with the visitor id from the request’s rc_vid cookie, as Track conversions shows.
  • With no such place, as when a provider keeps the accounts: from your server, at the new user’s first signed-in page load. Nothing is set up at the provider, but a user who never loads a signed-in page is missed.
  • Also in the provider’s user-created webhook, if you want every sign-up: it needs its endpoint added in the provider’s dashboard.

Every path records the sign-up under the id signup:<user id>, so a sign-up that several paths record counts once. Whichever you choose, identify at every sign-in too, so that the person’s other devices link to the account.

Identify at every sign-in

Where your server completes a sign-in, or renders the first page signed in, it posts an identity link for the user’s id and the request’s rc_vid. A sign-in that only the page sees, such as one a provider’s widget completes in the browser, calls window.routingcat.identify() with the user’s id in the page instead.

The link is only as lasting as the visitor id it names. Written by RoutingCat’s script, the id lasts 7 days in Safari without a visit; set by the cookie helper, 400 days, so a returning visitor’s sign-in links the browser that saw your pages weeks before.

Record the sign-up at the first signed-in page load

On a signed-in page load, your server reads the user from the provider, with the time the provider created it. For a user created in the last seven days, it identifies, then tracks signup with:

  • id: signup:<user id>, so that each user counts once, however many pages and browsers record them;
  • account_id: the user’s id;
  • visitor_id: the request’s rc_vid;
  • occurred_at: the user’s creation time, in RFC 3339 or Unix seconds. A provider that gives milliseconds needs them converted, since RoutingCat reads a plain number as seconds.

A user created in the week before the install is recorded at their next signed-in page load, dated when they signed up. An older user signed up before RoutingCat, and records no sign-up. Remembering in the user’s session that it was recorded saves a call at each page load; the shared id keeps the count right without it.

Add the user-created webhook

Optional. A webhook carries no visitor cookie, so the sign-up passes the visitor id to the provider, in the field the provider lets a sign-up set: Clerk’s unsafeMetadata, or Supabase’s signUp options.data. The page reads the id from the rc_vid cookie, which your browser code can read. OAuth sign-ups have no such field, so they rely on the first-load recording.

On the user-created event, the webhook’s handler identifies the new user with that visitor id, then tracks signup under the same id as the first-load recording, signup:<user id>, dated when the provider created the user, through the events API. Then add the endpoint in the provider’s dashboard, and keep its signing secret in your server’s environment.

Avoid two pitfalls

  • Verification on another device. When email verification finishes on another device, identify at account creation, on the first device: that browser is the visitor who saw your pages.
  • Callbacks posted from another site, such as Sign in with Apple’s form_post, arrive without RoutingCat’s cookie, which is SameSite=Lax, so an identity link there has no visitor id. Identify at the next page load instead. status reports such calls as identify without a visitor id.

Next