API reference

Configuration happens natively, in AppDelegate and MainApplication. See the Quick Start.

Imports

import Grovs from 'react-native-grovs-wrapper';

At a glance

Setup

setSDK

setSDK(enabled: boolean): void

Turns collection on or off at runtime, for example when consent changes. See Privacy & Consent.

• 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
  • linkDetails
  • displayMessages
  • numberOfUnreadMessages
• On Android, enabling re-forwards onStart, so a launch link from while disabled is delivered.

setDebug

setDebug(level: LogLevel): void

Sets the native SDK log level: 'info' for everything, 'error' for errors only (the default).

Deep links

See Deep Linking.

onDeeplinkReceived

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.

Returns an object with remove() to unsubscribe.

• The first registration marks JavaScript ready and delivers the launch link.

markReadyToHandleDeeplinks

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

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

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.
• Held while the SDK is disabled.

Links

generateLink

generateLink(options: GenerateLinkOptions): Promise<string>
 
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<string>

Creates a smart link. Fields: GenerateLinkOptions. See 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.

linkDetails

linkDetails(path: string): Promise<LinkDetails>

Gets the details of a link generated in the current environment. See Inspecting a link.

Returns a LinkDetails.

• 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.

track

track(name: string, properties?: { [key: string]: Any }, tags?: string[]): void

Tracks a custom event.

• The name can't be empty or a reserved name. 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.

trackScreenView

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

startScreenTracking(navigationRef: NavigationContainerRefLike): () => void

Reports each distinct React Navigation route change through trackScreenView. See 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.

<NavigationContainer
  ref={navigationRef}
  onReady={() => Grovs.startScreenTracking(navigationRef)}>
  {/* navigators */}
</NavigationContainer>

setGlobalTags

setGlobalTags(tags?: string[]): void

Sets tags merged onto every later event. Call with no argument to clear them.

setScreenAliases

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.

logInAppPurchase

logInAppPurchase(purchase: InAppPurchase): Promise<boolean>

Logs a store purchase. Each platform reads its own field of InAppPurchase and ignores the other.

• Rejects before calling native if the current platform's field is missing or, on iOS, not numeric.

logCustomPurchase

logCustomPurchase(
    type: TransactionType,
    priceInCents: number,
    currency: string,
    productId: string,
    startDate?: string
): Promise<boolean>

Logs a purchase, cancellation or refund made outside the app stores.

Returns true once the native SDK has it.

Push notifications

setPushToken

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.

• 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

handleNotificationOpen(data: { [key: string]: unknown }): Promise<boolean>

Handles a notification tap reported by a push library, from the notification's data payload. The push is then delivered to 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

isGrovsNotification(data: { [key: string]: unknown }): Promise<boolean>

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.

onInAppMessage

onInAppMessage(callback: (event: InAppMessageEvent) => void): { remove: () => void }

Registers a listener for in-app message events. Gets an 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

pauseInAppMessages(): void

Holds messages back until resumeInAppMessages. The newest highest priority message waits.

resumeInAppMessages

resumeInAppMessages(): void

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

discardInAppMessages

discardInAppMessages(opts?: { dismissCurrent?: boolean }): void

Drops the waiting message.

setInAppExcludedScreens

setInAppExcludedScreens(screens: string[]): void

Screens where no message shows. Names match those sent through trackScreenView or startScreenTracking.

• Non-string entries are dropped. A non-array is treated as an empty list.

setInAppDebugLogging

setInAppDebugLogging(enabled: boolean): void

Logs, natively, each campaign considered for an event and why it was skipped. Combine with setDebug('info').

markReadyForInAppEvents

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

interface DeeplinkResponse {
    link?: string;
    data?: { [key: string]: Any };
}

A resolved deep link, passed to onDeeplinkReceived.

• 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

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

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. Every field is optional.

Tracking

interface Tracking {
    utm_medium?: string;
    utm_source?: string;
    utm_campaign?: string;
}

UTM tracking parameters for link generation.

CustomRedirects

interface CustomRedirects {
    ios: CustomLinkRedirect;
    android: CustomLinkRedirect;
    desktop: CustomLinkRedirect;
}

Per-platform redirect overrides for generateLink. The type requires all three entries.

CustomLinkRedirect

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

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. Field names are the backend's snake_case. Every field is optional, and new fields may be added.

LinkCustomRedirect

interface LinkCustomRedirect {
    url?: string | null;
    open_app_if_installed?: boolean;
    [key: string]: unknown;
}

A redirect in LinkDetails. Not the same shape as CustomLinkRedirect, the input to generateLink.

InAppMessageEvent

type InAppMessageEvent =
    | { type: 'shown'; campaignId: string }
    | { type: 'clicked'; campaignId: string; buttonId?: string; payload?: Record<string, unknown> }
    | { 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. Narrow on type.

InAppDismissReason

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

interface InAppPurchase {
    transactionId?: string;
    originalJson?: string;
}

Input for logInAppPurchase. transactionId is read on iOS, originalJson on Android.

NavigationContainerRefLike

interface NavigationContainerRefLike {
    getCurrentRoute(): { name: string } | undefined;
    addListener(type: 'state', callback: () => void): () => void;
}

The shape startScreenTracking needs.

• A React Navigation NavigationContainerRef satisfies it, so the wrapper doesn't depend on @react-navigation/native.

LogLevel

type LogLevel = 'info' | 'error';

Native log verbosity. Pass to setDebug.

TransactionType

type TransactionType = 'buy' | 'cancel' | 'refund';

Payment transaction type for logCustomPurchase.

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.

• 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).

Deprecated

The messages inbox was removed from the Grovs backend and from the native 3.1 SDKs. In-app messages replace it. Remove inbox buttons and unread badges.

displayMessages

displayMessages(): Promise<void>

Shows nothing and resolves.

• Rejects with 'SDK_DISABLED' while disabled.

numberOfUnreadMessages

numberOfUnreadMessages(): Promise<number>

Always resolves 0.

• Rejects with 'SDK_DISABLED' while disabled.