react-native-plasma

React Native bridge for the Plasma mobile engagement SDK.

This package exposes native Android and iOS functionality to:

• initialize Plasma and manage user identity
• set tags and user properties
• fetch cached/live banner payloads
• fetch and acknowledge in-app popup deliveries
• show/hide native in-app popup UI from React Native

Installation

yarn add react-native-plasma

Peer dependencies used by the banner component:

yarn add react-native-gesture-handler react-native-reanimated react-native-reanimated-carousel

For iOS:

cd ios && pod install

Available functionality

1) SDK lifecycle and user state

• PlasmaAPI.initializePlasma(baseUrl, apiKey)
• PlasmaAPI.setPersonId(personId) — required before any backend call
• PlasmaAPI.setDeviceToken(token)
• PlasmaAPI.setTags(tags)
• PlasmaAPI.plasmaLogout()

setPersonId is not a login call — call it on every app start and every profile refresh, not just after sign-in. Re-asserting the same id costs nothing and re-drives anything an earlier attempt failed to send. Until it is called the SDK has no identity and any backend call raises rather than silently doing nothing.

setDeviceToken and setTags are safe to call first: the value is stored locally, flagged as unsent, and delivered as soon as setPersonId lands. The same retry runs on every initializePlasma, so a write that failed while offline is not lost.

Calling setPersonId with a different id than last time clears everything cached for the previous person — tags, banners, in-app state — so nothing leaks between two people sharing a handset. The device token is kept and re-registered under the new person, since it belongs to the phone rather than to whoever is signed in.

2) Banner APIs

• PlasmaAPI.getBanners(onCacheRetrieved, onResponse)
  • onCacheRetrieved returns locally cached banners first (if any)
  • onResponse returns fresh network banners or an error

UI component:

• PlasmaBannerCarousel

3) In-app popup APIs

In-app popups are pull-based and scoped to a screen: you tell the SDK which screen the user is on, and the server answers with at most one popup — the highest-priority one that user is eligible for right now. There is no list and no queue.

• PlasmaAPI.getInAppPopup(screen, onSuccess, onError) — read-only probe; onSuccess receives the popup or null. Does not advance the user's schedule, so calling it twice returns the same popup.
• PlasmaAPI.showInAppPopup(screen, metadata?, onSuccess?, onError?) — fetch + present natively. Acknowledges the popup once it is actually on screen, which advances the schedule; a fetch that never renders leaves it available for next time.
• PlasmaAPI.markInAppPopupViewed(popupId, onSuccess?, onError?) — advance the schedule by hand. Only needed when you present your own UI instead of showInAppPopup.
• PlasmaAPI.hideInAppPopup()

UI component:

• PlasmaInAppPopup (headless; mount it on a screen and it shows any eligible popup)

showInAppPopup displays native popup UI (Android/iOS) and supports metadata overrides such as button colors. Impressions, dismissals and clicks are reported automatically through the SDK's event logger — you don't report them yourself.

Basic usage

import { PlasmaAPI } from 'react-native-plasma';

PlasmaAPI.initializePlasma('https://your-domain.com', 'your-api-key');
PlasmaAPI.setPersonId('person-123');
PlasmaAPI.setDeviceToken('fcm-or-apns-token');
PlasmaAPI.setTags({ city: 'Bangalore', tier: 'gold' });

// Read-only: what would show on the Home screen, if anything?
PlasmaAPI.getInAppPopup(
  'Home',
  (popup) => console.log('popup', popup), // null when nothing is eligible
  (error) => console.warn(error)
);

// Fetch and present it.
PlasmaAPI.showInAppPopup(
  'Home',
  {
    buttonBackgroundColor: '#2563EB',
    buttonTextColor: '#FFFFFF',
  },
  () => console.log('popup shown'),
  (error) => console.warn(error)
);

Or declaratively — mount it on the screen and forget about it:

import { PlasmaInAppPopup } from 'react-native-plasma';

<PlasmaInAppPopup screen="Home" />;

Exports

• PlasmaAPI (default export also available)
• PlasmaBannerCarousel
• PlasmaInAppPopup
• Types: RawBanner, InAppPopup, PlasmaInAppPopupProps, PlasmaBanner, PlasmaBannerCarouselProps

Local development

Use the bundled sample app under example/.

See example/README.md for contributor setup instructions.