Beta. In-App Messaging is in beta and open to every Gameball account. Send questions and feedback to support@gameball.co.

Display In-App Messages

Your dashboard campaigns, drawn natively in your React Native app: slide-ups, modals, and full screens, triggered by session start or by the events you already send. In-app messaging needs Gameball React Native SDK 4.0.0 or later. For campaign options, triggers, filters, priority, cooldown, quiet hours, and how the analytics are defined, see In-App Messaging Campaigns.

Requirements

Item	Requirement
Package	`react-native-gameball` 4.0.0 or later. In-app messaging is part of the SDK, so there is no separate package to install
React Native	0.70 or newer. Use 0.71 or newer for correct button spacing in messages, which use the `gap` style
Platforms	iOS 15.0 or newer, Android 7.0 (API 24) or newer
Required peers	`@react-native-async-storage/async-storage`, `react-native-device-info`, `react-native-modal`, `react-native-push-notification-popup`, and `react-native-webview`, the same peers 3.3.1 requires
Optional	`react-native-safe-area-context`, detected at runtime
New runtime dependencies	None. The only new peer is the optional `react-native-safe-area-context`

Install

npm install react-native-gameball@^4.0.0 @react-native-async-storage/async-storage react-native-device-info react-native-modal react-native-push-notification-popup react-native-webview
cd ios && pod install

Upgrading from 3.x? SDK 4.0.0 raises the minimums to iOS 15.0 and Android API 24. Every 3.x call keeps its signature and behavior. Coming from 3.1.x or earlier, also install the required peers listed above. See Migration Notes.

Version 4.0.0 adds five methods (startInAppMessaging, stopInAppMessaging, setOverlayOpen, onInAppMessage, and logPurchase), one read-only property (isInAppMessagingStarted), one component (<GameballInAppMessages />), and a debug option on init.

Mount the Surface

React Native has no window of its own to draw into, so the SDK needs a place in your tree. Mount <GameballInAppMessages /> once, near the root of your app and above your navigator.

App.tsx

import GameballApp, { GameballInAppMessages } from 'react-native-gameball';

export default function App() {
  return (
    <>
      <NavigationContainer>{/* your app */}</NavigationContainer>
      <GameballInAppMessages />
    </>
  );
}

Until it is mounted, nothing draws. The SDK will not count an impression nobody could see, so it holds the message and displays it once a surface exists. If messages never appear, this is the first thing to check. The log says no in-app messaging host mounted yet; deferring.

Slide-ups render in place, so the app underneath stays usable. Modals and full screens render inside a React Native Modal, which puts them above everything your app draws, including a navigator’s own screens, and gives Android’s Back button somewhere to land.

Start Messaging

Three calls, in order.

const app = GameballApp.getInstance();

await app.init({ apiKey: 'YOUR_API_KEY', lang: 'en' });
await app.initializeCustomer({ customerId: 'customer-123' });
await app.startInAppMessaging();

Call init at module load, not from a component effect. It is asynchronous, because it fetches your account’s settings, and every network-facing method refuses to run until it resolves. A child component’s effect runs before its parent’s, so an effect-based init leaves a window in which your app is mounted and interactive while the SDK is not ready.

Awaiting startInAppMessaging is optional. The SDK loads the customer’s message history before it judges any campaign, whether or not you await. The promise resolves once campaigns have synced and the session-start campaign has been evaluated. Events you send before then are not matched against campaigns, so await it before sending an event that should trigger one.

startInAppMessaging takes an explicit customerId if you would rather not rely on the last customer passed to a successful initializeCustomer. You don’t need to stop to switch customers: a new initializeCustomer, or a start with a different customerId, fetches that customer’s campaigns. Call stopInAppMessaging() on logout: it dismisses what is showing, sends pending analytics, and lets go of the customer, so the next start needs a customer again. The device keeps the customer’s message history, so the same customer signing back in is not shown a once-ever message twice. It keeps one customer’s history at a time: when a different customer starts messaging on the device, the previous history is discarded.

Control Display and Actions

Every option is optional. The hooks follow your most recent startInAppMessaging call. sessionTimeoutSeconds is read only when messaging starts for the first time, or for the first time after stopInAppMessaging().

await app.startInAppMessaging({
  // Deep links from a campaign's button or surface.
  onNavigate: (route, args) => navigation.navigate(route, args),

  // 'show' displays it, 'later' holds it, 'discard' drops it.
  beforeDisplay: (message) => (checkoutInProgress ? 'later' : 'show'),

  // Return true to say you handled the action yourself.
  // The click is still recorded either way.
  onAction: (message, button, action) => false,

  // Every message the SDK selects, whatever you then decide.
  onMessage: (message) => analytics.track('gameball_message', { campaignId: message.campaignId }),

  // How long the app can be away and still count as the same session. Default 30 s, read on the first start.
  sessionTimeoutSeconds: 30,
});

A message you hold with 'later' waits until the screen frees up: setOverlayOpen(false), the profile widget or another message closing, or the device rotating. It is not passed to beforeDisplay again, so for a screen such as checkout, setOverlayOpen is the more reliable hold. beforeDisplay and onAction must return a value, not a promise. A message closes after any tap action, whatever onAction returns. While your own modal, drawer, or checkout step is up, tell the SDK and it holds messages until you say the screen is yours again:

app.setOverlayOpen(true);
// … later
app.setOverlayOpen(false);   // A held message displays now, or once your account's minimum interval allows

You don’t need to do this for the Gameball profile widget: messages already wait while it is open and are offered again when it closes.

Actions

A campaign’s surface or button can dismiss, open a URL, navigate to a route, or ask for push permission. onAction sees all of them first.

React Native ships no in-app browser. Without openUrl, both link kinds, external: true and external: false, leave for the system browser through Linking.openURL, so the customer leaves your app and comes back to it suspended, not restarted.

If you bundle a browser, pass openUrl and decide for yourself:

openUrl: async (url, external) => {
  if (external) {
    await Linking.openURL(url);     // The system browser
  } else {
    await InAppBrowser.open(url);   // Your in-app browser
  }
  return true;                      // Opened
}

Once you pass openUrl, it opens every campaign link, both kinds. Return true when the link opened. Returning false does not hand the link back to the SDK: nothing opens, and the log says could not open "<url>". Whatever you do, the SDK only ever opens http, https, mailto, and tel. A campaign carrying javascript:, file:, or your own deep-link scheme is refused and logged, so a campaign cannot launch arbitrary schemes in your app.

Observe Messages

const off = app.onInAppMessage((message) => {
  // Every message the SDK selects, before beforeDisplay decides, including ones that are held or dropped.
});
// later
off();

This is a listener, not a veto. Use beforeDisplay to hold or drop a message. It fires for every listener you register, and a listener that throws is logged rather than allowed to break the display. It fires once, at selection. A held message does not fire again when it finally displays.

Events and Purchases

Nothing extra to wire. Every event you already send is also a trigger, evaluated before the request goes out, so a campaign that fires on add_to_cart needs no new code:

await app.sendEvent({
  customerId: 'customer-123',
  events: { add_to_cart: { price: 1200, category: 'shoes' } },
});

The properties you attach are what the campaign’s filters are matched against. Equality checks are exact and case-sensitive, and a number matches its numeric string, so 1200 equals "1200". contains ignores case. Event names must match exactly, including case. A property the event does not carry never matches, even for a “does not equal” filter. Purchases have their own method. logPurchase sends an event named purchase through sendEvent, so a campaign triggered by purchase can filter on productId, price, currency, quantity, and anything in properties. It works whether or not messaging has started, and takes the same optional callback and sessionToken arguments as sendEvent. If you already send purchase events yourself, switch to logPurchase rather than sending both.

await app.logPurchase({
  customerId: 'customer-123',
  productId: 'sku-001',
  price: 49.99,
  currency: 'USD',
  quantity: 2,                        // Optional, defaults to 1
  properties: { category: 'shoes' },  // Optional, also matched by filters
});

Language and Right-to-Left

A campaign is fetched in one language. The customer’s own preferredLanguage, a two-letter code, wins; without one, the SDK uses the language init was given, then English. setLanguage changes that language for every request from then on, and also saves it as the last initialized customer’s preferredLanguage. A code the SDK does not support falls back to en. Campaigns already synced keep the copy they were fetched with until the next sync. changeLanguage still works but is deprecated in favor of setLanguage.

await app.initializeCustomer({
  customerId: 'customer-123',
  customerAttributes: { preferredLanguage: 'ar' },
});

Mirroring is your app’s business, not the SDK’s. Messages are drawn into whatever layout direction your app lays out in, so an app running under I18nManager.isRTL gets right-aligned copy, mirrored buttons, and the close glyph in the top-left corner. An app that stays left-to-right does not. The SDK never forces a direction on you.

Personalization

Campaign text can carry placeholders such as {player_name}. See In-App Messaging Campaigns for the list. Just before a message with placeholders displays, the SDK fetches the customer’s current values and fills them in. It waits at most 2 seconds and reuses the values for up to a minute, and every event you send clears them so the next message quotes fresh numbers. If the request fails, the SDK uses the last values it stored for the customer. Any placeholder still without a value, including every placeholder when the request times out, is removed rather than shown as raw braces, and the message still displays. Messages with no placeholders skip the fetch. Your hooks receive the message as authored, with its placeholders.

Push Permission

React Native has no notification-permission API of its own, so a campaign that asks for one asks you. Without a requester the SDK logs and closes the message rather than pretending. For example, with react-native-permissions:

requestPushPermission: async () => {
  const { status } = await requestNotifications(['alert', 'sound']);
  return status === 'granted';
}

Storage and Insets

The SDK keeps in-app messaging state in AsyncStorage, a required peer. The customer’s message history, the campaign cache, unsent analytics, and personalization values survive a restart. If storage cannot be read, messaging still runs, starts empty, and logs why. react-native-safe-area-context is optional and resolved at runtime. When it is installed, messages clear the notch and the home indicator, using the insets the device reports at startup. Without it, the SDK falls back to the status-bar height on Android and to zero elsewhere.

If your app’s own insets are the authority, pass them and they win: <GameballInAppMessages insets={useSafeAreaInsets()} />.

Session Tokens

In-app messaging requests carry the SDK’s current session token as X-GB-TOKEN when it has one, and each sync reports your app’s version. The current token is whatever your last initializeCustomer, sendEvent, logPurchase, or showProfile call passed, so pass it on every call if you use session tokens.

Behavior Reference

The campaign rules themselves are described in In-App Messaging Campaigns. This is what they mean in a React Native app.

Topic	In this SDK
Message types	Slide-up, modal, and full-screen campaigns with images. A modal or full screen shows at most two buttons, and a slide-up has none: the whole banner is the tap target. Other message types and video are skipped, and so is a campaign whose event filters are combined with OR, since the SDK matches filters with AND.
Slide-up auto-dismiss	A campaign that names no duration gets 8 seconds, so a banner cannot sit over your app bar indefinitely. A duration of 0 keeps it until dismissed. The clock starts when it paints, not when the trigger fires.
Swipe to dismiss	A slide-up is dragged toward its own edge, up for a top banner and down for a bottom one. A drag the OS cancels springs back.
Android Back	Closes a modal or a full screen, never a slide-up.
Orientation	A full screen authored portrait-only or landscape-only is held until the device is in that orientation, then displays on its own. A message never rotates your app.
Artwork	HTTPS only. Cleartext artwork is refused before any request goes out. Images download into memory when campaigns sync, and a message never draws before its image. A campaign whose image cannot be loaded is passed over and the next eligible campaign shows, rather than a broken card. If the image does not paint within 2 seconds, the message is taken away unshown, no impression is counted, and the campaign can show on its next trigger.
One at a time	A second campaign matching the same trigger waits behind the one on screen. It displays after that message closes and your account’s minimum interval between messages has passed, without the trigger firing again. Only one message waits at a time, and a newer one replaces it. A trigger that fires inside the minimum interval is skipped, not held.
Sessions	A background longer than the session timeout starts a new session on resume: a fresh sync and a session-start evaluation. Shorter, and the session continues. On iOS, the app switcher, an incoming call, or a system prompt counts as leaving.
Sync and cache	If a sync fails, the SDK uses the campaigns it last cached for that customer.
Quiet hours	Judged on the device’s local time.
Analytics	Impressions, clicks, and dismissals are batched and sent within 30 seconds, sooner once 10 are waiting or just before a link or route action runs, and flushed when the app leaves the foreground. A dismissal is only counted when the customer did not engage. Dashboard test sends display normally and are never reported.

Logging and Troubleshooting

Pass debug: true to init for a running commentary prefixed [GameballIAM], showing which campaign was chosen, which was passed over, and why. It defaults to __DEV__, so it is on in development builds and off in release builds.

You see	It means
`no in-app messaging host mounted yet; deferring`	`<GameballInAppMessages />` is not in the tree. Nothing will draw until it is.
`a second in-app messaging host mounted; the first one keeps the screen`	Mount `<GameballInAppMessages />` only once.
`startInAppMessaging ignored: call init({ apiKey }) first`	`startInAppMessaging` ran before `init`. Await `init` first.
`startInAppMessaging ignored: no customerId — pass one or identify a customer first`	Identify a customer first, or pass one. After `stopInAppMessaging()` the SDK deliberately holds no customer.
`start ignored: already running for customer "…"`	`startInAppMessaging` was called again with the same customer. Harmless.
`session start evaluated`	Start finished. The lines before it say what matched or was held.
`trigger ignored: no campaigns loaded`	The event came before the sync finished, or the sync returned no campaigns.
`campaign "N" deferred: <reason>`	The message is waiting. Reasons include `the host overlay is open`, `another message is showing`, and `no presentation surface available`.
`campaign "N" passed over: artwork not ready`	Its image did not download within 5 seconds, or it is served over `http`. The SDK tries again on a later trigger, at most every 30 seconds, and the campaign is eligible once the image arrives.
`artwork "<url>" is served over http and is refused — in-app artwork must be https`	The campaign’s image is not HTTPS. Fix it in the dashboard.
`… cooldown has not elapsed since the last message; suppressed`	Your account’s floor between two displays, set in the dashboard.
`<n> campaign(s) matched but it is inside the quiet-hours window (device local time); suppressed`	The account’s quiet hours cover the device’s local time.
`message "N" needs landscape orientation; deferring`	Working as intended. It will display when the device turns.
`navigate to "<route>" ignored: pass onNavigate to startInAppMessaging()`	Pass `onNavigate` to route campaign links.
Nothing at all	Logging is off. Release builds log only with `debug: true`.

API Reference

Member	Signature	Notes
`startInAppMessaging`	`(options?) => Promise<void>`	Awaiting is optional. Options: `customerId`, `sessionTimeoutSeconds`, `beforeDisplay`, `onAction`, `onNavigate`, `onMessage`, `openUrl`, `requestPushPermission`.
`stopInAppMessaging`	`() => void`	Logout boundary. Dismisses, flushes, forgets the customer, keeps stored state.
`setOverlayOpen`	`(open: boolean) => void`	Holds messages while your own overlay is up. Closing it retries a held message.
`onInAppMessage`	`(listener) => () => void`	Returns its own unsubscribe.
`isInAppMessagingStarted`	`boolean`	Read-only property.
`logPurchase`	`(purchase: Purchase, callback?, sessionToken?) => Promise<boolean>`	Sends a `purchase` event through `sendEvent`. Works whether or not messaging has started.
`<GameballInAppMessages />`	`{ insets?: { top?, bottom? } }`	Mount once, near the root, above your navigator.

init also takes debug?: boolean, which defaults to __DEV__. Types InAppMessage, MessageButton, ClickAction, MessageType, MessageLayout, MessageOrientation, SlidePosition, MessageStyle, ButtonStyle, TextAlign, BeforeDisplay, DisplayDecision, OnAction, StartInAppMessagingOptions, GameballInAppMessagesProps, PresentedMessage, PresentCallbacks, and Purchase are exported from the package root.

Launch Checklist

Initialize at module load

init runs at module load and is awaited before anything else.

Mount the surface

<GameballInAppMessages /> is mounted once, above the navigator.

Start and stop messaging

startInAppMessaging is called after a customer is identified, and stopInAppMessaging() is called on logout.

Wire the hooks

onNavigate if any campaign uses a route action, requestPushPermission if any campaign asks for notifications, and setOverlayOpen bracketing your own modals and checkout steps.

Check storage and insets

AsyncStorage is installed, safe-area insets come from somewhere, and debug is off in release builds.

In-App Messaging Campaigns

Campaign options, triggers, delivery rules, and analytics definitions.

Track Events

Send the events your campaigns are triggered by.

Push Notifications

Reach customers when the app is closed.

Go-Live Checklist

Verify the full React Native integration before release.

Overview

Web & POS Integration

Mobile Integration

How Do I Set Up In-App Messaging in the React Native SDK (v3)?

Display In-App Messages

Requirements

Install

Mount the Surface

Start Messaging

Control Display and Actions

Actions

Observe Messages

Events and Purchases

Language and Right-to-Left

Personalization

Push Permission

Storage and Insets

Session Tokens

Behavior Reference

Logging and Troubleshooting

API Reference

Launch Checklist

In-App Messaging Campaigns

Track Events

Push Notifications

Go-Live Checklist

​Display In-App Messages

​Requirements

​Install

​Mount the Surface

​Start Messaging

​Control Display and Actions

​Actions

​Observe Messages

​Events and Purchases

​Language and Right-to-Left

​Personalization

​Push Permission

​Storage and Insets

​Session Tokens

​Behavior Reference

​Logging and Troubleshooting

​API Reference

​Launch Checklist

​Related Articles

In-App Messaging Campaigns

Track Events

Push Notifications

Go-Live Checklist

Display In-App Messages

Requirements

Install

Mount the Surface

Start Messaging

Control Display and Actions

Actions

Observe Messages

Events and Purchases

Language and Right-to-Left

Personalization

Push Permission

Storage and Insets

Session Tokens

Behavior Reference

Logging and Troubleshooting

API Reference

Launch Checklist

Related Articles