API reference

All methods are static on the default export, Grovs.

Imports

import Grovs, { GrovsError, SDK_VERSION } from "grovs";

At a glance

Setup

configure

Grovs.configure(config: GrovsConfig): Promise<boolean>

Creates the client and authenticates. Options: GrovsConfig.

Returns true when authenticated. The false cases: Configuration options.

• Rejects if apiKey is missing.
• Calling it again with the same settings on an authenticated client keeps the client and takes the new callbacks. There's no re-authentication or second smart banner view.
• Different settings, or a client disabled with setEnabled(false), build a new client.

Calls made before configure:

setEnabled

Grovs.setEnabled(enabled: boolean): void

Stops or restarts the SDK. See Disabling the SDK.

grantConsent

Grovs.grantConsent(): Promise<boolean>

Grants consent when configure was called with requireConsent: true. See Privacy & Consent.

• Moves events tracked meanwhile into durable storage, then authenticates.

reset

Grovs.reset(): void

Clears stored identifiers, the session and queued events. Stops tracking until the next configure.

setDebugLevel

Grovs.setDebugLevel(level: "info" | "warn" | "error"): void

Sets the configured client's minimum log level.

• Before configure, it affects only pre-configure warnings. The client starts at the debugLevel option.
• Any value other than "info", "warn" or "error" silences all output.

isAuthenticated

Grovs.isAuthenticated(): boolean

Whether the client is authenticated.

• false until authentication succeeds, after reset(), and while a transient failure retries.
• Turns true when the authenticate request succeeds, slightly before configure resolves.

Deep links

Payloads also reach the onDeeplink callback. See Deep Linking.

lastReceivedPayload

Grovs.lastReceivedPayload(): Record<string, unknown> | null

Gets the most recent deep link payload, or null.

allReceivedPayloadsSinceStartup

Grovs.allReceivedPayloadsSinceStartup(): Record<string, unknown>[]

Gets every payload received since the page loaded.

Users

setUserIdentifier

Grovs.setUserIdentifier(identifier: string | null): void

Sets your identifier for the current user. Safe to call before configure resolves.

setUserAttributes

Grovs.setUserAttributes(attributes: Record<string, unknown> | null): void

Sets attributes describing the current user. Safe to call before configure resolves.

userIdentifier

Grovs.userIdentifier: string | null

The current user identifier.

• Whichever of the local and server values was set wins. Otherwise the server's is adopted.

userAttributes

Grovs.userAttributes: Record<string, unknown> | null

The current user attributes, with the same precedence as userIdentifier.

Links

generateLink

Grovs.generateLink(params: CreateLinkParams): Promise<string | null>

Creates a smart link. Fields: CreateLinkParams. See Link Creation.

Returns the URL, or null on failure. The reason goes to onError.

linkDetails

Grovs.linkDetails(path: string): Promise<Record<string, unknown> | null>

Gets details for a link generated in the current environment, by path.

Returns the details, or null when the path is unknown.

Events

See Events & Screen Tracking.

track

Grovs.track(name: string, properties?: Record<string, unknown>, tags?: string[]): void

Tracks a custom event.

• Refuses reserved names.
• Events can trigger in-app messages.
• Sanitization and limits: Tracking custom events.

trackScreenView

Grovs.trackScreenView(screenName: string, properties?: Record<string, unknown>): void

Tracks a screen view. Names are capped at 255 characters.

setGlobalTags

Grovs.setGlobalTags(tags: string[] | null): void

Sets tags attached to every later event, including system events. Pass null to clear them.

setScreenAliases

Grovs.setScreenAliases(aliases: Record<string, string>): void

Maps URL patterns to dashboard names. See Screen name aliases.

Grovs.setScreenAliases({ "/product/:id": "Product", "/docs/*": "Documentation" });

screenNameProvider

Grovs.screenNameProvider: ((url: URL) => string | "suppress" | "automatic") | null

Resolver consulted first for automatically tracked screens. See Custom resolver.

flush

Grovs.flush(): Promise<void>

Sends the event queue now, ignoring the interval and any server cooldown.

• If a delivery is in progress, it joins that one.
• Resolves immediately without sending before authentication, before attribution resolves, or while consent is pending.

Revenue

logCustomPurchase

Grovs.logCustomPurchase(purchase: CustomPurchase): Promise<boolean>

Logs a purchase. Fields: CustomPurchase. See Revenue.

• Requires a Grovs Enterprise backend.

In-app messages

See In-app messages. Every Grovs.inApp method works before configure and carries over to later configure calls.

inApp.pause

Grovs.inApp.pause(): void

Holds messages back, during a checkout or video, say. The newest highest priority one waits.

inApp.resume

Grovs.inApp.resume(): void

Lets messages show again, starting with the one that waited, if it still qualifies.

inApp.discard

Grovs.inApp.discard(dismiss?: boolean): void   // default false

Drops the waiting message and stays paused. Pass true to also close the message on screen.

inApp.setExcludedScreens

Grovs.inApp.setExcludedScreens(names: string[]): void

Sets screens where no message shows. Messages wait.

• Use tracked screen names, from trackScreenView or automatic tracking.

inApp.setCallbacks

Grovs.inApp.setCallbacks(callbacks: InAppCallbacks): void

Replaces the in-app callbacks. See InAppCallbacks.

inApp.setDebug

Grovs.inApp.setDebug(enabled: boolean): void

Logs, at info level, each campaign considered for an event and why it was skipped.

Smart banners

See Smart banners.

smartBanner.setLinkData

Grovs.smartBanner.setLinkData(data: SmartBannerLinkData): void

Sets the link the banner opens on the current page. Fields: SmartBannerLinkData.

• A call before configure applies once it runs.
• Data over a limit isn't sent, and the banner keeps its default link.

smartBanner.hide

Grovs.smartBanner.hide(): void

Hides the banner on this page only. Not counted as a dismissal.

smartBanner.refresh

Grovs.smartBanner.refresh(): Promise<void>

Runs banner selection again. Never rejects.

Types

GrovsConfig

interface GrovsConfig {
  apiKey: string;
  testEnvironment?: boolean;       // default false
  baseURL?: string;                // default: Grovs cloud
  cookieDomain?: string;           // default: host-only
  autoTrackScreenViews?: boolean;  // default true
  requireConsent?: boolean;        // default false
  appVersion?: string;             // default: SDK version
  debugLevel?: LogLevel;           // default "error"
  messagesTheme?: MessagesTheme;   // deprecated, ignored
  onDeeplink?: (payload: Record<string, unknown>) => void;
  onError?: (code: GrovsError, message: string) => void;
  smartBanner?: boolean;           // default true
}

Options for configure. Descriptions: Configuration options.

CreateLinkParams

interface CreateLinkParams {
  title?: string;
  subtitle?: string;
  imageURL?: string;
  data?: Record<string, unknown>;
  tags?: string[];
  customRedirects?: CustomRedirects;
  showPreviewiOS?: boolean;
  showPreviewAndroid?: boolean;
  copyToClipboardiOS?: boolean;
  copyToClipboardAndroid?: boolean;
  trackingCampaign?: string;
  trackingSource?: string;
  trackingMedium?: string;
}

Options for generateLink. Every field is optional.

CustomRedirects

interface CustomRedirects {
  ios?: { link?: string; openAppIfInstalled?: boolean };
  android?: { link?: string; openAppIfInstalled?: boolean };
  desktop?: { link?: string };
}

Per-platform redirect overrides for generateLink.

CustomPurchase

interface CustomPurchase {
  type: TransactionType;
  priceInCents: number;
  currency: string;
  productID: string;
  startDate?: Date;
  transactionID?: string;
}

Input for logCustomPurchase.

TransactionType

type TransactionType = "buy" | "cancel" | "refund" | "refund_reversed";

The kind of purchase event in CustomPurchase.

GrovsError

enum GrovsError {
  authenticationFailed = 1,
  networkRequestFailed = 2,
  eventDispatchFailed = 3,
  linkGenerationFailed = 4,
  inAppDisplayFailed = 5,
}

Failure categories passed to onError. See Handling SDK errors.

• inAppDisplayFailed (new in 2.1): an in-app message couldn't be drawn, for example HTML blocked by the page's Content-Security-Policy.
• Numeric values match the iOS SDK's GrovsError and are stable.

InAppCallbacks

interface InAppCallbacks {
  beforeShow?: (campaignId: string) => boolean;
  onShown?: (campaignId: string) => void;
  onClicked?: (campaignId: string, buttonId: string | null, payload: Record<string, unknown> | null) => void;
  onDismissed?: (campaignId: string, reason: string) => void;
  onAnswered?: (campaignId: string, value: number | string, comment: string | null) => void;
}

Passed to inApp.setCallbacks.

SmartBannerLinkData

interface SmartBannerLinkData {
  page_path?: string;                  // defaults to the current page's path
  data?: Record<string, unknown>;      // flat: string, number or boolean values
}

Passed to smartBanner.setLinkData.

LogLevel

type LogLevel = "info" | "warn" | "error";

The debugLevel option of GrovsConfig.

ScreenNameProvider (type)

type ScreenNameDecision = string | "suppress" | "automatic";
type ScreenNameProvider = (url: URL) => ScreenNameDecision;

The type of screenNameProvider.

DeeplinkCallback

type DeeplinkCallback = (payload: Record<string, unknown>) => void;

The onDeeplink option of GrovsConfig.

ErrorCallback

type ErrorCallback = (code: GrovsError, message: string) => void;

The onError option of GrovsConfig.

SDK_VERSION

const SDK_VERSION: string   // "2.1"

Sent as the SDK-VERSION header on every request.

Deprecated

Messages inbox methods

Grovs.showMessagesList(): Promise<void>
Grovs.displayAutomaticMessages(): Promise<void>
Grovs.getMessages(page: number): Promise<GrovsMessage[]>
Grovs.numberOfUnreadMessages(): Promise<number>
Grovs.markMessageAsRead(id: number): Promise<boolean>

The messages inbox was removed in 2.1. These methods remain so existing pages keep working. None makes a request. Use in-app messages.

GrovsMessage

import type { GrovsMessage } from "grovs";

An inbox message. Kept for existing imports.

MessagesTheme

import type { MessagesTheme } from "grovs";

configure accepts and ignores it since the inbox was removed. Kept for existing imports.

GrovsV1

import { GrovsV1 } from "grovs";

The 1.x class, also reachable as Grovs.V1 and by constructing the default export. See Upgrading to 2.0.