TourKit
@tour-kit/adoptionAnalytics

Analytics Integration

Adoption analytics integration: automatically send feature usage and nudge interaction events to your analytics provider

Overview

The @tour-kit/adoption package integrates with @tour-kit/analytics to automatically track adoption events. When an analytics provider is configured, events are sent for feature usage, adoption milestones, and nudge interactions.

Setup

Install Analytics Package

pnpm add @tour-kit/analytics

Configure Provider

import { AnalyticsProvider } from '@tour-kit/analytics'
import { AdoptionProvider } from '@tour-kit/adoption'

function App() {
  return (
    <AnalyticsProvider
      plugins={[
        // Your analytics plugins (Segment, Mixpanel, etc.)
      ]}
    >
      <AdoptionProvider features={features}>
        {children}
      </AdoptionProvider>
    </AnalyticsProvider>
  )
}

That's it! Adoption events are now tracked automatically.

Automatic Events

Feature Adopted

Fired when a feature meets adoption criteria:

{
  event: 'Feature Adopted',
  properties: {
    featureId: 'dark-mode',
    featureName: 'Dark Mode',
    category: 'customization',
    useCount: 3,
    daysSinceFirst: 5,
  }
}

Feature Churned

Fired when an adopted feature becomes inactive:

{
  event: 'Feature Churned',
  properties: {
    featureId: 'export',
    featureName: 'Export Data',
    category: 'productivity',
    useCount: 10,
    daysSinceLastUse: 35,
  }
}

Feature Used

Fired every time a feature is used:

{
  event: 'Feature Used',
  properties: {
    featureId: 'search',
    featureName: 'Advanced Search',
    category: 'productivity',
    useCount: 7,
    status: 'exploring',
  }
}

Nudge Shown

Fired when a nudge is displayed:

{
  event: 'Nudge Shown',
  properties: {
    featureId: 'shortcuts',
    featureName: 'Keyboard Shortcuts',
    category: 'productivity',
    priority: 10,
  }
}

Nudge Clicked

Fired when user clicks a nudge:

{
  event: 'Nudge Clicked',
  properties: {
    featureId: 'ai-assist',
    featureName: 'AI Assistant',
    category: 'ai',
  }
}

Nudge Dismissed

Fired when user dismisses a nudge:

{
  event: 'Nudge Dismissed',
  properties: {
    featureId: 'premium',
    featureName: 'Premium Export',
    category: 'export',
  }
}

Manual Event Tracking

useAdoptionAnalytics Hook

For custom analytics:

import { useAdoptionAnalytics } from '@tour-kit/adoption'

function CustomComponent() {
  const analytics = useAdoptionAnalytics()

  const handleAction = () => {
    // Track custom event
    analytics.track('Custom Adoption Event', {
      featureId: 'custom',
      customProperty: 'value',
    })
  }

  return <button onClick={handleAction}>Action</button>
}

The hook returns the analytics context from @tour-kit/analytics:

Prop

Type

Event Builder Functions

Build event objects manually:

import {
  buildFeatureAdoptedEvent,
  buildFeatureChurnedEvent,
  buildFeatureUsedEvent,
  buildNudgeShownEvent,
  buildNudgeClickedEvent,
  buildNudgeDismissedEvent,
} from '@tour-kit/adoption'

// Build event
const event = buildFeatureAdoptedEvent(feature, usage)
// { event: 'Feature Adopted', properties: { ... } }

// Send to your analytics
analytics.track(event.event, event.properties)

Custom Analytics Implementation

Without @tour-kit/analytics

Use provider callbacks for custom analytics:

<AdoptionProvider
  features={features}
  onAdoption={(feature) => {
    // Send to your analytics service
    window.gtag('event', 'feature_adopted', {
      feature_id: feature.id,
      feature_name: feature.name,
      category: feature.category,
    })
  }}
  onChurn={(feature) => {
    window.gtag('event', 'feature_churned', {
      feature_id: feature.id,
      feature_name: feature.name,
    })
  }}
  onNudge={(feature, action) => {
    window.gtag('event', `nudge_${action}`, {
      feature_id: feature.id,
      feature_name: feature.name,
    })
  }}
/>

Tracking Usage Events

Listen to usage events manually:

import { emitFeatureEvent } from '@tour-kit/adoption'

// Emit feature usage event
emitFeatureEvent('feature-id')

// Listen for events
window.addEventListener('feature-used', (event) => {
  const { featureId } = event.detail
  analytics.track('Feature Used', { featureId })
})

Analytics Integrations

Segment

import { AnalyticsProvider, segmentPlugin } from '@tour-kit/analytics'

<AnalyticsProvider
  plugins={[
    segmentPlugin({
      writeKey: 'YOUR_SEGMENT_KEY',
    }),
  ]}
>
  <AdoptionProvider features={features}>
    {children}
  </AdoptionProvider>
</AnalyticsProvider>

Google Analytics

import { AnalyticsProvider, googleAnalyticsPlugin } from '@tour-kit/analytics'

<AnalyticsProvider
  plugins={[
    googleAnalyticsPlugin({
      measurementId: 'G-XXXXXXXXXX',
    }),
  ]}
>
  <AdoptionProvider features={features}>
    {children}
  </AdoptionProvider>
</AnalyticsProvider>

Mixpanel

import { AnalyticsProvider, mixpanelPlugin } from '@tour-kit/analytics'

<AnalyticsProvider
  plugins={[
    mixpanelPlugin({
      token: 'YOUR_MIXPANEL_TOKEN',
    }),
  ]}
>
  <AdoptionProvider features={features}>
    {children}
  </AdoptionProvider>
</AnalyticsProvider>

PostHog

import { AnalyticsProvider, posthogPlugin } from '@tour-kit/analytics'

<AnalyticsProvider
  plugins={[
    posthogPlugin({
      apiKey: 'YOUR_POSTHOG_KEY',
      host: 'https://app.posthog.com',
    }),
  ]}
>
  <AdoptionProvider features={features}>
    {children}
  </AdoptionProvider>
</AnalyticsProvider>

Event Properties Reference

Common Properties

All events include:

{
  featureId: string
  featureName: string
  category?: string
  timestamp: string // ISO 8601
}

Feature Adopted

Additional properties:

{
  useCount: number
  daysSinceFirst: number
  adoptionCriteria: {
    minUses: number
    recencyDays: number
  }
}

Feature Churned

Additional properties:

{
  useCount: number
  daysSinceLastUse: number
  previousStatus: 'adopted'
}

Feature Used

Additional properties:

{
  useCount: number
  status: AdoptionStatus
  isFirstUse: boolean
}

Nudge Events

Additional properties:

{
  priority: number
  description?: string
  premium?: boolean
}

Privacy Considerations

Adoption tracking collects usage data. Ensure compliance with privacy regulations (GDPR, CCPA, etc.):

  • Disclose tracking in your privacy policy
  • Obtain user consent where required
  • Provide opt-out mechanisms
  • Anonymize sensitive data

Disable Tracking

<AdoptionProvider
  features={features}
  // Don't track if user opted out
  onAdoption={userConsent ? handleAdoption : undefined}
  onChurn={userConsent ? handleChurn : undefined}
/>

Anonymize Data

onAdoption={(feature) => {
  analytics.track('Feature Adopted', {
    featureId: hashFeatureId(feature.id), // Hash IDs
    // Omit featureName to avoid PII
  })
}

Debugging

Enable debug mode to log events:

import { AnalyticsProvider } from '@tour-kit/analytics'

<AnalyticsProvider
  plugins={[...]}
  debug={process.env.NODE_ENV === 'development'}
>
  <AdoptionProvider features={features}>
    {children}
  </AdoptionProvider>
</AnalyticsProvider>

Best Practices

  1. Track meaningful events - Don't over-track:
// Good: Track adoption milestones
onAdoption={(feature) => analytics.track('Feature Adopted', { ... })}

// Bad: Track every render
useEffect(() => {
  analytics.track('Component Rendered') // Too noisy
}, [])
  1. Include context in event properties:
onAdoption={(feature) => {
  analytics.track('Feature Adopted', {
    featureId: feature.id,
    category: feature.category,
    userPlan: user.plan, // Useful context
    daysActive: user.daysActive,
  })
}

  1. Use standard event names for cross-platform analysis

  2. Test analytics in development before production

Next Steps

Charts

AdoptionCategoryChart and AdoptionStatusBadge: visualize adoption distribution by category and individual feature status

TypeScript Types

TypeScript types for FeatureConfig, AdoptionState, NudgeRule, UsageThreshold, and the @tour-kit/adoption API surface

On this page

OverviewSetupInstall Analytics PackageConfigure ProviderAutomatic EventsFeature AdoptedFeature ChurnedFeature UsedNudge ShownNudge ClickedNudge DismissedManual Event TrackinguseAdoptionAnalytics HookEvent Builder FunctionsCustom Analytics ImplementationWithout @tour-kit/analyticsTracking Usage EventsAnalytics IntegrationsSegmentGoogle AnalyticsMixpanelPostHogEvent Properties ReferenceCommon PropertiesFeature AdoptedFeature ChurnedFeature UsedNudge EventsPrivacy ConsiderationsDisable TrackingAnonymize DataDebuggingBest PracticesNext Steps