How It Works

Schema First Tracking 📄

Analytics events can only be tracked as they exist in schema. Schema files are extensible, and are designed to scale from simple to complex codebases.

Supported schema extensions:

• .yaml
• .yml
• .json

YAML Schemas (.yaml / .yml):

JSON schemas (.json):

Voltage schema files are designed to scale:

• Schema files can be arbitrarily broken up and organized inside your project.
• Schemas support flexible metadata for events, groups, & dimensions.
• Event schemas can be extended to support user defined metadata.
• A project can implement as many schemas & trackers as it needs.
• CI integrations allow your CI to read taxonomy data for automation purposes.

Generated Types & Tracking Config ✅

Voltage is typescript first, and uses codegen to generate types & tracking config from your schema files.

voltage.config.js:

export default {
  generates: [
    {
      events: "./analytics/events/events.volt.yaml",
      groups: [
        "./analytics/groups/user-group.volt.yaml",
        "./analytics/groups/team-group.volt.yaml"
      ],
      dimensions: [
        "./analytics/dimensions/user-role-dimensions.volt.yaml",
        "./analytics/dimensions/team-plan-dimensions.volt.yaml"
      ],
      output: "/__analytics_generated__/analytics.ts"
    }
  ]
}

Running the codegen:

npm voltage generate

When creating your tracker, you supply it's generated tracking config, and point it towards your preferred analytics vendor.

import { createAnalyticsTracker } from 'voltage-schema';
import { AnalyticsSchema, trackingConfig } from '/__analytics_generated__/analytics';

// Create a tracker, and integrate with your preferred analytics vendor.
const tracker = createAnalyticsTracker<AnalyticsSchema>(
  trackingConfig,
  {
    onEventTracked: (eventName, { properties, groups, meta }) => {
      // Send event data (pageview, click, etc.) to your preferred analytics service.
    },
    onGroupUpdated: (groupName, properties) => {
      // Send group data (user, team, etc.) to your preferred analytics service.
    },
  }
);

Once your tracker is setup, you can track events with type safety & type ahead results.

Your tracker acts as a lightweight type safe gate check to ensure that your app tracks exactly what it's supposed to track.

Events that pass the gate check are cleared for takeoff. ✈️

"Takeoff" here means that voltage hands events off to a callback that you control, called onEventTracked. This is where you plug-in your preferred analytics vendor.

// Tracking callback
onEventTracked: (eventName, { properties, groups, meta }) => {
  // Send event data to your preferred analytics service.
}

Never Stale Auto Doc 📚

Gone are the days of maintaining an almost-always-stale doc or spreadsheet of your analytics data.

Why the Autodoc Doesn't get Stale:

• Analytics data lives in schema files as an evergreen source of truth.
• Developers edit schema files when making analytics changes.
• The autodoc reads analytics taxonomy from the analytics schema files.
• CI/CD integrations can be used to publish the auto doc each time your app gets updated.

CI/CD Integrations:

• The codegen config file uses .js so that CI can inject env variables.
• The voltage events -- --verbose command outputs all taxonomy data as JSON.
• The voltage-autodoc -- --output-html command outputs HTML for a taxonomy autodoc for self hosting.

Sample Autodoc

Want to see what the autodoc looks like? Check out our sample autodoc to see how Voltage Schema automatically documents your analytics taxonomy.