Skip to content

SDK Event Tracking

!!! tip "Quick start" Copy-paste the examples below and you're tracking behavioral events in under 15 minutes. No additional packages required — event tracking is built into @canviq/sdk-js.

Overview

Survey responses tell you what users think. Behavioral events tell you what they actually do. Together, they give your PMF score the context it needs to be actionable.

When you track events through Canviq, the SDK aggregates behavioral signals — feature adoption counts, daily active sessions, and retention curves — and surfaces them alongside your PMF score in the Metrics Dashboard. You can see which features your High-Expectation Customers use most, which cohorts churn before reaching the 40% PMF threshold, and which product moments drive "I'd be very disappointed" responses. Without event data, your PMF score is a number. With it, it becomes a diagnostic.

Installation

The survey SDK includes event tracking. No separate package is required.

npm install @canviq/sdk-js

!!! info "Bundle size" The full SDK — survey display and event tracking combined — is ≤ 20 KB gzipped.

Track Your First Event

Step 1 — Initialize the SDK

import { CanviqSDK } from '@canviq/sdk-js'

const canviq = CanviqSDK.init({ key: 'sk_live_...' })

Get your key from Admin → Settings → API Keys.

Step 2 — Track an event

canviq.track('button_clicked', { button: 'upgrade' })

That's it. The event name (button_clicked) and the current date are recorded. The properties object provides context in your codebase but is not stored on Canviq servers (see Privacy and Data below).

React example

import { useEffect } from 'react'
import { CanviqSDK } from '@canviq/sdk-js'

const canviq = CanviqSDK.init({ key: 'sk_live_...' })

function PricingPage() {
  useEffect(() => {
    canviq.track('pricing_page_viewed')
  }, [])

  return <div>...</div>
}

import { CanviqSDK } from '@canviq/sdk-js'

const canviq = CanviqSDK.init({ key: 'sk_live_...' })

function UpgradeButton() {
  const handleClick = () => {
    canviq.track('button_clicked', { button: 'upgrade' })
    // your upgrade logic here
  }

  return <button onClick={handleClick}>Upgrade</button>
}

Identify Users

Associate events with a specific user so Canviq can build per-user retention curves and HXC profiles.

canviq.identify('user-opaque-id')

!!! warning "Pass an opaque ID — never an email or name" identify() accepts an internal user ID only. Canviq applies HMAC-SHA256 on top of whatever you pass — the original value is never stored in plain text on our servers. Use your database's primary key (e.g., usr_a1b2c3) or a UUID, not a human-readable identifier.

Call identify() once per session, as soon as the user is authenticated:

// After login
canviq.identify('usr_a1b2c3d4')

import { useEffect } from 'react'

function App({ user }) {
  useEffect(() => {
    if (user?.id) {
      canviq.identify(user.id)
    }
  }, [user?.id])

  return <YourApp />
}

Set Your North Star Metric

Designate one event as your North Star — the action that best represents value delivered to your users.

canviq.setNorthStar('purchase_completed')

The North Star event is displayed prominently on your Canviq Metrics Dashboard as the primary health indicator. It appears above all other event metrics and is used to correlate PMF score movement with product outcomes. Choose an event that represents a completed, meaningful user action (e.g., report_exported, project_published, integration_connected) rather than a passive one (e.g., page_viewed).

Call setNorthStar() once during SDK initialization, not on every event.

What Canviq Tracks Automatically

Session detection only. The SDK tracks whether a user had any activity on a given calendar day. This single signal powers WAU% computation and the retention curve in your dashboard.

No page views, clicks, navigation events, or network requests are auto-tracked. Every event in Canviq is something you explicitly called canviq.track() for. This is a deliberate design choice: you own the signal quality, and your users aren't being profiled beyond what you choose to measure.

Privacy and Data

  • No raw events are stored. Events are aggregated server-side (daily active counts, per-feature counts) and the raw payloads are discarded immediately after aggregation. Canviq cannot reconstruct a user's event history.
  • User IDs are hashed. The value you pass to identify() is hashed with HMAC-SHA256 using a per-organization secret before it is written to any database. The original ID is never stored in plain text.
  • Event properties are not stored. The properties object you pass to track() is used only for client-side context. Only the event name and date are counted server-side.
  • Session IDs are ephemeral. Session IDs are generated client-side as UUID v4 values and are not persisted between page loads. They are used only to deduplicate events within a single session before transmission.

Viewing Your Behavioral Data

All event data surfaces in the Canviq Metrics Dashboard at /admin/pmf:

  • WAU% — Weekly active users as a percentage of your total identified user base
  • Feature adoption — Event counts by name, showing which features are used and by which segments
  • Retention curves — Day-N retention computed from session activity, broken out by cohort and persona
  • North Star trend — Your designated North Star event plotted over time alongside your PMF score

Use the dashboard to correlate behavioral patterns with your PMF score. When your score stagnates, the adoption breakdown will usually point to the feature gap or onboarding friction causing it.

What's Next