react-native-overlay-sdk

Android floating bubble overlay SDK — a React Native wrapper around the overlay-sdk Android library.

Installation

npm install react-native-overlay-sdk

Android setup

The SDK needs the SYSTEM_ALERT_WINDOW permission. Add it to your AndroidManifest.xml:

<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

Usage

1. Initialize

Call initialize() once, early in your app (e.g. in your root component or app entry).

import OverlaySdk from 'react-native-overlay-sdk';

await OverlaySdk.initialize();

2. Request overlay permission

Android requires the user to explicitly grant "Display over other apps" permission. Check and request it before showing a bubble.

const hasPermission = await OverlaySdk.hasOverlayPermission();

if (!hasPermission) {
  await OverlaySdk.requestOverlayPermission();
  // User is taken to Android settings. Call showBubble() after they return.
}

3. Show a bubble

await OverlaySdk.showBubble({
  bubbleId: 'support',
  bubbleClickAction: 'OPEN_APP',

  draggable: true,
  edgeMagnet: true,
  safeZone: true,
  persistPosition: true,

  leftMargin: 20,
  rightMargin: 20,
  topMargin: 100,
  bottomMargin: 100,

  initialX: 100,
  initialY: 300,

  bubbleStyle: {
    bubbleSizeDp: 64,
    bubbleColor: '#FF2F80ED',
    iconName: 'assistant_icon',
    removeZoneWidthDp: 128,
    removeZoneHeightDp: 56,
    removeMagnetRadiusDp: 96,
  },
});

4. Hide the bubble

await OverlaySdk.hideBubble();

API

| Method | Returns | Description | |---|---|---| | initialize() | Promise<void> | Initializes the SDK. Call once before any other method. | | hasOverlayPermission() | Promise<boolean> | Returns true if overlay permission is granted. | | requestOverlayPermission() | Promise<void> | Opens Android's "Display over other apps" settings screen. | | showBubble(options) | Promise<void> | Shows a floating bubble with the given options. | | hideBubble() | Promise<void> | Hides the currently shown bubble. |

BubbleOptions

| Field | Type | Description | |---|---|---| | bubbleId | string | Unique identifier for the bubble. | | iconResId | number | Android drawable resource ID for the bubble icon. | | draggable | boolean | Whether the bubble can be dragged. | | edgeMagnet | boolean | Snap bubble to nearest edge when released. | | safeZone | boolean | Keep bubble within safe display area. | | persistPosition | boolean | Persist bubble position across app restarts. | | leftMargin | number | Minimum margin from the left edge (dp). | | rightMargin | number | Minimum margin from the right edge (dp). | | topMargin | number | Minimum margin from the top edge (dp). | | bottomMargin | number | Minimum margin from the bottom edge (dp). | | initialX | number | Initial horizontal position (dp). | | initialY | number | Initial vertical position (dp). | | bubbleStyle | BubbleStyleOptions | Visual style options (see below). | | bubbleClickAction | 'TOGGLE_PANEL' \| 'OPEN_APP' | Action when bubble is tapped. |

BubbleStyleOptions

| Field | Type | Description | |---|---|---| | bubbleSizeDp | number | Bubble diameter in dp. | | bubbleColor | string | Bubble background color (e.g. '#FF2F80ED'). | | iconName | string | Android drawable resource name used as bubble icon. | | removeZoneWidthDp | number | Width of the remove zone in dp. | | removeZoneHeightDp | number | Height of the remove zone in dp. | | removeMagnetRadiusDp | number | Radius for magnet snap into remove zone in dp. |

Error codes

Errors rejected from native methods include these codes:

| Code | Cause | |---|---| | E_NOT_INITIALIZED | showBubble or hideBubble called before initialize(). | | E_PERMISSION_REQUIRED | showBubble called without overlay permission. | | E_INVALID_OPTIONS | Invalid value passed in bubble options. | | E_ACTIVITY_UNAVAILABLE | No foreground activity when requesting permission. | | E_INITIALIZE_FAILED | SDK initialization threw an exception. | | E_SHOW_BUBBLE_FAILED | showBubble threw an unexpected exception. | | E_HIDE_BUBBLE_FAILED | hideBubble threw an unexpected exception. |

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library