Quick Start

Install and configure the Grovs Web SDK in your project

Upgrading from 1.x? See the 2.0 upgrade guide.

Requirements

A browser environment. The SDK is safe to import during server rendering, but must be configured on the client.
Every origin your app runs on — including http://localhost:<port> for development — registered as a linked domain in the Grovs dashboard. See Registering Domains.

Installation

Until 2.0.0 is on the npm registry, install it from the GitHub release. The package name is still grovs, so imports are unchanged.

Bash

npm install https://github.com/grovs-io/grovs-js/releases/download/2.0.0/grovs-2.0.0.tgz

import Grovs from "grovs";

CommonJS

import is the primary path. From require, the SDK is the default export and the named exports sit alongside it:

const { default: Grovs, GrovsError } = require("grovs");

Script tag

The IIFE build at dist/grovs.global.js exposes window.Grovs. Serve it from your own origin alongside your other assets:

HTML

<script src="/assets/grovs.global.js"></script>
<script>
  Grovs.configure({ apiKey: "your-api-key" });
</script>

Loading it from a public CDN works too, but pin an exact version and add a Subresource Integrity hash. A @2 range resolves to a different file on every patch release, which defeats SRI. The release notes carry the integrity value for each version.

TypeScript

Types ship with the package. No @types/grovs is needed.

Configuration

Call configure once, as early as you can. It resolves true when the SDK has authenticated:

import Grovs from "grovs";
 
const ready = await Grovs.configure({
  apiKey: "your-api-key",
  testEnvironment: false,
  onDeeplink: (payload) => {
    // The page was opened from a Grovs link
    console.log("deep link payload", payload);
  },
  onError: (code, message) => {
    console.error("grovs error", code, message);
  },
});

Then identify the user, if you have one:

Grovs.setUserIdentifier("user-42");
Grovs.setUserAttributes({ plan: "pro", seats: 5 });

Both are safe to call before configure resolves.

Configuration options

Option	Default	Description
`apiKey`	required	Your project API key from the Grovs dashboard.
`testEnvironment`	`false`	`true` targets your project's test environment (its own domain, links, and data); `false` targets production. Use `true` only in development.
`baseURL`	Grovs cloud	Domain of a self-hosted backend, e.g. `"https://sdk.example.com"`. The SDK appends the API path.
`autoTrackScreenViews`	`true`	Fire screen views on single-page-app route changes. See Events & Screen Tracking.
`cookieDomain`	host-only	Set to span subdomains, e.g. `".example.com"`.
`requireConsent`	`false`	Store and send nothing until `grantConsent()` is called. See Privacy & Consent.
`appVersion`	SDK version	Your app's version, reported with the device fingerprint.
`debugLevel`	`"error"`	`"info"`, `"warn"`, or `"error"`.
`messagesTheme`	built-in	Styling for the messages UI. See Messages.
`onDeeplink`	—	Called with the payload when the page was opened from a link.
`onError`	—	Called on every SDK failure with a `GrovsError` code and a message.

configure throws if apiKey is missing. It resolves false without sending anything when requireConsent is true and consent has not been granted, and when called during server rendering. It also resolves false when authentication fails: on a transient failure (no connection, timeout, 429, 5xx) the SDK keeps retrying in the background, on online and every 30 seconds, up to three times; on a permanent failure such as a bad key or an unlinked origin it stops, and you must call configure again after fixing the cause. A configure call superseded by a later one also resolves false.

Calling configure again replaces the previous client. A second call for the same project on the same page load does not emit a second app_open, so React strict mode's double invocation is safe.

Linked domains. The SDK sends its origin (for example https://app.example.com) as an identifier, and the backend compares it exactly against the linked domains configured for your project. A mismatch fails with "This Web app is not configured". The error message contains the exact string the SDK sent — copy it into the dashboard.

Server-side rendering

Importing the SDK during SSR is safe. Calling configure on the server is a no-op that logs and reports networkRequestFailed through onError, once per configure call. Call it on the client instead — in a useEffect, an onMounted hook, or equivalent.

Quick Start

Requirements

Installation

CommonJS

Script tag

TypeScript

Configuration

Configuration options

Server-side rendering

Next steps

See also