# API reference > Every public type and method in the Grovs Web SDK 2.1. Source: https://docs.grovs.io/docs/sdk/web/api-reference All methods are static on the default export, `Grovs`. ## Imports ```javascript import Grovs, { GrovsError, SDK_VERSION } from "grovs"; ``` | Export | Kind | What it is | | ------------------------------------------------ | -------- | ----------------------------- | | `Grovs` (default) | class | Every method on this page | | [`GrovsError`](#grovserror) | enum | SDK error codes | | [`SDK_VERSION`](#sdk_version) | constant | The SDK version string | | [`GrovsV1`](#grovsv1) | class | The deprecated 1.x API | | [`GrovsConfig`](#grovsconfig) | type | Options for `configure` | | [`DeeplinkCallback`](#deeplinkcallback) | type | The `onDeeplink` callback | | [`ErrorCallback`](#errorcallback) | type | The `onError` callback | | [`LogLevel`](#loglevel) | type | Log verbosity | | [`CreateLinkParams`](#createlinkparams) | type | Options for `generateLink` | | [`CustomRedirects`](#customredirects) | type | Per-platform link redirects | | [`ScreenNameProvider`](#screennameprovider-type) | type | Custom screen name resolver | | [`ScreenNameDecision`](#screennameprovider-type) | type | What the resolver returns | | [`CustomPurchase`](#custompurchase) | type | Input for `logCustomPurchase` | | [`TransactionType`](#transactiontype) | type | Purchase event kind | | [`InAppCallbacks`](#inappcallbacks) | type | In-app message callbacks | | [`SmartBannerLinkData`](#smartbannerlinkdata) | type | Link for the smart banner | | [`GrovsMessage`](#grovsmessage) | type | Deprecated inbox message | | [`MessagesTheme`](#messagestheme) | type | Deprecated inbox theme | ## At a glance | Area | Member | Kind | What it does | | ------------------- | --------------------------------------------------------------------- | --------- | -------------------------------------- | | **Setup** | [`configure`](#configure) | method | Creates the client and authenticates | | | [`setEnabled`](#setenabled) | method | Stops or restarts the SDK | | | [`grantConsent`](#grantconsent) | method | Starts tracking after consent | | | [`reset`](#reset) | method | Clears stored identity and queue | | | [`setDebugLevel`](#setdebuglevel) | method | Sets the minimum log level | | | [`isAuthenticated`](#isauthenticated) | method | Whether the client is authenticated | | **Deep links** | [`lastReceivedPayload`](#lastreceivedpayload) | method | Most recent deep link payload | | | [`allReceivedPayloadsSinceStartup`](#allreceivedpayloadssincestartup) | method | Every payload since page load | | **Users** | [`setUserIdentifier`](#setuseridentifier) | method | Sets your ID for the user | | | [`setUserAttributes`](#setuserattributes) | method | Sets user attributes | | | [`userIdentifier`](#useridentifier) | property | Current user identifier | | | [`userAttributes`](#userattributes) | property | Current user attributes | | **Links** | [`generateLink`](#generatelink) | method | Creates a smart link | | | [`linkDetails`](#linkdetails) | method | Details of a link by path | | **Events** | [`track`](#track) | method | Tracks a custom event | | | [`trackScreenView`](#trackscreenview) | method | Tracks a screen view | | | [`setGlobalTags`](#setglobaltags) | method | Tags added to every event | | | [`setScreenAliases`](#setscreenaliases) | method | Renames URL patterns for the dashboard | | | [`screenNameProvider`](#screennameprovider) | property | Custom resolver for screen names | | | [`flush`](#flush) | method | Sends queued events now | | **Revenue** | [`logCustomPurchase`](#logcustompurchase) | method | Logs a purchase | | **In-app messages** | [`inApp.pause`](#inapppause) | method | Holds messages back | | | [`inApp.resume`](#inappresume) | method | Lets messages show again | | | [`inApp.discard`](#inappdiscard) | method | Drops the waiting message | | | [`inApp.setExcludedScreens`](#inappsetexcludedscreens) | method | Screens where no message shows | | | [`inApp.setCallbacks`](#inappsetcallbacks) | method | Sets in-app callbacks | | | [`inApp.setDebug`](#inappsetdebug) | method | Logs why campaigns were skipped | | **Smart banners** | [`smartBanner.setLinkData`](#smartbannersetlinkdata) | method | Sets the banner's link | | | [`smartBanner.hide`](#smartbannerhide) | method | Hides the banner on this page | | | [`smartBanner.refresh`](#smartbannerrefresh) | method | Runs banner selection again | | **Types** | [`GrovsConfig`](#grovsconfig) | interface | Options for `configure` | | | [`CreateLinkParams`](#createlinkparams) | interface | Options for `generateLink` | | | [`CustomRedirects`](#customredirects) | interface | Per-platform link redirects | | | [`CustomPurchase`](#custompurchase) | interface | Input for `logCustomPurchase` | | | [`TransactionType`](#transactiontype) | type | Purchase event kind | | | [`GrovsError`](#grovserror) | enum | SDK error codes | | | [`InAppCallbacks`](#inappcallbacks) | interface | In-app message callbacks | | | [`SmartBannerLinkData`](#smartbannerlinkdata) | interface | Link for the smart banner | | | [`LogLevel`](#loglevel) | type | Log verbosity | | | [`ScreenNameProvider`](#screennameprovider-type) | type | Custom screen name resolver | | | [`DeeplinkCallback`](#deeplinkcallback) | callback | Gets each deep link payload | | | [`ErrorCallback`](#errorcallback) | callback | Gets each SDK error | | | [`SDK_VERSION`](#sdk_version) | property | The SDK version string | | **Deprecated** | [Messages inbox methods](#messages-inbox-methods) | method | Do nothing | | | [`GrovsMessage`](#grovsmessage) | type | Inbox message | | | [`MessagesTheme`](#messagestheme) | type | Inbox theme, ignored | | | [`GrovsV1`](#grovsv1) | class | The 1.x API | --- ## Setup ### configure Kind: method ```typescript Grovs.configure(config: GrovsConfig): Promise ``` Creates the client and authenticates. Options: [`GrovsConfig`](#grovsconfig). **Returns** `true` when authenticated. The `false` cases: [Configuration options](https://docs.grovs.io/docs/sdk/web/quick-start#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`: | Calls | Effect | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | [`Grovs.inApp`](#in-app-messages) methods, `smartBanner.setLinkData`, `smartBanner.hide` | Applied once `configure` runs | | `setUserIdentifier`, `setUserAttributes` | Work once `configure` is called, before it resolves | | Methods returning a Promise | Resolve an empty value of their type, such as `null` or `false` | | `isAuthenticated`, payload getters, accessors | Return defaults | | Other action methods | No-op. Log a warning, visible only if `setDebugLevel` raised the pre-configure level | ### setEnabled Kind: method ```typescript Grovs.setEnabled(enabled: boolean): void ``` Stops or restarts the SDK. See [Disabling the SDK](https://docs.grovs.io/docs/sdk/web/privacy#disabling-the-sdk). ### grantConsent Kind: method · Since 2.0 ```typescript Grovs.grantConsent(): Promise ``` Grants consent when `configure` was called with `requireConsent: true`. See [Privacy & Consent](https://docs.grovs.io/docs/sdk/web/privacy). - Moves events tracked meanwhile into durable storage, then authenticates. ### reset Kind: method · Since 2.0 ```typescript Grovs.reset(): void ``` Clears stored identifiers, the session and queued events. Stops tracking until the next `configure`. ### setDebugLevel Kind: method ```typescript 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 Kind: method ```typescript 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`](#deeplinkcallback) callback. See [Deep Linking](https://docs.grovs.io/docs/sdk/web/deep-linking). ### lastReceivedPayload Kind: method ```typescript Grovs.lastReceivedPayload(): Record | null ``` Gets the most recent deep link payload, or `null`. ### allReceivedPayloadsSinceStartup Kind: method ```typescript Grovs.allReceivedPayloadsSinceStartup(): Record[] ``` Gets every payload received since the page loaded. --- ## Users ### setUserIdentifier Kind: method ```typescript Grovs.setUserIdentifier(identifier: string | null): void ``` Sets your identifier for the current user. Safe to call before `configure` resolves. ### setUserAttributes Kind: method ```typescript Grovs.setUserAttributes(attributes: Record | null): void ``` Sets attributes describing the current user. Safe to call before `configure` resolves. ### userIdentifier Kind: property ```typescript 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 Kind: property ```typescript Grovs.userAttributes: Record | null ``` The current user attributes, with the same precedence as `userIdentifier`. --- ## Links ### generateLink Kind: method ```typescript Grovs.generateLink(params: CreateLinkParams): Promise ``` Creates a smart link. Fields: [`CreateLinkParams`](#createlinkparams). See [Link Creation](https://docs.grovs.io/docs/sdk/web/link-creation). **Returns** the URL, or `null` on failure. The reason goes to `onError`. ### linkDetails Kind: method · Since 2.0 ```typescript Grovs.linkDetails(path: string): Promise | 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](https://docs.grovs.io/docs/sdk/web/analytics). ### track Kind: method · Since 2.0 ```typescript Grovs.track(name: string, properties?: Record, tags?: string[]): void ``` Tracks a custom event. - Refuses [reserved names](https://docs.grovs.io/docs/sdk/web/in-app-messages#reserved-event-names). - Events can trigger in-app messages. - Sanitization and limits: [Tracking custom events](https://docs.grovs.io/docs/sdk/web/analytics#tracking-custom-events). ### trackScreenView Kind: method · Since 2.0 ```typescript Grovs.trackScreenView(screenName: string, properties?: Record): void ``` Tracks a screen view. Names are capped at 255 characters. ### setGlobalTags Kind: method · Since 2.0 ```typescript Grovs.setGlobalTags(tags: string[] | null): void ``` Sets tags attached to every later event, including system events. Pass `null` to clear them. ### setScreenAliases Kind: method · Since 2.0 ```typescript Grovs.setScreenAliases(aliases: Record): void ``` Maps URL patterns to dashboard names. See [Screen name aliases](https://docs.grovs.io/docs/sdk/web/analytics#screen-name-aliases). ```typescript Grovs.setScreenAliases({ "/product/:id": "Product", "/docs/*": "Documentation" }); ``` ### screenNameProvider Kind: property · Since 2.0 ```typescript Grovs.screenNameProvider: ((url: URL) => string | "suppress" | "automatic") | null ``` Resolver consulted first for automatically tracked screens. See [Custom resolver](https://docs.grovs.io/docs/sdk/web/analytics#custom-resolver). ### flush Kind: method · Since 2.0 ```typescript Grovs.flush(): Promise ``` 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 Kind: method · Since 2.0 ```typescript Grovs.logCustomPurchase(purchase: CustomPurchase): Promise ``` Logs a purchase. Fields: [`CustomPurchase`](#custompurchase). See [Revenue](https://docs.grovs.io/docs/sdk/web/revenue). - Requires a Grovs Enterprise backend. --- ## In-app messages See [In-app messages](https://docs.grovs.io/docs/sdk/web/in-app-messages). Every `Grovs.inApp` method works before `configure` and carries over to later `configure` calls. ### inApp.pause Kind: method · Since 2.1 ```typescript Grovs.inApp.pause(): void ``` Holds messages back, during a checkout or video, say. The newest highest priority one waits. ### inApp.resume Kind: method · Since 2.1 ```typescript Grovs.inApp.resume(): void ``` Lets messages show again, starting with the one that waited, if it still qualifies. ### inApp.discard Kind: method · Since 2.1 ```typescript 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 Kind: method · Since 2.1 ```typescript 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 Kind: method · Since 2.1 ```typescript Grovs.inApp.setCallbacks(callbacks: InAppCallbacks): void ``` Replaces the in-app callbacks. See [`InAppCallbacks`](#inappcallbacks). ### inApp.setDebug Kind: method · Since 2.1 ```typescript 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](https://docs.grovs.io/docs/sdk/web/smart-banners). ### smartBanner.setLinkData Kind: method · Since 2.1 ```typescript Grovs.smartBanner.setLinkData(data: SmartBannerLinkData): void ``` Sets the link the banner opens on the current page. Fields: [`SmartBannerLinkData`](#smartbannerlinkdata). - A call before `configure` applies once it runs. - Data over a [limit](https://docs.grovs.io/docs/sdk/web/smart-banners#point-the-banner-at-the-current-page) isn't sent, and the banner keeps its default link. ### smartBanner.hide Kind: method · Since 2.1 ```typescript Grovs.smartBanner.hide(): void ``` Hides the banner on this page only. Not counted as a dismissal. ### smartBanner.refresh Kind: method · Since 2.1 ```typescript Grovs.smartBanner.refresh(): Promise ``` Runs banner selection again. Never rejects. --- ## Types ### GrovsConfig Kind: interface ```typescript 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) => void; onError?: (code: GrovsError, message: string) => void; smartBanner?: boolean; // default true } ``` Options for [`configure`](#configure). Descriptions: [Configuration options](https://docs.grovs.io/docs/sdk/web/quick-start#configuration-options). ### CreateLinkParams Kind: interface ```typescript interface CreateLinkParams { title?: string; subtitle?: string; imageURL?: string; data?: Record; tags?: string[]; customRedirects?: CustomRedirects; showPreviewiOS?: boolean; showPreviewAndroid?: boolean; copyToClipboardiOS?: boolean; copyToClipboardAndroid?: boolean; trackingCampaign?: string; trackingSource?: string; trackingMedium?: string; } ``` Options for [`generateLink`](#generatelink). Every field is optional. | Name | Type | Description | | ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `title` | `string` | Link preview title. | | `subtitle` | `string` | Link preview subtitle. | | `imageURL` | `string` | Link preview image URL. | | `data` | `Record` | Custom payload delivered when the link is opened. Must be JSON-serializable. | | `tags` | `string[]` | Tags for filtering and analytics. | | `customRedirects` | `CustomRedirects` | Per-platform [redirect overrides](#customredirects). | | `showPreviewiOS` | `boolean` | Show the preview page on iOS. Omit to use the project default. | | `showPreviewAndroid` | `boolean` | Show the preview page on Android. Omit to use the project default. | | `copyToClipboardiOS` | `boolean` | Copy the link on the iOS preview page, so the native SDK can match a fresh install. Omit to use the project setting. | | `copyToClipboardAndroid` | `boolean` | Same, for Android. | | `trackingCampaign` | `string` | UTM campaign, for example `"BlackFriday2025"`. | | `trackingSource` | `string` | UTM source, for example `"newsletter"`. | | `trackingMedium` | `string` | UTM medium, for example `"email"`. | ### CustomRedirects Kind: interface ```typescript interface CustomRedirects { ios?: { link?: string; openAppIfInstalled?: boolean }; android?: { link?: string; openAppIfInstalled?: boolean }; desktop?: { link?: string }; } ``` Per-platform redirect overrides for [`generateLink`](#generatelink). ### CustomPurchase Kind: interface · Since 2.0 ```typescript interface CustomPurchase { type: TransactionType; priceInCents: number; currency: string; productID: string; startDate?: Date; transactionID?: string; } ``` Input for [`logCustomPurchase`](#logcustompurchase). ### TransactionType Kind: type · Since 2.0 ```typescript type TransactionType = "buy" | "cancel" | "refund" | "refund_reversed"; ``` The kind of purchase event in [`CustomPurchase`](#custompurchase). ### GrovsError Kind: enum ```typescript enum GrovsError { authenticationFailed = 1, networkRequestFailed = 2, eventDispatchFailed = 3, linkGenerationFailed = 4, inAppDisplayFailed = 5, } ``` Failure categories passed to `onError`. See [Handling SDK errors](https://docs.grovs.io/docs/sdk/web/deep-linking#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 Kind: interface · Since 2.1 ```typescript interface InAppCallbacks { beforeShow?: (campaignId: string) => boolean; onShown?: (campaignId: string) => void; onClicked?: (campaignId: string, buttonId: string | null, payload: Record | null) => void; onDismissed?: (campaignId: string, reason: string) => void; onAnswered?: (campaignId: string, value: number | string, comment: string | null) => void; } ``` Passed to [`inApp.setCallbacks`](#inappsetcallbacks). | Callback | Called when | | ------------- | -------------------------------------------------------------------------------------------------------------- | | `beforeShow` | A message is about to show. Return `false` to stop it. It gains no view and nothing else shows for that event. | | `onShown` | A message is on screen. | | `onClicked` | The user clicks the message or a button. | | `onDismissed` | A message closes. | | `onAnswered` | An answered message has closed. `value` is a number for stars or the option's ID for a choice. | ### SmartBannerLinkData Kind: interface · Since 2.1 ```typescript interface SmartBannerLinkData { page_path?: string; // defaults to the current page's path data?: Record; // flat: string, number or boolean values } ``` Passed to [`smartBanner.setLinkData`](#smartbannersetlinkdata). ### LogLevel Kind: type ```typescript type LogLevel = "info" | "warn" | "error"; ``` The `debugLevel` option of [`GrovsConfig`](#grovsconfig). ### ScreenNameProvider (type) Kind: type · Since 2.0 ```typescript type ScreenNameDecision = string | "suppress" | "automatic"; type ScreenNameProvider = (url: URL) => ScreenNameDecision; ``` The type of [`screenNameProvider`](#screennameprovider). ### DeeplinkCallback Kind: callback ```typescript type DeeplinkCallback = (payload: Record) => void; ``` The `onDeeplink` option of [`GrovsConfig`](#grovsconfig). ### ErrorCallback Kind: callback ```typescript type ErrorCallback = (code: GrovsError, message: string) => void; ``` The `onError` option of [`GrovsConfig`](#grovsconfig). ### SDK_VERSION Kind: property ```typescript const SDK_VERSION: string // "2.1" ``` Sent as the `SDK-VERSION` header on every request. --- ## Deprecated ### Messages inbox methods Kind: method · Deprecated in 2.1 ```typescript Grovs.showMessagesList(): Promise Grovs.displayAutomaticMessages(): Promise Grovs.getMessages(page: number): Promise Grovs.numberOfUnreadMessages(): Promise Grovs.markMessageAsRead(id: number): Promise ``` The messages inbox was removed in 2.1. These methods remain so existing pages keep working. None makes a request. Use [in-app messages](#in-app-messages). | Method | Now | | -------------------------- | --------------- | | `showMessagesList` | Does nothing | | `displayAutomaticMessages` | Does nothing | | `getMessages` | Resolves `[]` | | `numberOfUnreadMessages` | Resolves `0` | | `markMessageAsRead` | Resolves `true` | ### GrovsMessage Kind: type · Deprecated in 2.1 ```typescript import type { GrovsMessage } from "grovs"; ``` An inbox message. Kept for existing imports. ### MessagesTheme Kind: type · Deprecated in 2.1 ```typescript import type { MessagesTheme } from "grovs"; ``` `configure` accepts and ignores it since the inbox was removed. Kept for existing imports. ### GrovsV1 Kind: class · Deprecated in 2.0 ```typescript import { GrovsV1 } from "grovs"; ``` The 1.x class, also reachable as `Grovs.V1` and by constructing the default export. See [Upgrading to 2.0](https://docs.grovs.io/docs/upgrade-guides/web-2-0).