> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corbado.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Autocapture vs. Custom Events
> Corbado Observe offers two ways to capture authentication data: Autocapture, the recommended default on web and custom events for anything Autocapture cannot infer.
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
**Recommended for web.** Autocapture is the default integration path.
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:
| Mechanism | What it means in practice |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Inspects the DOM tree** | Locates the elements your authentication runs through: identifier and password fields, OTP inputs, submit and method-selection buttons, including across shadow-DOM boundaries. Field semantics such as `autocomplete="new-password"` distinguish a "set new password" field from a login field. |
| **Listens to DOM events** | `focus`, `blur`, `input`, `click` and `submit` on those elements produce the low-level signals that show *how* a user moved through a screen, including hesitation, retries and abandoned fields. |
| **Observes the WebAuthn API** | The full lifecycle of `navigator.credentials.get()` and `create()`, including **silent cancellations** that produce no error and no backend request. |
| **Observes your auth network calls** | The start and outcome of requests to the endpoints Corbado is configured to watch, correlated by request ID. All other traffic is ignored. |
| **Follows in-app navigation** | Same-document (SPA) route changes, so a journey stays intact across a client-side router. |
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`](https://www.npmjs.com/package/@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.
Autocapture pairs the capture library with a mapping for **your** flows, which Corbado builds and keeps current. It is therefore set up together with Corbado during onboarding rather than fully self-serve. [Talk to us](mailto:support@corbado.com) to get started.
## 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](/corbado-observe/get-started/custom-events) to send your first one, and the [tracking reference](/corbado-observe/tracking/overview) 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:
| Case | Example |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **The fact exists only outside the browser** | A QR-code login where the scan happens in your mobile app. The moment of the scan and a scan error live in the app or your backend, so the browser never sees them. |
| **The fact exists only in your backend** | A risk decision, a fraud score or a segment that influences the journey but is never rendered. |
| **Business context Observe cannot know** | Your own [tags](/corbado-observe/tracking/tags), [user references](/corbado-observe/tracking/user) and conversions outside authentication. |
| **You want the semantics guaranteed** | Where a frontend refactor must not be able to silently change how a step is classified. |
| **Native apps** | iOS and Android have no DOM and no WebAuthn browser API to observe. |
Where a custom event needs to join a journey that started in the browser, it is correlated using an ID you already have, such as a challenge or transaction ID, otherwise the Observe session ID.
## 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
| | **Autocapture** | **Custom events** |
| --------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------- |
| Platforms | Web | Web, iOS, Android |
| Integration effort | **One line of code.** Corbado prepares the script for your flows. | **1 to 3 days** for a typical login flow, plus your own testing |
| Time to first insight | Same day | As soon as your first instrumented flow ships |
| Semantics | Derived from observed signals | Explicit: you define flow, touchpoint, spec type and decisions |
| Maintenance | Corbado keeps the mapping current | Your team maintains events as flows change |
| Coverage | Every flow the script sees | Exactly the flows you instrument |
**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](/corbado-observe/tracking/applications) keep them comparable.
**Want to try one flow first?** [Tell us which flow](mailto:support@corbado.com) and we prepare an Autocapture script for it. You add one line, walk the flow and see the data. That is the fastest way to judge whether Observe fits before committing to a full integration.
## 6. Next steps
One script, no event tagging.
Web, iOS and Android SDKs.