# API reference > Every public type and method in react-native-grovs-wrapper, including push and in-app messages from 3.1.0. Source: https://docs.grovs.io/docs/sdk/react-native/api-reference Configuration happens natively, in `AppDelegate` and `MainApplication`. See the [Quick Start](https://docs.grovs.io/docs/sdk/react-native/quick-start). ## Imports ```typescript import Grovs from 'react-native-grovs-wrapper'; ``` | Export | Kind | What it is | | ----------------- | ----- | --------------------------------------------------------- | | `Grovs` (default) | class | A singleton `GrovsWrapper` with every method on this page | | `GrovsWrapper` | class | The class behind the default export | | [Types](#types) | type | Every type below, except `Tracking` | ## At a glance | Area | Member | Kind | What it does | | ---------------------- | ----------------------------------------------------------- | --------- | ---------------------------------- | | **Setup** | [`setSDK`](#setsdk) | method | Turns collection on or off | | | [`setDebug`](#setdebug) | method | Sets the native log level | | **Deep links** | [`onDeeplinkReceived`](#ondeeplinkreceived) | method | Listens for resolved links | | | [`markReadyToHandleDeeplinks`](#markreadytohandledeeplinks) | method | Signals JavaScript is ready | | **Users** | [`setIdentifier`](#setidentifier) | method | Sets your ID for the user | | | [`setAttributes`](#setattributes) | method | Sets 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 | | | [`startScreenTracking`](#startscreentracking) | method | Tracks React Navigation routes | | | [`setGlobalTags`](#setglobaltags) | method | Tags added to every event | | | [`setScreenAliases`](#setscreenaliases) | method | Renames screens for the dashboard | | **Revenue** | [`logInAppPurchase`](#loginapppurchase) | method | Logs a store purchase | | | [`logCustomPurchase`](#logcustompurchase) | method | Logs a purchase outside the stores | | **Push notifications** | [`setPushToken`](#setpushtoken) | method | Sets the FCM or APNs token | | | [`handleNotificationOpen`](#handlenotificationopen) | method | Handles a tap from a push library | | | [`isGrovsNotification`](#isgrovsnotification) | method | Checks if Grovs sent a push | | **In-app messages** | [`onInAppMessage`](#oninappmessage) | method | Listens for in-app message events | | | [`pauseInAppMessages`](#pauseinappmessages) | method | Holds messages back | | | [`resumeInAppMessages`](#resumeinappmessages) | method | Lets messages show again | | | [`discardInAppMessages`](#discardinappmessages) | method | Drops the waiting message | | | [`setInAppExcludedScreens`](#setinappexcludedscreens) | method | Screens where no message shows | | | [`setInAppDebugLogging`](#setinappdebuglogging) | method | Logs why campaigns were skipped | | | [`markReadyForInAppEvents`](#markreadyforinappevents) | method | Releases buffered in-app events | | **Types** | [`DeeplinkResponse`](#deeplinkresponse) | interface | A resolved deep link | | | [`Any`](#any) | type | Allowed payload values | | | [`GenerateLinkOptions`](#generatelinkoptions) | interface | Options for `generateLink` | | | [`Tracking`](#tracking) | interface | UTM parameters | | | [`CustomRedirects`](#customredirects) | interface | Per-platform link redirects | | | [`CustomLinkRedirect`](#customlinkredirect) | interface | One platform redirect | | | [`LinkDetails`](#linkdetails-1) | interface | Result of `linkDetails` | | | [`LinkCustomRedirect`](#linkcustomredirect) | interface | A redirect in `LinkDetails` | | | [`InAppMessageEvent`](#inappmessageevent) | type | Event passed to `onInAppMessage` | | | [`InAppDismissReason`](#inappdismissreason) | type | Why a message closed | | | [`InAppPurchase`](#inapppurchase) | interface | Input for `logInAppPurchase` | | | [`NavigationContainerRefLike`](#navigationcontainerreflike) | interface | Ref shape for screen tracking | | | [`LogLevel`](#loglevel) | type | Log verbosity | | | [`TransactionType`](#transactiontype) | type | Buy, cancel or refund | | | [Promise errors](#promise-errors) | type | How promises reject | | **Deprecated** | [`displayMessages`](#displaymessages) | method | Shows nothing | | | [`numberOfUnreadMessages`](#numberofunreadmessages) | method | Always `0` | --- ## Setup ### setSDK Kind: method ```typescript setSDK(enabled: boolean): void ``` Turns collection on or off at runtime, for example when consent changes. See [Privacy & Consent](https://docs.grovs.io/docs/sdk/react-native/privacy). - The wrapper stores the value so native `configure` can read it next launch, then forwards it. - While disabled, the native SDK sends nothing, and these methods reject with `code` `'SDK_DISABLED'`: - [`generateLink`](#generatelink) - [`linkDetails`](#linkdetails) - [`displayMessages`](#displaymessages) - [`numberOfUnreadMessages`](#numberofunreadmessages) - On Android, enabling re-forwards `onStart`, so a launch link from while disabled is delivered. ### setDebug Kind: method ```typescript setDebug(level: LogLevel): void ``` Sets the native SDK [log level](#loglevel): `'info'` for everything, `'error'` for errors only (the default). --- ## Deep links See [Deep Linking](https://docs.grovs.io/docs/sdk/react-native/deep-linking). ### onDeeplinkReceived Kind: method ```typescript onDeeplinkReceived(callback: (data: DeeplinkResponse) => void): { remove: () => void } ``` Registers a listener for resolved links, including deferred links matched after install and tapped Grovs pushes. Gets a [`DeeplinkResponse`](#deeplinkresponse). **Returns** an object with `remove()` to unsubscribe. - The first registration marks JavaScript ready and delivers the launch link. ### markReadyToHandleDeeplinks Kind: method ```typescript markReadyToHandleDeeplinks(): void ``` Tells the native side JavaScript is ready for links. - `onDeeplinkReceived` calls it. You need it only if you register listeners another way. --- ## Users ### setIdentifier Kind: method ```typescript setIdentifier(identifier?: string): void ``` Sets your identifier for the current user, typically your `user_id`. Shown in the dashboard and reports. - Held natively while the SDK is disabled. - Dashboard test in-app messages are matched by this identifier. ### setAttributes Kind: method ```typescript setAttributes(attributes?: { [key: string]: Any }): void ``` Sets attributes of the current user, shown in the dashboard. - Values must be strings, numbers, booleans or flat arrays of those. See [`Any`](#any). - Held while the SDK is disabled. --- ## Links ### generateLink Kind: method ```typescript generateLink(options: GenerateLinkOptions): Promise generateLink( title?: string, subtitle?: string, imageURL?: string, data?: { [key: string]: Any }, tags?: Any[], customRedirects?: CustomRedirects, showPreviewIos?: boolean, showPreviewAndroid?: boolean, tracking?: Tracking, copyToClipboardIos?: boolean, copyToClipboardAndroid?: boolean ): Promise ``` Creates a smart link. Fields: [`GenerateLinkOptions`](#generatelinkoptions). See [Link Creation](https://docs.grovs.io/docs/sdk/react-native/link-creation). **Returns** the URL. - Prefer the options object. The positional form remains for 1.x code. - Rejects while disabled (`'SDK_DISABLED'`) or when the native SDK can't generate the link. See [Promise errors](#promise-errors). ### linkDetails Kind: method · Since 3.1.0 ```typescript linkDetails(path: string): Promise ``` Gets the details of a link generated in the current environment. See [Inspecting a link](https://docs.grovs.io/docs/sdk/react-native/link-creation#inspecting-a-link). | Name | Type | Description | | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ | | `path` | `string` | The part of the link after the domain, without the leading `/` and without a query string, for example `'abc123'`. | **Returns** a [`LinkDetails`](#linkdetails-1). - Rejects with `linkDetails requires a non-empty path` before calling native when `path` is empty or blank. - Rejects while disabled (`'SDK_DISABLED'`), when the link doesn't exist, or when the request fails. --- ## Events See [Events & Screen Tracking](https://docs.grovs.io/docs/sdk/react-native/analytics). ### track Kind: method · Since 3.0 ```typescript track(name: string, properties?: { [key: string]: Any }, tags?: string[]): void ``` Tracks a custom event. - The name can't be empty or a [reserved name](https://docs.grovs.io/docs/sdk/react-native/analytics#event-name-rules). From 3.1.0, that includes the in-app, push and journey event names. - Properties over 8 KB are dropped. Tags cap at 20. - Validation is native, and `track` never throws. See [Tracking custom events](https://docs.grovs.io/docs/sdk/react-native/analytics#tracking-custom-events). ### trackScreenView Kind: method · Since 3.0 ```typescript trackScreenView(screenName: string, properties?: { [key: string]: Any }): void ``` Tracks a screen view. - A repeat of the same screen within one second is dropped natively. ### startScreenTracking Kind: method · Since 3.0 ```typescript startScreenTracking(navigationRef: NavigationContainerRefLike): () => void ``` Reports each distinct React Navigation route change through `trackScreenView`. See [Automatic screen tracking with React Navigation](https://docs.grovs.io/docs/sdk/react-native/analytics#automatic-screen-tracking-with-react-navigation). **Returns** an unsubscribe function. - Reports the current route immediately, so call it from `NavigationContainer`'s `onReady`. - Calling it again drops the previous subscription first. - An invalid ref logs an error and returns a no-op. ```tsx Grovs.startScreenTracking(navigationRef)}> {/* navigators */} ``` ### setGlobalTags Kind: method · Since 3.0 ```typescript setGlobalTags(tags?: string[]): void ``` Sets tags merged onto every later event. Call with no argument to clear them. ### setScreenAliases Kind: method · Since 3.0 ```typescript setScreenAliases(aliases: { [key: string]: string }): void ``` Maps screen names to dashboard names, for example `{ Home: 'Home Page' }`. - Only string values are forwarded. --- ## Revenue See [Revenue](https://docs.grovs.io/docs/sdk/react-native/revenue). ### logInAppPurchase Kind: method ```typescript logInAppPurchase(purchase: InAppPurchase): Promise ``` Logs a store purchase. Each platform reads its own field of [`InAppPurchase`](#inapppurchase) and ignores the other. | Platform | Pass | Resolves | | -------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------ | | iOS | `transactionId`: the StoreKit 2 transaction ID as a decimal string | `false` when the ID can't be parsed or the device runs iOS 14 or earlier | | Android | `originalJson`: the Play Billing purchase JSON | `true` once the native SDK has the JSON | - Rejects before calling native if the current platform's field is missing or, on iOS, not numeric. ### logCustomPurchase Kind: method ```typescript logCustomPurchase( type: TransactionType, priceInCents: number, currency: string, productId: string, startDate?: string ): Promise ``` Logs a purchase, cancellation or refund made outside the app stores. | Name | Type | Description | | -------------- | ----------------- | ------------------------------------------------------ | | `type` | `TransactionType` | [`'buy'`, `'cancel'` or `'refund'`](#transactiontype). | | `priceInCents` | `number` | Price in cents. Becomes an integer natively. | | `currency` | `string` | ISO 4217 code. | | `productId` | `string` | Your product identifier. | | `startDate` | `string` | ISO 8601 without fractional seconds. Defaults to now. | **Returns** `true` once the native SDK has it. --- ## Push notifications ### setPushToken Kind: method ```typescript setPushToken(pushToken?: string): void ``` Sets the push token for push campaigns: the FCM token on Android, the APNs device token as a hex string on iOS. See [Push notifications](https://docs.grovs.io/docs/sdk/react-native/push-notifications). - On iOS you can pass the token natively instead, with `Grovs.setPushToken(deviceToken:)` in `AppDelegate`. - On Android, when Firebase Messaging is in the app, the wrapper fetches the FCM token itself when its native module starts. ### handleNotificationOpen Kind: method · Since 3.1.0 ```typescript handleNotificationOpen(data: { [key: string]: unknown }): Promise ``` Handles a notification tap reported by a push library, from the notification's data payload. The push is then delivered to [`onDeeplinkReceived`](#ondeeplinkreceived) and its open is reported. **Returns** `true` when it was a Grovs push. - Call it for taps only. Calling it when a push is delivered counts each delivery as an open. - On iOS, don't also forward the tap natively with `Grovs.handleNotificationResponse`, or the tap counts twice. - On Android, a tap the launcher intent already handled (matched by `grovs_campaign_id`) isn't handled again. - Resolves `false` for an empty payload without calling native. ### isGrovsNotification Kind: method · Since 3.1.0 ```typescript isGrovsNotification(data: { [key: string]: unknown }): Promise ``` Checks whether Grovs sent a push, without handling it. **Returns** `true` when the payload has a non-empty `grovs_campaign_id`. Resolves `false` for an empty payload. --- ## In-app messages See [In-app messages](https://docs.grovs.io/docs/sdk/react-native/in-app-messages). ### onInAppMessage Kind: method · Since 3.1.0 ```typescript onInAppMessage(callback: (event: InAppMessageEvent) => void): { remove: () => void } ``` Registers a listener for in-app message events. Gets an [`InAppMessageEvent`](#inappmessageevent). **Returns** an object with `remove()` to unsubscribe. - Events from before the first subscription are buffered natively, up to 20 (oldest dropped first), and delivered when you subscribe. - Events with missing or invalid fields are dropped. - The wrapper owns the native in-app delegate (iOS) and listener (Android). Setting your own in native code stops these events. ### pauseInAppMessages Kind: method · Since 3.1.0 ```typescript pauseInAppMessages(): void ``` Holds messages back until [`resumeInAppMessages`](#resumeinappmessages). The newest highest priority message waits. ### resumeInAppMessages Kind: method · Since 3.1.0 ```typescript resumeInAppMessages(): void ``` Lets messages show again, starting with the one that waited, if it still qualifies. ### discardInAppMessages Kind: method · Since 3.1.0 ```typescript discardInAppMessages(opts?: { dismissCurrent?: boolean }): void ``` Drops the waiting message. | Name | Type | Description | | --------------------- | --------- | ------------------------------------------------------ | | `opts.dismissCurrent` | `boolean` | Also close the message on screen. Defaults to `false`. | ### setInAppExcludedScreens Kind: method · Since 3.1.0 ```typescript setInAppExcludedScreens(screens: string[]): void ``` Screens where no message shows. Names match those sent through [`trackScreenView`](#trackscreenview) or [`startScreenTracking`](#startscreentracking). - Non-string entries are dropped. A non-array is treated as an empty list. ### setInAppDebugLogging Kind: method · Since 3.1.0 ```typescript setInAppDebugLogging(enabled: boolean): void ``` Logs, natively, each campaign considered for an event and why it was skipped. Combine with [`setDebug('info')`](#setdebug). ### markReadyForInAppEvents Kind: method · Since 3.1.0 ```typescript markReadyForInAppEvents(): void ``` Tells the native side JavaScript is ready for in-app events and flushes the buffer. - `onInAppMessage` calls it. You need it only if you listen another way. --- ## Types All types are exported from `react-native-grovs-wrapper`, except `Tracking`. Reach it as `GenerateLinkOptions['tracking']`. ### DeeplinkResponse Kind: interface ```typescript interface DeeplinkResponse { link?: string; data?: { [key: string]: Any }; } ``` A resolved deep link, passed to [`onDeeplinkReceived`](#ondeeplinkreceived). | Name | Type | Description | | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | `link` | `string` | The deep link URL that opened the app. Missing for a push campaign without a link. | | `data` | `{ [key: string]: Any }` | Custom payload data attached to the link. For a push, the push's keys merged over the link's data. Optional. | - `link` became optional in 3.1.0. Code that reads `response.link` without a check needs one. - The bridge also sends a `tracking` map with the link's attribution metadata when present. The type doesn't declare it. ### Any Kind: type ```typescript type AnyPrimitive = string | number | boolean; type Any = AnyPrimitive | AnyPrimitive[]; ``` The value type for link `data`, attributes and event properties, and for `DeeplinkResponse.data`. - Nested objects, `null` and `Date` aren't accepted. - On Android, non-`Serializable` values are dropped. ### GenerateLinkOptions Kind: interface · Since 3.0 ```typescript interface GenerateLinkOptions { title?: string; subtitle?: string; imageURL?: string; data?: { [key: string]: Any }; tags?: Any[]; customRedirects?: CustomRedirects; showPreviewIos?: boolean; showPreviewAndroid?: boolean; tracking?: Tracking; copyToClipboardIos?: boolean; copyToClipboardAndroid?: boolean; } ``` 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` | `{ [key: string]: Any }` | Custom payload delivered on deep link open. | | `tags` | `Any[]` | Tags for filtering and analytics. Pass strings: Android converts other values, iOS expects strings. | | `customRedirects` | `CustomRedirects` | Per-platform [redirect overrides](#customredirects). | | `showPreviewIos` | `boolean` | Show the preview page on iOS. `undefined` uses the project default. | | `showPreviewAndroid` | `boolean` | Show the preview page on Android. `undefined` uses the project default. | | `tracking` | `Tracking` | [UTM campaign, source and medium](#tracking). | | `copyToClipboardIos` | `boolean` | Copy the link on the iOS preview page, for [clipboard-assisted deferred deep linking](https://docs.grovs.io/docs/sdk/react-native/deep-linking#clipboard-assisted-deferred-deep-linking). `undefined` uses the project setting. | | `copyToClipboardAndroid` | `boolean` | Same, for Android. | ### Tracking Kind: interface ```typescript interface Tracking { utm_medium?: string; utm_source?: string; utm_campaign?: string; } ``` UTM tracking parameters for link generation. | Name | Type | Description | | -------------- | -------- | ----------------------------------------------- | | `utm_campaign` | `string` | Campaign name, for example `'spring_sale'`. | | `utm_source` | `string` | Traffic source, for example `'in_app'`. | | `utm_medium` | `string` | Marketing medium, for example `'share_button'`. | ### CustomRedirects Kind: interface ```typescript interface CustomRedirects { ios: CustomLinkRedirect; android: CustomLinkRedirect; desktop: CustomLinkRedirect; } ``` Per-platform redirect overrides for [`generateLink`](#generatelink). The type requires all three entries. ### CustomLinkRedirect Kind: interface ```typescript interface CustomLinkRedirect { link: string; open_if_app_installed: boolean; } ``` One platform redirect. With `open_if_app_installed` `true`, the app opens if installed. Otherwise `link` is always used. - Both platforms forward each entry's own flag. In wrapper 3.0.x, Android sent the `ios` flag (new architecture) or `true` (legacy bridge) for `desktop`. ### LinkDetails Kind: interface · Since 3.1.0 ```typescript interface LinkDetails { id?: number | string; name?: string | null; path?: string; title?: string | null; subtitle?: string | null; image?: string | null; access_path?: string; active?: boolean; sdk_generated?: boolean; data?: { [key: string]: unknown } | null; tags?: string[] | null; updated_at?: string; show_preview_ios?: boolean | null; show_preview_android?: boolean | null; ads_platform?: string | null; generated_from_platform?: string | null; tracking_source?: string | null; tracking_medium?: string | null; tracking_campaign?: string | null; visitor_id?: number | null; campaign_id?: number | null; ios_custom_redirect?: LinkCustomRedirect | null; android_custom_redirect?: LinkCustomRedirect | null; desktop_custom_redirect?: LinkCustomRedirect | null; [key: string]: unknown; } ``` A link as the backend returns it, from [`linkDetails`](#linkdetails). Field names are the backend's snake_case. Every field is optional, and new fields may be added. ### LinkCustomRedirect Kind: interface · Since 3.1.0 ```typescript interface LinkCustomRedirect { url?: string | null; open_app_if_installed?: boolean; [key: string]: unknown; } ``` A redirect in [`LinkDetails`](#linkdetails-1). Not the same shape as [`CustomLinkRedirect`](#customlinkredirect), the input to `generateLink`. ### InAppMessageEvent Kind: type · Since 3.1.0 ```typescript type InAppMessageEvent = | { type: 'shown'; campaignId: string } | { type: 'clicked'; campaignId: string; buttonId?: string; payload?: Record } | { type: 'dismissed'; campaignId: string; reason: InAppDismissReason | (string & {}) } | { type: 'answered'; campaignId: string; value: number | string; comment?: string } | { type: 'failed'; campaignId?: string; message: string }; ``` Passed to [`onInAppMessage`](#oninappmessage). Narrow on `type`. | `type` | When | | ----------- | -------------------------------------------------------------------------------------- | | `shown` | The message is on screen. | | `clicked` | A button or the message was tapped. `payload` carries the pairs of a key-value action. | | `dismissed` | The message closed. See [`InAppDismissReason`](#inappdismissreason). | | `answered` | A question was answered. `value` is a number for stars, or the chosen option's ID. | | `failed` | The message couldn't be shown. `campaignId` is set on Android only. | ### InAppDismissReason Kind: type · Since 3.1.0 ```typescript type InAppDismissReason = 'close_button' | 'backdrop' | 'swipe' | 'app' | 'orientation'; ``` Why a message closed. `app` means the SDK or your app closed it. `orientation` means the device turned to an orientation the campaign doesn't allow. `dismissed` events may carry other values later, so keep a default branch. ### InAppPurchase Kind: interface · Since 3.0 ```typescript interface InAppPurchase { transactionId?: string; originalJson?: string; } ``` Input for [`logInAppPurchase`](#loginapppurchase). `transactionId` is read on iOS, `originalJson` on Android. ### NavigationContainerRefLike Kind: interface · Since 3.0 ```typescript interface NavigationContainerRefLike { getCurrentRoute(): { name: string } | undefined; addListener(type: 'state', callback: () => void): () => void; } ``` The shape [`startScreenTracking`](#startscreentracking) needs. - A React Navigation `NavigationContainerRef` satisfies it, so the wrapper doesn't depend on `@react-navigation/native`. ### LogLevel Kind: type ```typescript type LogLevel = 'info' | 'error'; ``` Native log verbosity. Pass to [`setDebug`](#setdebug). ### TransactionType Kind: type ```typescript type TransactionType = 'buy' | 'cancel' | 'refund'; ``` Payment transaction type for [`logCustomPurchase`](#logcustompurchase). | Value | Description | | ---------- | ------------------------------------- | | `'buy'` | A new purchase. | | `'cancel'` | A cancelled subscription or purchase. | | `'refund'` | A refunded transaction. | ### Promise errors Promise methods reject with an `Error` whose message is a fixed prefix plus the native message, and which keeps the native `code` when there is one. | Method | Message prefix | | ------------------------ | -------------------------------------- | | `generateLink` | `Failed to generate link:` | | `linkDetails` | `Failed to get link details:` | | `displayMessages` | `Failed to display messages:` | | `numberOfUnreadMessages` | `Failed to get unread messages count:` | | `logInAppPurchase` | `Failed to log in-app purchase:` | | `logCustomPurchase` | `Failed to log custom purchase:` | | `handleNotificationOpen` | `Failed to handle notification open:` | | `isGrovsNotification` | `Failed to check notification:` | - In wrapper 3.0.x, `logInAppPurchase` and `logCustomPurchase` dropped the native `code`. - The only reliable `code` is `'SDK_DISABLED'`, returned while disabled with [`setSDK(false)`](#setsdk). --- ## Deprecated The messages inbox was removed from the Grovs backend and from the native 3.1 SDKs. [In-app messages](https://docs.grovs.io/docs/sdk/react-native/in-app-messages) replace it. Remove inbox buttons and unread badges. ### displayMessages Kind: method · Inbox removed ```typescript displayMessages(): Promise ``` Shows nothing and resolves. - Rejects with `'SDK_DISABLED'` while disabled. ### numberOfUnreadMessages Kind: method · Inbox removed ```typescript numberOfUnreadMessages(): Promise ``` Always resolves `0`. - Rejects with `'SDK_DISABLED'` while disabled.