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.
- 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.
Profile & Company Settings
Manage your company profile from Dashboard → Settings.
- 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.
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.
Requires at least 8 characters with upper, lower, numbers, and special symbols. The console provides a live visual meter.
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.
- Navigate to Dashboard → Projects in the sidebar.
- Click the blue + New Project button in the upper-right corner.
- Provide a Project Name (e.g.
TelemetryPulse Core) and an optional description. - 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.
Normal state. The ingestion engine actively buffers beacons and computes DAU.
Ingestion pauses gracefully. Client beacons are acknowledged but held without counter increment.
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.
- Go to Dashboard → Projects and click on your target project.
- Click Settings in the navigation header.
- Under the Project API key section, view your masked key (e.g.
DAU_9670...c2b4). - Click Copy key to copy the key to your clipboard.
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.
- 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:
Centralized Initialization
Create a centralized tracker singleton instance in your project (e.g. lib/dau.ts or utils/dau.js):
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:
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);
}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();
}, []);
}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);
}
);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>
);
}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
Creates a new tracker instance. apiKey is the Project API Key obtained from your dashboard Project Settings.
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)
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.
Content-Type: application/jsonx-api-key: YOUR_PROJECT_API_KEY(Copy from Project Settings)
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"}'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.