Role
- Package author
- Native Android implementation
- Documentation
- Release management
Stack
Project summary
The package gives Expo and React Native developers a reusable API for checking overlay permission, opening named bubbles, closing overlays and sharing native state between the host app and Android overlay surfaces.
The problem
Android overlays require special system permission, native services, WindowManager handling and lifecycle coordination. In an Expo application, that complexity is usually outside the normal JavaScript development workflow.
Requirements
- Expose a typed JavaScript API for permission and bubble lifecycle control.
- Bridge React Native code to Kotlin through Expo Modules.
- Support named overlay renderers and native shared numeric values.
- Document SDK compatibility and Android-only constraints clearly.
- Ship a package that can be built, tested and published through repeatable release steps.
Architecture
Your responsibilities
- Public API design
- Kotlin overlay service implementation
- TypeScript types and examples
- Example application validation
- Documentation and npm publishing
Technical implementation
- The TypeScript API exposes permission checks, permission requests, bubble lifecycle helpers, hooks and renderer registration.
- The native side coordinates Android overlay services, launch intents, drag behavior, positioning and host-app reopening.
- Shared overlay values keep numeric state synchronized across JavaScript and native overlay surfaces without moving sensitive data into overlay keys.
Engineering challenges
Permission flow across app and settings
Android overlay permission is granted outside the normal app permission dialog, so the app must recover state after the user returns.
The package exposes explicit permission checks before and after the request flow, keeping the app in control of UI state.
Platform-specific permissions need direct lifecycle thinking instead of pretending they behave like standard runtime permissions.
Overlay lifecycle resilience
Floating interfaces can outlive parts of the host UI, making service cleanup and visible state easy to desynchronize.
Named bubbles, close helpers and state hooks keep overlay visibility explicit and easier to test.
A small public API is stronger when lifecycle boundaries are visible to the developer.
Security and privacy
- The package is Android only and does not run in Expo Go because it includes native Android code.
- Documentation warns developers to use non-sensitive bubble IDs and shared-value keys.
- Secrets, personal data and large app state should remain in the host application's protected storage.
Outcome
- Created a reusable open-source package for Android overlay support in Expo applications.
- Published documentation, version tracks and quick-start examples for developers.
- Established a foundation for future Expo and React Native native-platform tooling.
Lessons learned
- Expo Modules can expose advanced Android capabilities while keeping the JavaScript surface typed and approachable.
- Compatibility notes are part of the product when native SDK versions change.