Analytics SDK | .git Documentation

Overview

The @git/analytics SDK provides a lightweight, privacy-first interface for capturing product usage data. It automatically handles batching, retries, offline storage, and GDPR-compliant data masking.

ℹ️ Privacy-First by Default

All PII fields are automatically hashed using SHA-256. Sensitive data can be explicitly excluded via the blocklist configuration.

Installation

Install the SDK using your preferred package manager:

bash

# npm
npm install @git/analytics

# yarn
yarn add @git/analytics

# pnpm
pnpm add @git/analytics

Or include via CDN for browser environments:

html

<script src="https://cdn.git.dev/analytics/v1.4.2/analytics.min.js"></script>

Quick Start

Initialize the SDK with your project API key and start tracking immediately:

javascript

import { init, track } from "@git/analytics";

// Initialize once at app bootstrap
const analytics = init({
  writeKey: "pk_live_a1b2c3d4e5f6",
  env: "production",
});

// Track an event
track("signup_completed", {
  method: "github_oauth",
  plan: "pro",
});

identify()

Associate a user with their actions and attributes. Call this once per user, ideally after authentication.

javascript

analytics.identify({
  userId: "usr_9x8k2m",
  traits: {
    email: "dev@example.com",
    company: "Acme Inc",
    role: "admin"
  }
});

track()

Record user actions. Every event automatically includes timestamp, sessionId, and environment metadata.

Parameter	Type	Description
`event`	string	Descriptive event name (kebab-case recommended)
`properties`	object	Optional metadata key-value pairs
`options`	object	Override global config for this call

screen()

Track page or modal views. Automatically enriched with URL, referrer, and screen dimensions.

javascript

analytics.screen("dashboard", {
  tab: "analytics",
  version: 2
});

Configuration

Customize SDK behavior during initialization:

typescript

interface AnalyticsConfig {
  writeKey: string;
  env: "development" | "staging" | "production";
  flushInterval?: number;       // ms between batch sends (default: 3000)
  maxQueueSize?: number;       // max events in memory (default: 100)
  blocklist?: string[];       // fields to automatically redact
  respectDoNotTrack?: boolean; // honor browser DNT flag
}

⚠️ Security Note

Never hardcode production writeKey values in client-side code exposed to the public. Use environment variables or server-side proxies.

Batching & Offline Mode

The SDK automatically queues events when the network is unavailable and flushes them in optimized batches to minimize requests and data transfer.

javascript

// Manually flush queue
await analytics.flush();

// Check offline status
const isOffline = analytics.isOffline();

// Clear local storage cache
analytics.clearCache();

Plugins System

Extend functionality with first-party or community plugins. Plugins can intercept, modify, or route events before transmission.

javascript

import { init } from "@git/analytics";
import { datadogPlugin } from "@git/analytics-plugin-datadog";

init({
  writeKey: "pk_live_...",
  plugins: [
    datadogPlugin({ apiKey: "dd_api_key" })
  ]
});

TypeScript Support

Full type definitions are included. You can generate types from your dashboard for type-safe event tracking:

bash

npx @git/cli gen-types --project my-app --output ./types/analytics.d.ts

FAQ

Does the SDK block the main thread?

No. All network operations are deferred to Web Workers (browser) or background threads (Node.js). Core API calls are synchronous and return immediately.

How is GDPR handled?

The SDK respects respectDoNotTrack, provides reset() for session clearing, and supports consent-based initialization via analytics.waitForConsent().

Can I track events server-side?

Yes. The same package works in Node.js, Deno, and Cloudflare Workers. Server-side tracking automatically includes request IP masking and environment tagging.