Install

Full SDK installation guide: growtoki.com/docs

bun add growtoki

You can also install it with npm, yarn, or pnpm.

JavaScript / TypeScript

import { Growtoki, GrowtokiEvents } from "growtoki";

const growtoki = Growtoki.init({
  apiKey: "gk_project_write_key",
  autoTrackSessions: true,
  autoTrackPageViews: true,
  autoTrackPerformance: true,
  autoTrackErrors: true,
});

growtoki.identify("user_123", { plan: "pro" });
growtoki.track(GrowtokiEvents.signupCompleted, { method: "email" });
growtoki.track(GrowtokiEvents.coreActionCompleted, { action: "created_project" });
growtoki.captureError(new Error("checkout failed"), { route: "/checkout" });
growtoki.track("project_created", { template: "saas_dashboard" });
await growtoki.flush();

React

import { GrowtokiProvider, useGrowtoki } from "growtoki/react";

export function App() {
  return (
    <GrowtokiProvider apiKey={process.env.GROWTOKI_API_KEY} platform="web">
      <Product />
    </GrowtokiProvider>
  );
}

function Product() {
  const growtoki = useGrowtoki();
  growtoki.track("trial_started", { source: "pricing_cta" });
}

React Native

import { GrowtokiProvider, useGrowtoki } from "growtoki/react-native";

export function App() {
  return (
    <GrowtokiProvider apiKey="gk_project_write_key" platform="react-native">
      <HomeScreen />
    </GrowtokiProvider>
  );
}

function HomeScreen() {
  const growtoki = useGrowtoki();

  growtoki.track("screen_viewed", { screen_name: "Home" });
  growtoki.track(GrowtokiEvents.signupStarted);
  growtoki.captureCrash(new Error("root boundary failed"), {
    route: "Home",
  });
}

React Native does not require native modules. Pass a storage adapter, such as AsyncStorage, when you want durable local queues. Sessions rotate after 30 minutes of inactivity by default. Override with sessionTimeoutMs when your app uses a different analytics session window.

Event Contract

The most important API is the event contract. Keep your shared event language in growtoki.events.json at the repository root so SDK code, app code, and growth audits all agree.

Use standard events for common growth moments:

growtoki.track(GrowtokiEvents.signupCompleted, { method: "email" });
growtoki.track(GrowtokiEvents.coreActionCompleted, { action: "created_project" });

Use custom events for product-specific moments:

growtoki.track("project_created", { template: "saas_dashboard" });
growtoki.track("invite_sent", { role: "editor" });

Custom events are allowed by design. Add important ones to growtoki.events.json with a description, properties, category, and growth questions so a daily Growtoki skill can audit coverage and suggest growth work.

API

Client

| Method | Use | | --- | --- | | track(eventName, properties?) | Track any standard or custom product event. | | captureError(error, properties?) | Track a handled client error as error_captured. | | captureCrash(error, properties?) | Track a fatal app crash or error-boundary failure as crash_captured. | | identify(userId, traits?) | Attach events to a known user. | | flush() | Send queued events immediately. | | reset() | Clear local identity and queue state. | | optIn() / optOut() | Resume or pause event collection. | | alias(previousId, nextId) | Connect an old user id to a new one. | | setUserProperties(properties) | Update traits for the current user. |

Convenience methods such as page, screen, performance, and growth.* are available, but track() plus the event contract is the recommended path for simple Codex-readable instrumentation.

Standard Events

Growtoki ships a shared taxonomy so daily recommendations can compare the same moments across apps:

• Activation: signup_started, signup_completed, onboarding_completed, core_action_completed
• Retention: session_started, app_opened, page_viewed, screen_viewed
• Revenue: trial_started, checkout_started, purchase_completed, subscription_started
• Quality: performance_trace, error_captured, crash_captured
• Growth loop: codex_prompt_copied, improvement_shipped, improvement_measured

Use GrowtokiEvents for constants. Use track("your_custom_event") for your own product moments.

Privacy

Sensitive property keys such as email, password, token, secret, authorization, phone, and credit_card are redacted by default before events leave the app.

Growtoki.init({
  apiKey: "gk_project_write_key",
  privacy: {
    blockedPropertyKeys: ["internal_user_note"],
    captureUrlSearchParams: false,
    captureUserAgent: true,
  },
});

Local Development

bun install
bun build
bun test
bun typecheck

License

Open source under the MIT License.