Next.js

This guide covers installing the VEKTIS tracker in a Next.js project using either the App Router (Next.js 13+) or the Pages Router. The recommended path is the App Router; both are supported.

1. Install the package

npm install @vektis-io/tracker

pnpm add @vektis-io/tracker

yarn add @vektis-io/tracker

2. Add your API key

Generate a key at Settings → API Keys in the VEKTIS dashboard, then create or update .env.local:

NEXT_PUBLIC_VEKTIS_KEY=vk_pub_prd_...

Use a publishable key (vk_pub_*) — it’s scoped to event ingest only and safe to ship in your browser bundle. A non-publishable (server-side) key still works today but triggers a debug-mode warning in the browser console, and will become a hard error in a future major version.

Create a small client component that calls init() once on mount, then mount it from your root layout:

"use client";

import { useEffect } from "react";
import * as vektis from "@vektis-io/tracker";

export function VektisTracker() {
  useEffect(() => {
    vektis.init({ apiKey: process.env.NEXT_PUBLIC_VEKTIS_KEY! });
  }, []);
  return null;
}

import { VektisTracker } from "./_components/VektisTracker";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <VektisTracker />
        {children}
      </body>
    </html>
  );
}

Initialize once in pages/_app.tsx:

import { useEffect } from "react";
import type { AppProps } from "next/app";
import * as vektis from "@vektis-io/tracker";

export default function App({ Component, pageProps }: AppProps) {
  useEffect(() => {
    vektis.init({ apiKey: process.env.NEXT_PUBLIC_VEKTIS_KEY! });
  }, []);
  return <Component {...pageProps} />;
}

Call identify() once you know who the user is. The SDK requires an identity before any track() event will be sent.

import * as vektis from "@vektis-io/tracker";

vektis.identify({
  customer_id: "acct_A1",     // your account / organization id
  user_id: "user_123",        // optional — the individual user
});

Place this inside whatever callback fires when your auth provider establishes a session (e.g. inside a useEffect that watches the user state, or in a “session-loaded” hook). See Reset on logout for the matching teardown.

5. Send an event

import * as vektis from "@vektis-io/tracker";

// User used a feature
vektis.track("feature.used", { feature_id: "reports-dashboard" });

// User engaged with a sub-action
vektis.track("feature.engagement", {
  feature_id: "reports-dashboard",
  action: "exported_csv",
  properties: { row_count: 1284 },
});

Event types: feature.used, feature.engagement, feature.first_use, session.active, customer.identified. The feature.* events require a feature_id.

6. Verify the install

In the browser dev console after sign-in:

vektis.getStatus();
// { state: "READY", queueLength: 0, identityCustomerId: "acct_A1", identityUserId: "user_123" }

If state is READY and identityCustomerId matches what you passed, the SDK is wired correctly.

Next steps

Configure CSP — required if your app sends Content-Security-Policy headers
Reset on logout
Troubleshooting — for SDK error codes and common install issues