Documentation Navigation
Official Documentation

PulseMetrics Documentation

Learn how to set up your organization, create telemetry projects, generate API keys, and track daily active users with the lightweight pulsemetrics client SDK.

1. Organization & Account Management

Registering your team, authentication, and security preferences

Registration & Onboarding

To start ingesting daily active user events, first register an organization account on PulseMetrics.

Required Registration Fields:
  • Organization Name: e.g., Apex Innovations
  • Owner Full Name: First & Last name
  • Primary Work Email: For verification & alerts
  • Mobile Phone: Verified contact channel

Authentication & Login

Sign in to the PulseMetrics console using your registered organization email and password. Sessions are securely signed with high-entropy JWTs and refresh tokens.

Session Security: Access tokens expire periodically. Active sessions are automatically kept alive via secure refresh tokens while you work in the console.

Profile & Company Settings

Manage your company profile from Dashboard → Settings.

Editable Attributes:
  • Organization Name: Update the company or workspace display name across projects.
  • Owner First & Last Name: Change administrative contact identity.
  • Secondary Email: Optional fallback email for administrative and billing notifications.
  • Landline Number: Optional 10-digit office phone number.
Locked Attributes (Non-Editable):

Primary Email and Primary Phone Number are permanently verified on registration and cannot be modified from the dashboard to protect organization identity and prevent account takeover.

Security & Password Recovery

Keep your account secure with automated password strength evaluation and OTP recovery.

Password Complexity

Requires at least 8 characters with upper, lower, numbers, and special symbols. The console provides a live visual meter.

6-Digit OTP Reset

If you forget your password, click Forgot password? to receive a time-limited 6-digit verification code to your verified email.

2. Project Management & API Keys

Partitioning applications, lifecycle states, and token security

Creating a New Project

PulseMetrics partitions telemetry by project. Create separate projects for production, staging, internal tools, or different client apps.

How to Create a Project:
  1. Navigate to Dashboard → Projects in the sidebar.
  2. Click the blue + New Project button in the upper-right corner.
  3. Provide a Project Name (e.g. TelemetryPulse Core) and an optional description.
  4. Click Create. Your project is immediately allocated an isolated ingestion pipeline and API Key.

Project Settings & Status Lifecycle

Every project supports dynamic lifecycle state transitions to manage event ingestion without code deploys.

ACTIVE

Normal state. The ingestion engine actively buffers beacons and computes DAU.

PAUSED

Ingestion pauses gracefully. Client beacons are acknowledged but held without counter increment.

ARCHIVED

Project becomes read-only. Historical analytics remain accessible for audit.

Finding & Rotating API Keys

To authenticate telemetry payloads from the pulsemetrics SDK, you need your Project API Key.

Locating Your Project API Key:
  1. Go to Dashboard → Projects and click on your target project.
  2. Click Settings in the navigation header.
  3. Under the Project API key section, view your masked key (e.g. DAU_9670...c2b4).
  4. Click Copy key to copy the key to your clipboard.
Keep this key private: Your Project API key authenticates telemetry beacons for that specific workspace. Store it in environment variables (e.g. NEXT_PUBLIC_DAU_KEY or DAU_API_KEY).

Active Sessions & Device Kill Switch

Navigate to Dashboard → Devices to review all browsers and computers currently authorized to access your account.

Zero-Trust Controls:
  • Device Fingerprints: Inspect client platform (macOS, Windows, Linux) and last active timestamp.
  • Revoke Individual Session: Click Revoke session to immediately invalidate a single suspicious device.
  • Revoke All Other Sessions: Single-click kill switch that terminates all remote refresh tokens across the globe.

3. SDK Integration Guide (pulsemetrics)

Official installation, initialization, and recommended lifecycle patterns

Installing the Package

Install the lightweight pulsemetrics package via your package manager of choice:

npm install pulsemetrics

Centralized Initialization

Create a centralized tracker singleton instance in your project (e.g. lib/dau.ts or utils/dau.js):

lib/dau.ts
import PulseMetrics from "pulsemetrics";

export const dau = new PulseMetrics(
  process.env.NEXT_PUBLIC_DAU_KEY || "YOUR_API_KEY"
);

Recommended Lifecycle Integration Patterns

Daily active users can be tracked effectively at multiple stages of your application lifecycle depending on your architecture:

Pattern 1: Right After Successful LoginAuth Trigger

Call dau.init(userId) right when the user completes login via email, credentials, or OAuth.

import { dau } from "@/lib/dau";

async function handleLogin(credentials) {
  const response = await api.post("/auth/login", credentials);
  const user = response.data.user;

  // Track DAU on login
  await dau.init(user.id);
}
Pattern 2: On Page Refresh / Session Restore (/api/me)SPA & Next.js Rehydration

When logged-in users refresh your SPA or Next.js app, trigger dau.init right after your /api/me session validation.

import { useEffect } from "react";
import { dau } from "@/lib/dau";

export function useSessionRestore() {
  useEffect(() => {
    async function fetchCurrentUser() {
      try {
        const response = await fetch("/api/me");
        if (response.ok) {
          const userData = await response.json();
          // Track DAU on session verify
          await dau.init(userData.id);
        }
      } catch (error) {
        console.error("Session restore error:", error);
      }
    }

    fetchCurrentUser();
  }, []);
}
Pattern 3: Auth Interceptor & Token RefreshHTTP Middleware

Trigger DAU tracking when an expired access token is refreshed in your Axios or fetch interceptor.

import axios from "axios";
import { dau } from "@/lib/dau";

axios.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401) {
      // 1. Refresh token
      const newSession = await refreshAccessToken();

      // 2. Track DAU upon successful re-authentication
      if (newSession?.user?.id) {
        await dau.init(newSession.user.id);
      }

      // 3. Retry original request
      return axios(error.config);
    }
    return Promise.reject(error);
  }
);
Pattern 4: Centralized Inside Auth ContextGlobal Provider

Place dau.init inside your global React AuthProvider so any active authenticated user is automatically tracked.

import React, { createContext, useEffect, useState } from "react";
import { dau } from "@/lib/dau";

export const AuthContext = createContext(null);

export function AuthProvider({ children }) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    if (user?.id) {
      dau.init(user.id).catch(console.error);
    }
  }, [user?.id]);

  return (
    <AuthContext.Provider value={{ user, setUser }}>
      {children}
    </AuthContext.Provider>
  );
}
Pattern 5: Anonymous Traffic & Public Sites (crypto.randomUUID)Public Sites & Blogs

For public websites, documentation, and blogs without authentication. Generates a persistent UUID using crypto.randomUUID() stored in localStorage.

import { useEffect } from "react";
import { dau } from "@/lib/dau";

export function useAnonymousTracker() {
  useEffect(() => {
    // 1. Check or generate anonymous persistent ID in localStorage
    let anonymousId = localStorage.getItem("dau_anon_id");

    if (!anonymousId) {
      anonymousId = crypto.randomUUID();
      localStorage.setItem("dau_anon_id", anonymousId);
    }

    // 2. Track DAU for non-logged-in public visits
    dau.init(anonymousId).catch(console.error);
  }, []);
}

SDK API Reference

new PulseMetrics(apiKey: string)

Creates a new tracker instance. apiKey is the Project API Key obtained from your dashboard Project Settings.

tracker.init(userId: string): Promise<ApiResponse>

Dispatches an asynchronous telemetry beacon associating the user identifier with the rolling 24-hour daily active user window. Returns a Promise resolving to the ingestion response.

Integration in Other Languages (HTTP REST API)

Universal Telemetry Ingestion

If you are building in Python, Go, PHP, or want to make direct network calls without the Node.js SDK, you can track daily active users by sending an HTTP POST request to the PulseMetrics ingestion endpoint.

Required HTTP Headers
  • Content-Type: application/json
  • x-api-key: YOUR_PROJECT_API_KEY (Copy from Project Settings)
Payload Structure

Send a JSON body containing the unique user identifier:

{ "user": "USER_ID" }
curl -X POST "https://api.pulsemetrics.in/api/v1/dau/track" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -d '{"user": "USER_ID"}'
Dynamic User Identification: You can pass a persistent user ID from your auth database (e.g. user.id) or generate an anonymous UUID via crypto.randomUUID() to track unauthenticated visitor retention. Multiple events for the same user identifier within a single 24-hour UTC window are automatically deduplicated.