Autocapture vs. Custom Events

There are two ways to get authentication data into Corbado Observe. They are not competing options. Most teams run Autocapture as the foundation and add custom events only where they need more. Both feed the same data model and the same views.

​

1. Autocapture

You deploy a single script and Corbado maps your authentication journey from signals your frontend already emits. No event tagging, no change to your login flows and no instrumentation to maintain as your login evolves.

​

1.1 What Autocapture actually does

Autocapture is not a black box. Concretely, it does five things in the browser: Those raw signals are then mapped onto your actual flows, so which request means “identifier accepted” and which button means “user chose password over passkey”. They arrive in Observe as a modeled journey rather than a stream of clicks. Autocapture is built on @corbado/autocapture, a dependency-free capture library designed to run inside a page it does not own and to fail closed when a browser surface cannot be instrumented safely.

​

2. Custom events

Custom events are explicit Corbado Observe events you emit from your own code, at the semantically correct points in your flows. You get exactly the granularity you define, and this is the only path available on native platforms. Section 3 explains exactly when you need them. See Custom events to send your first one, and the tracking reference for the full data model.

​

3. Where Autocapture stops

The boundary is not “simple flows vs. complex flows”. It is observability in the client. Autocapture can work with anything that is visible in the browser or reported back to it: rendered UI states, user interactions, WebAuthn ceremonies, navigation and the shape of requests and responses. From those signals Corbado’s mapping derives the product meaning, including which method a user chose, whether an identifier was already known, whether a ceremony was a login or an enrollment and whether the user or the system started a step. Custom events are for facts that never reach the browser, or that you want pinned rather than derived:

​

4. Combining both on web

Running Autocapture and custom events together on web is a supported setup, sometimes called a hybrid integration. Autocapture provides the baseline journey and you add events only for the gaps that matter, including enrichment from your backend. Both write into the same project, the same session and the same data model, so the added events appear inside the same journey rather than beside it. Because the exact wiring depends on how your Autocapture bundle is delivered, set this up together with us rather than adding a second SDK instance to the page.

​

5. Choosing between them

What we recommend:

• Web: start with Autocapture, then add custom events for the gaps in section 3.
• iOS and Android: custom events, using the native SDKs.
• Both web and native apps: Autocapture on web and custom events in the apps. Do not drop Autocapture just because your apps need instrumenting. One project holds all three channels, and applications keep them comparable.

​

6. Next steps