How AI Onboarding Works: DOM Observation vs CSS Selectors

The CSS Selector Problem

Every product tour tool built before 2024 works the same way: you point at an element, the tool records a CSS selector, and the tour plays it back later.

It sounds simple. In practice, it's a maintenance nightmare.

CSS selectors are fragile by nature. A developer renames a class, restructures a component, or swaps a div for a section — and every tour step targeting that element silently breaks. The tour still launches, but it can't find its targets. Users see nothing, or worse, see a tooltip pointing at the wrong element.

/* Tour step targeting a button */
#app > div:nth-child(3) > main > div.content > button.save-btn

/* After a refactor... */
#app > div:nth-child(2) > main > section.content > button.primary-action
// ↑ Tour is now broken. No error. Just silence.

Teams using Pendo, Appcues, or WalkMe report spending 2-5 hours per week fixing broken selectors. That's 100-250 hours per year on maintenance that adds zero user value.

The DOM Observation Approach

ActivationKit takes a fundamentally different approach. Instead of recording CSS selectors during authoring, the SDK observes the live DOM at runtime.

On every page load, the SDK extracts the page structure: buttons, inputs, tabs, navigation elements, headings, and interactive controls. It reads their visible text, ARIA labels, roles, and states. This extraction is sent to the API, which builds a semantic model of your application — not a list of CSS paths, but a map of named features and sections.

The core design principle: observe the DOM, never require host cooperation. Your app doesn't need to add data attributes, configure routes, or expose any metadata. The SDK reads what the browser already renders.

Element Resolution by Name, Not by Path

When the AI generates a tour or highlights an element, it references elements by their human-readable name — "Save Button", "Background Color", "Wallet Tab" — not by a CSS selector.

The SDK then resolves that name to a live DOM element using a multi-strategy cascade:

A developer can rename CSS classes, restructure component hierarchies, or even swap frontend frameworks — as long as the button still says "Save", the SDK finds it. This is why ActivationKit tours self-heal instead of breaking.

Self-Healing in Practice

Traditional DAPs have a binary outcome: the selector matches or it doesn't. ActivationKit has a graceful degradation path:

The SDK also detects element states that CSS selectors can't represent: aria-disabled, pointer-events: none, low opacity, and locked CSS classes. When a feature is gated behind a paid tier, the AI doesn't just fail — it explains the limitation and suggests the upgrade path.

Tour Health monitoring in the dashboard tracks resolution success rates. If a name stops resolving, ActivationKit flags it and suggests corrections — before your users notice.

The Three-Tier Decision Pipeline

DOM observation generates rich context. But not every guidance decision needs an LLM call. ActivationKit uses a three-tier pipeline that optimizes for speed and cost:

Tier 1 — Rules (<10ms): Twelve deterministic rules handle predictable patterns. First page visit? Welcome nudge. Idle for 30 seconds? Contextual help prompt. Form abandoned? Encouragement to continue. These fire instantly with zero API cost.

Tier 2 — Cache (<50ms): When a similar question has been asked in the same context before, the cached response is returned. Quality scoring ensures only good responses are reused.

Tier 3 — LLM (500-2000ms): GPT-4o-mini with structured JSON output generates novel guidance. The response includes specific actions — highlight an element, navigate to a section, start a tour — not just text.

In production, approximately 70% of guidance requests resolve at Tier 1 or Tier 2. The LLM handles the long tail of unique questions and on-demand tour generation. Cost per conversation: ~$0.001.

One Script Tag, Full Coverage

Because ActivationKit observes the DOM rather than requiring configuration, installation is a single script tag:

<script>
  ActivationKit('init', {
    apiKey: 'YOUR_API_KEY',
    apiUrl: 'https://api.activationkit.com'
  });
</script>
<script src="https://api.activationkit.com/sdk/nd.js" defer></script>

No npm package. No framework adapter. No route configuration. The SDK auto-discovers your app's structure on the first page load and builds the schema via AI enrichment. Within minutes, the AI can answer questions about your product and generate on-demand tours.

Optional user context (ID, plan tier) enables tier-aware guidance and per-user progress tracking — but the SDK delivers value with zero configuration beyond the script tag itself.

Move Past CSS Selectors

CSS selectors were the best option when product tours were first invented. They're not anymore. DOM observation with AI-powered element resolution is more reliable, requires zero maintenance, and adapts as your product evolves.

Try ActivationKit free — no credit card, no configuration, no tooltip tour builder to learn.