AIMirror Documentation
Learn what AIMirror is showing you, how to read an analysis, and how to add it to your product.
What AIMirror does
AIMirror watches for interaction patterns that may indicate confusion, hesitation, unnecessary effort, or a blocked task. It turns those signals into something useful without asking you to interpret raw analytics.
| AIMirror shows you | Read it as |
|---|---|
| What it noticed | A behaviour or interface problem worth investigating. |
| Why it may matter | The likely friction or task difficulty suggested by the evidence. |
| What to try | A practical direction for repairing the experience and checking whether it improved. |
The Interface view is the supporting map AIMirror builds while doing that work. The Insights view is where the map and behavioural evidence become plain-language problems and suggested fixes.
Installation
Choose either method below. They load the same AIMirror client and collect the same evidence; you do not need to install both.
Option 1: one-line script
The quickest option for any website. Paste this before the closing </body> tag on every page:
<script src="https://cdn.aimirror.dev/aimirror.latest.js" data-key="YOUR_PUBLIC_API_KEY" defer></script>The loader initializes itself. Its client is available as window.AIMirror if you later need to send a named milestone.
Option 2: package SDK
Use the package when AIMirror should be part of your JavaScript or TypeScript build:
npm install @aimirror/sdkimport { createAIMirror } from "@aimirror/sdk/browser";
const aimirror = createAIMirror({
apiBaseUrl: "https://api.aimirror.dev",
publicKey: "YOUR_PUBLIC_API_KEY",
release: "2026.09.08" // optional
});Create the client once in the browser. In applications that render on the server,
call it from the framework's client-only lifecycle hook, such as Svelte's onMount or React's useEffect.
What either installation gives you
| Capability | What you need to do |
|---|---|
| Behaviour and interface states | Nothing else. AIMirror automatically observes non-sensitive interaction and meaningful interface changes. |
| Funnel analysis | Nothing else for automatic detection on eligible plans. Add optional funnel-step markers when you want exact journey names. |
| Task and intent context | Add optional markers only to important controls when you want to tell AIMirror what a person is trying to achieve. |
| Release comparison | Use data-release on the script, or release in the package configuration. |
The script tag or package initialization is the complete loader. Funnel steps and task context are added to the relevant page elements—not crammed into the loader. The examples below work with either installation method.
Event Model (What AIMirror Collects)
AIMirror does not record form input values or passwords. Behavioral, structural, and semantic interaction signals are used to understand how the interface is being experienced.
| Event | Description |
|---|---|
click | Element clicks + metadata (position, element shape, etc.) |
scroll | Scroll depth, direction, and momentum frames |
hover | Hover start/end + total hover duration per element |
input_change | Tracks that a field changed (never records the field value) |
pointer_stop | Micro-hesitation signal (stopped cursor) |
scroll_velocity | Velocity changes used as one signal in friction and reading-pattern analysis |
dom_mutation_batch | Significant DOM updates such as modal, state, or validation changes |
touch_gesture | Mobile gesture signals such as pinch, zoom, and swipe |
interface_state_transition | Semantic transition between learned interface states, including optional task, intent, and release context |
funnel PRO | Your own journey metadata (e.g. "signup_start") — paid feature |
Funnel Tracking PRO
On plans with funnel analysis, the one-line loader can recognise likely journey stages from semantic sections, forms, calls to action, and common signup, pricing, checkout, and confirmation patterns.
For an important journey, give each visible stage a clear name. The label is for humans; the stable ID lets AIMirror recognise the same step across copy changes.
<section
data-funnel-step="Choose a plan"
data-funnel-step-id="choose-plan"
>
...
</section>
AIMirror then observes entry, progression, CTA use, form starts, form submissions, and possible drop-off around those stages. You do not need to manually fire an event for ordinary visible steps.
Route changes and invisible milestones
If a meaningful milestone has no page element—for example, a client-side route completes or payment is confirmed—send it through the client exposed by the loader:
window.AIMirror.client.track("funnel", {
stage: "signup_complete",
plan: "pro_monthly"
});
With the package SDK, send the same milestone through the instance you created:
aimirror.client.track("funnel", {
stage: "signup_complete",
plan: "pro_monthly"
});Use short, stable stage names and include only useful non-sensitive metadata. Funnel evidence helps AIMirror explain where a journey becomes difficult and what part of the experience is worth inspecting.
Session Model
AIMirror groups interaction evidence into anonymous sessions so behavior can be interpreted as a sequence rather than as disconnected event totals.
{
"sessionId": "5dd71c23-9c51-4d2e-8a4a-9a322e2ab1b9",
"projectId": "your-project",
"events": [...],
"startTime": 1712010218412,
"endTime": 1712010225532
}Events remain scoped to the AIMirror project that collected them. The public ChatGPT connector exposes derived insights and aggregate project information, not raw session IDs or event streams.
Learned HCI & Interface State Model
AIMirror's analysis is not based on click and scroll totals alone. The SDK builds a compact interface state model from the semantic states people actually encounter: navigation paths, open dialogs, expanded controls, selected tabs, pressed controls, validation states, current navigation items, and other meaningful UI changes. When that semantic state changes, AIMirror records a transition between the previous state and the new one.
This state-transition layer is important because HCI problems usually appear in a sequence. A single click may be unremarkable; repeated movement between the same two states can instead be evidence of backtracking or recovery. A path that detours away from a declared task can suggest friction. A transition that repeatedly stops at a validation state can be more informative than the raw number of form events.
What becomes part of the analysis
| Context | How AIMirror uses it |
|---|---|
| Interface states | Provides the semantic UI context in which behavior occurred. |
| State transitions | Supports analysis of progression, detours, reciprocal transitions, backtracking, abandonment, and recovery paths. |
| Declared human tasks | Provides explicit design intent: what the person is meant to accomplish and what success looks like. |
| Optional intent markers | Associates a specific interaction with declared intent without asking the AI to guess it. |
| Release context | Shows which application release a state or transition was observed in. AIMirror treats this as temporal association, not proof of causality. |
| Deterministic crawl findings | Lets behavioral evidence corroborate structural and accessibility findings while keeping deterministic evidence distinct from inference. |
The resulting model is visible in each project's Interface view. You do not need to interpret it like a data scientist. Read states as “where people were” and transitions as “where they went next.” Repeated returns, detours, and stopping points give AIMirror evidence to identify a possible problem and suggest what to inspect.
Optional human-task modelling
AIMirror can learn interface states automatically, but you can also declare the human tasks your product is designed to support. Each task can define a start condition, success condition, description, and stable task ID. This gives the analysis engine a high-confidence representation of design intent instead of forcing it to infer intent from behavior alone.
For especially important controls, optional semantic markers can connect an interaction to that task:
<button
data-aim-task="create-account"
data-aim-intent="advance"
>
Continue
</button>These markers are optional. AIMirror still observes normal behavior without them; they simply increase confidence by providing explicit task and intent context where it matters.
Evidence, correlation, and inference
The HCI model is supplied directly to the insight analysis alongside live behavioral evidence and deterministic crawl findings. AIMirror keeps those evidence types separate: an observed transition is not automatically a usability failure, a deterministic finding is not automatically the cause of a behavior, and a release change is not automatically causal. The analysis engine is instructed to label conclusions according to evidence and uncertainty, and to prefer fewer grounded findings over generic UX advice.
AI Insight Objects
AIMirror does the interpretation for you. It combines behavioural signals with interface, task, accessibility, crawl, and release context, then presents each finding in a simple form: what appears to be happening, why it may matter, and what to inspect or change next.
How to read an insight
| What you see | What it means |
|---|---|
| Observation | The problem or behaviour AIMirror noticed. |
| Suggested direction | A practical place to begin investigating or improving the experience. |
| Impact | How much the issue could affect users or an important task. |
| Confidence | How strongly the available evidence supports the finding. It is not a guarantee of cause. |
| Evidence | The behaviour, interface pattern, task, or deterministic finding behind the conclusion. |
Treat an insight as a grounded diagnosis and starting point, not an unquestionable verdict. Confirm the problem in your product, inspect the affected interface, make the smallest useful change, and compare the same path after release.
{
"section": "onboarding",
"category": "navigation",
"observation": "Users repeatedly transition from the plan-selection state back to the comparison state before continuing",
"suggestion": "Clarify the distinction between plans at the decision point and validate the change against the same task path",
"confidence": 0.86,
"impact": "medium",
"linked_tasks": ["choose-plan"],
"provenance": [
{
"kind": "observed",
"source": "sdk",
"label": "Repeated reciprocal state transitions during the choose-plan task",
"confidence": 0.86
}
]
}Depending on the evidence available, insights can be linked to declared tasks and deterministic findings and can preserve provenance such as observed, correlated, inferred, or hypothesis-level evidence. This is what allows AIMirror to move from “what was clicked?” toward “where did the interaction break down, and how strong is the evidence for that conclusion?”
FAQ
Is the Interface State Model a session recording?
No. It is a compact semantic graph of observed UI states and transitions, not captured video or screenshots.
Do I need to define tasks or add HCI annotations?
No. State learning is automatic. Task models and data-aim-task/data-aim-intent markers are optional ways to provide higher-confidence design intent.
Does a reciprocal transition automatically mean the UX is broken?
No. It is a candidate signal for backtracking or recovery. AIMirror combines it with the rest of the available evidence before forming an insight.
Does it use cookies?
The AIMirror SDK does not require cookies for its interaction model.
Does AIMirror record form values or passwords?
No. Input-change telemetry records that an interaction occurred without storing the entered field value.
Can I export my insights?
Yes — JSON/CSV downloads and an API endpoint are available where provided by your plan and product surface.