@logfrog/client

Typed browser SDK for LogFrog. Loads the LogFrog widget — analytics, session replay, product updates, feedback, feature flags and support chat — from an npm install instead of a hand-added <script> tag, with full TypeScript types and SSR safety.

This package doesn't bundle the widget; it injects the hosted script (https://api.logfrog.io/widget.js) so you always run the latest version, and gives you a typed facade over it. Calls made before the script finishes loading are queued and replayed on load.

Install

npm install @logfrog/client

Usage

import { logfrog } from "@logfrog/client";

logfrog.init({
  company: "YOUR_COMPANY_ID", // from the dashboard Install page
  features: {
    analytics: true,
    record: { sampleRate: 0.1 }, // session replay (also enable it in project settings)
    updates: true,
  },
});

// Attach the signed-in user (safe to call before or after init):
logfrog.identify({ user_id: "user_123", name: "Ada Lovelace", email: "[email protected]" });

// Custom analytics events:
logfrog.track("checkout_started", { plan: "pro" });

Individual functions are also exported if you prefer named imports:

import { init, identify, track, flag } from "@logfrog/client";

React

Initialize once, in your root component:

import { useEffect } from "react";
import { logfrog } from "@logfrog/client";

export function App() {
  useEffect(() => {
    logfrog.init({ company: "YOUR_COMPANY_ID", features: { analytics: true } });
  }, []);
  // …
}

init is idempotent and a no-op during server-side rendering, so it's safe in effects and frameworks like Next.js.

API

| method | description | | --- | --- | | init(options) | Load the widget and apply config. Idempotent; SSR-safe. | | whenReady() | Promise<void> that resolves once the widget script is live. | | identify(options) | Attach the signed-in user ({ user_id, name?, email?, traits? }). | | track(event, props?) | Record a custom analytics event. | | setTheme(theme) | "light" \| "dark" \| "system". | | open(id?) / openChat() | Open the updates widget / support chat. | | flag(key, fallback?) | Read a feature flag (returns fallback until flags load). | | flags() | Snapshot of all evaluated flags. | | onFlags(cb) | Subscribe to flag updates. | | refreshFlags() | Force a re-evaluation (e.g. after identify). | | stopRecording() | Opt this page out of session recording. | | isRecording() | Whether replay is actively capturing. | | stripeMetadata(extra?) | Metadata to attach to a Stripe Checkout session so revenue links to the visitor. | | reset() | Clear the stored visitor identity (e.g. on logout). |

init options

| option | type | description | | --- | --- | --- | | company | string (required) | Project company id from the dashboard. | | features | object | { updates?, feedback?, suggestions?, support?, analytics?, record? }. All opt-in. | | theme | "light" \| "dark" \| "system" | Widget theme. | | position | "bottom-left" \| "bottom-right" | Launcher position. | | apiOrigin | string | Override the API origin (default https://api.logfrog.io). | | scriptUrl | string | Override the loader script URL. | | nonce | string | CSP nonce applied to the injected <script>. |

Privacy (session replay)

Recording is opt-in and must be enabled in your project settings. Inputs are masked by default; add .lf-mask to mask an element's text, or .lf-block / data-lf-block to exclude an element entirely. Do-Not-Track is respected.

License

MIT