add-adoption-tracking

Track feature adoption with @tour-kit/adoption

Use @tour-kit/adoption when the user wants to know which features are being used (and which aren't), nudge users toward unused features, and visualize adoption metrics. It tracks feature usage events, computes adoption status (not_started / exploring / adopted / churned), and ships a dashboard for admins.

Install

pnpm add @tour-kit/adoption @tour-kit/core

Minimal working example

'use client'
import {
  AdoptionProvider,
  IfNotAdopted,
  NewFeatureBadge,
} from '@tour-kit/adoption'

const features = [
  {
    id: 'dark-mode',
    name: 'Dark mode',
    trigger: '#dark-mode-toggle',          // CSS selector — auto-tracks clicks
    adoptionCriteria: { minUses: 3, recencyDays: 30 },
  },
  {
    id: 'export',
    name: 'Export data',
    trigger: { event: 'export:complete' }, // Custom event
    adoptionCriteria: { minUses: 1 },
  },
]

export function App() {
  return (
    <AdoptionProvider features={features}>
      <button id="dark-mode-toggle">
        Toggle dark mode
        <IfNotAdopted featureId="dark-mode">
          <NewFeatureBadge>New!</NewFeatureBadge>
        </IfNotAdopted>
      </button>
    </AdoptionProvider>
  )
}

The badge shows only to users who haven't adopted the feature yet. Once they click the button 3 times within 30 days, adoption status flips to adopted and the badge disappears.

Hooks

import { useFeature, useAdoptionStats, useNudge } from '@tour-kit/adoption'

const { feature, usage, isAdopted, status, trackUsage } = useFeature('export')
const { totalFeatures, adoptedCount, adoptionRate } = useAdoptionStats()
const { currentNudge, queue, show, dismiss } = useNudge()

Call trackUsage() manually if neither selector nor event triggers fit your case.

Components

• <IfAdopted featureId="..." /> / <IfNotAdopted featureId="..." /> — conditional rendering based on adoption
• <NewFeatureBadge> — visual badge for unused features
• <FeatureButton featureId="...">Try export</FeatureButton> — click auto-tracks
• <AdoptionNudge /> — auto-shows nudges for low-adoption features
• <AdoptionDashboard /> — admin view (totals, by-category breakdowns, charts)

Common follow-ups

Pipe events to your analytics

Wrap with <AnalyticsProvider> (from @tour-kit/analytics) — adoption events auto-forward to PostHog/Mixpanel/Segment plugins.

<AnalyticsProvider analytics={analytics}>
  <AdoptionProvider features={features}>
    {/* feature_used, feature_adopted, nudge_shown events auto-tracked */}
  </AdoptionProvider>
</AnalyticsProvider>

Manual event emission

import { emitFeatureEvent } from '@tour-kit/adoption'
emitFeatureEvent('export:complete', { format: 'csv' })

Server-rendered apps

AdoptionProvider is client-only — wrap inside a client boundary. State persists in localStorage keyed by user id (if provided via userContext) or anonymously.

Gotchas

• Trigger types: string = CSS selector (auto-listens for clicks); { event: string } = custom event name on window; both can be combined.
• Recency window: recencyDays defines the rolling window for "still active" — outside it, users churn back to exploring or churned.
• Storage collisions: Uses prefixed storage keys; safe to coexist with tour state.

Reference

• Docs: https://usertourkit.com/docs/adoption
• Dashboard: https://usertourkit.com/docs/adoption/dashboard
• npm: https://www.npmjs.com/package/@tour-kit/adoption