@bubblsdk/react-native-sdk 4.1.7 → 5.0.0-alpha.2

package/BubblReactNativeSdk.podspec

@@ -1,17 +1,37 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+# The iOS side of @bubblsdk/react-native-sdk: the TurboModule (ios/) and the Bubbl iOS SDK it
+# drives, built together as one module. The SDK's sources (BubblCore, BubblSDK and BubblLaunch)
+# are carried in the package, in ios-sdk/, copied from renewed-sdk/ios by
+# scripts/sync-ios-sources.mjs: there's no BubblSDK pod for 5.0 (CocoaPods trunk goes read-only).
 Pod::Spec.new do |s|
   s.name = 'BubblReactNativeSdk'
-  s.version = '4.1.7'
-  s.summary = 'React Native wrapper for Bubbl SDK v3 native Android and iOS cores.'
+  s.version = package['version']
+  s.summary = 'Bubbl for React Native: geofenced and scheduled notifications, surveys and analytics.'
   s.homepage = 'https://bubbl.tech'
-  s.license = { :type => 'Commercial', :text => 'Copyright Bubbl. All rights reserved.' }
+  s.license = { :type => 'Apache-2.0', :file => 'LICENSE' }
   s.author = { 'Bubbl' => 'engineering@bubbl.tech' }
-  s.source = { :git => 'https://github.com/bubbl-platform/renewed-sdk.git', :tag => s.version.to_s }
+  s.source = { :git => 'https://github.com/bubbl-platform/renewed-sdk.git', :tag => "v#{s.version}" }
 
-  s.platform = :ios, '15.0'
+  # iOS 13 and up install it (React Native's own floor, when its Podfile helper is loaded); Bubbl
+  # runs on iOS 17 and up and does nothing below (Bubbl.isSupported).
+  s.platforms = { :ios => defined?(min_ios_version_supported) ? min_ios_version_supported : '13.0' }
   s.swift_version = '5.9'
-  s.source_files = 'ios/**/*.{h,m,mm,swift}'
-  s.static_framework = true
+  s.source_files = 'ios/**/*.{h,m,mm,swift}', 'ios-sdk/**/*.{h,m,swift}'
+  # BubblLaunch's C function, called from the SDK's Swift in the same module.
+  s.public_header_files = 'ios-sdk/BubblLaunch/include/*.h'
+  # The iOS SDK's privacy manifest (what its Swift package ships as a resource), in a bundle of its
+  # own so Xcode's privacy report finds it in the app.
+  s.resource_bundles = { 'BubblSDKPrivacy' => ['ios-sdk/BubblSDK/PrivacyInfo.xcprivacy'] }
+  s.frameworks = 'CoreLocation', 'UserNotifications', 'UIKit', 'Security'
+  # The SDK's parts share `package` declarations, built here as one module.
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'OTHER_SWIFT_FLAGS' => '$(inherited) -package-name BubblReactNativeSdk',
+  }
 
-  s.dependency 'React-Core'
-  s.dependency 'BubblSDK', '4.1.7'
+  # React Native's dependencies for a TurboModule (the app's react_native_pods.rb).
+  install_modules_dependencies(s)
 end

package/CHANGELOG.md

@@ -1,6 +1,57 @@
 # Changelog
 
-## Unreleased
+## 5.0.0-alpha.2
+
+- `Bubbl.permissions.openSettings()` now works before `Bubbl.start` on Android, so an app can send people to its settings page (for example after a camera refusal) before it starts Bubbl. iOS 17+ already did. Below the minimum OS it stays a no-op.
+
+## 5.0.0-alpha.1
+
+- New v5 wrapper, replacing the 4.x one: a TurboModule (React Native 0.76+, New Architecture)
+  with the public API of docs/PUBLIC_API.md — `start(apiKey, options)`, consent and privacy,
+  `permissions`, `setSegments`, `track`, events, the notification listener, the report functions,
+  `submitSurvey`, `openCta`, `isBubblMessage` and `diagnostics`, and the `credential.rejected` event
+  on both platforms. JSON crosses the bridge, in the same shapes as the
+  Flutter wrapper.
+- Android over `tech.bubbl.sdk:bubbl-sdk` 5.x.
+- iOS over the Bubbl iOS SDK, built into the package's pod from its sources (no BubblSDK pod in
+  5.0).
+- `startWithCredential({ keyId, secret, installId }, options)`: start with a device credential issued
+  outside the app instead of an API key. The secret crosses the bridge as its own argument, never
+  in JSON, and nothing logs it.
+- Diagnostics include `installId` and `credentialRejected` on both platforms, and `permissions` on
+  iOS too.
+- An Expo config plugin (`app.plugin.js`): the push
+  entitlement and location usage strings, and optional plain http for development. Expo SDK 52
+  or later.
+- Where there's no native module (the web, Expo Go, Jest, a build from before the install), calls
+  do nothing and say why once in the console (the old architecture named as such), instead of
+  throwing; `diagnostics()` resolves as not started, the reason in `lastError`.
+  Importing the package on the web no longer breaks the bundle.
+- The notification listener never loses one: a notification handed to JS that JS doesn't take
+  (a reload, a stuck JS thread) is shown by Bubbl, and a React host going away (a headless one, a
+  second screen) only clears the listener its own JS set.
+- The Expo plugin also raises the app target's own `IPHONEOS_DEPLOYMENT_TARGET` to 17 (a higher
+  one is kept).
+- Expo: `ios.backgroundRefresh` adds the iOS SDK's background refresh task and the `fetch`
+  background mode to Info.plist.
+- Installs on older OS versions too (iOS 13 and Android 6 as floors, React Native's own apply):
+  `Bubbl.isSupported` and `diagnostics().supported` say whether Bubbl runs here (iOS 17 and Android
+  8.1 and later); below, every call does nothing. The config plugin no longer raises minSdk to 27 or
+  the iOS deployment target to 17 (only a value set below 23 / 13).
+- Sandbox: `registerTestDevice(code)` → `{ approved, message? }`; `diagnostics()` `environment`
+  ('sandbox' | 'production' | null) and `testDevice` (`{ status, code? }` | null); `isSandbox` on messages.
+- A Jest mock: `jest.mock('@bubblsdk/react-native-sdk', () => require('@bubblsdk/react-native-sdk/jest'))`.
+- iOS: `BubblReactNativeNotificationService` (in `ios-extension/`), the iOS SDK's
+  `BubblNotificationService` for an app's Notification Service Extension (pictures on pushes);
+  `BubblPush`, the push hand-overs for an Objective-C AppDelegate.
+- Expo: `ios.imageNotifications` in the config plugin adds that extension at prebuild (the
+  target, its Podfile target and its EAS Build `appExtensions` entry).
+
+## 5.0.0-alpha.1
+
+- Start of SDK v5, built against Bubbl's device API v1. Pre-release: not for
+  production apps. The wrapper surface is unchanged in this alpha; the native
+  engines move to the new API in later alphas.
 
 ## 4.1.7
 

package/LICENSE

@@ -1 +1,202 @@
-Copyright Bubbl. All rights reserved.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,129 +1,218 @@
-# Bubbl React Native SDK
+# @bubblsdk/react-native-sdk
 
-React Native wrapper for Bubbl SDK v3.
+Bubbl for React Native: geofenced and scheduled notifications, surveys and analytics. A thin
+TurboModule over the native Bubbl SDKs (Android `tech.bubbl.sdk:bubbl-sdk`, iOS `BubblSDK`),
+with the same functions as [docs/PUBLIC_API.md](../docs/PUBLIC_API.md) and the Flutter wrapper.
 
-The JavaScript facade forwards calls to the native Android and iOS SDK cores. Native runtime behavior, durable ingest queues, geofence transitions, notification triggering, Firebase/APNs payload handling, and diagnostics are owned by the platform SDKs.
+> 5.0 pre-release: the whole API works on Android and iOS. The
+> Android SDK 5.0 isn't on Maven Central yet: until it is, an Android build needs it in `~/.m2`
+> and `mavenLocal()` in the app's repositories (see Develop).
+
+Requires React Native 0.76 or later (the New Architecture) or Expo SDK 52 or later. It installs on
+every Android and iOS version those support; Bubbl runs on Android 8.1 (API 27) and iOS 17 and
+later, and on older ones `Bubbl.isSupported` is false and every call does nothing (permissions give
+null, diagnostics say `supported: false`). Expo SDK 57's own modules need Xcode 26.4 or later to build for
+iOS; Android builds want JDK 17.
 
 ## Install
 
-```bash
-npm install @bubblsdk/react-native-sdk
+5.0 is in alpha, on npm's `alpha` tag: install it by that tag (plain `npm install` still gets
+4.x, the `latest` tag, until 5.0 is released).
+
+```sh
+npm install @bubblsdk/react-native-sdk@alpha
+npx expo install @bubblsdk/react-native-sdk@alpha   # Expo
 ```
 
-## Boot
+An alpha can change between releases; pin the exact version (`5.0.0-alpha.1`) in `package.json`
+for repeatable builds. The steps below are otherwise the same.
 
-```ts
-import { Bubbl } from '@bubblsdk/react-native-sdk';
+### Expo (prebuild)
 
-await Bubbl.boot({ apiKey: '...' });
+```sh
+npx expo install @bubblsdk/react-native-sdk
 ```
 
-Enable SDK-owned location/background processing when the host app has collected
-location permission:
+```json
+{ "expo": { "plugins": ["@bubblsdk/react-native-sdk"] } }
+```
 
-```ts
-await Bubbl.boot({
-  apiKey: '...',
-  enableLocationTracking: true,
-});
+Then `npx expo prebuild` (or an EAS build). Expo Go can't load native modules. The plugin adds the push
+entitlement (`aps-environment`) and the location usage strings (yours, when set, or
+Bubbl's defaults). Options:
+
+```json
+["@bubblsdk/react-native-sdk", {
+  "ios": {
+    "locationWhenInUse": "…", "locationAlways": "…", "apsEnvironment": "development",
+    "imageNotifications": true, "backgroundRefresh": true
+  },
+  "android": { "cleartextHosts": ["10.0.2.2"] }
+}]
+```
+
+`ios.backgroundRefresh` lets iOS wake the app now and then so Bubbl sends what's queued (it adds
+`tech.bubbl.sdk.refresh` to `BGTaskSchedulerPermittedIdentifiers` and `fetch` to `UIBackgroundModes`;
+React Native CLI apps add the same two to Info.plist). `ios.imageNotifications` is below.
+
+For development against a local API over plain http: `android.cleartextHosts` and
+`ios.allowLocalNetworking: true` (leave both out of release builds).
 
-await Bubbl.startLocationTracking();
+### React Native CLI
+
+```sh
+npm install @bubblsdk/react-native-sdk
 ```
 
-The SDK owns the native background mechanics once enabled: Android uses the
-bundled foreground location service and WorkManager restore/refresh path, and
-iOS uses the bundled CoreLocation monitor. The host app still owns platform
-declarations and runtime permission UX.
+Android: nothing to add; what Bubbl needs (permissions, receivers, its screens) comes from the
+SDK's manifest.
+
+iOS: `pod install`, then add the Push Notifications
+capability, and `NSLocationWhenInUseUsageDescription` and
+`NSLocationAlwaysAndWhenInUseUsageDescription` to Info.plist. The Bubbl iOS SDK is built into
+this package's pod; there's nothing else to add.
 
-For iOS background geofence cold starts, forward launch options from your
-`AppDelegate` before the React Native bridge or JavaScript UI is mounted:
+### iOS: pictures on pushes (optional)
+
+Bubbl's pushes show their picture with a Notification Service Extension. React Native CLI: in
+Xcode, File › New › Target › Notification Service Extension (e.g. `NotificationService`, iOS
+17), then in the Podfile, outside the app's target:
+
+```ruby
+target 'NotificationService' do
+  pod 'BubblReactNativeNotificationService', :path => '../node_modules/@bubblsdk/react-native-sdk/ios-extension'
+end
+```
+
+`pod install`, and make the extension's `NotificationService.swift` just:
 
 ```swift
-import BubblReactNativeSdk
+import BubblNotificationService
 
-func application(
-  _ application: UIApplication,
-  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-) -> Bool {
-  BubblSdkLocationLaunchHandler.handleLaunchOptions(launchOptions as NSDictionary?)
-  return true
-}
+class NotificationService: BubblNotificationService {}
 ```
 
-For apps that render their own in-app notification modal while still letting
-the native SDK trigger device notifications:
+Other pushes pass through untouched.
 
-```ts
-await Bubbl.boot({
-  apiKey: '...',
-  notificationRenderingMode: 'sdkDefault',
-  enableDefaultNotificationModal: false,
-});
+Expo: `"ios": { "imageNotifications": true }` in the plugin's options does all of that at prebuild
+(needs `ios.bundleIdentifier`): a `BubblNotificationExtension` target (bundle id: the app's plus
+`.BubblNotificationExtension`, the app's version and device family), its Podfile target, and its
+entry in `extra.eas.build.experimental.ios.appExtensions`, so EAS Build provisions and signs it.
+
+### iOS: handing over pushes yourself (optional)
+
+Bubbl takes the push token and its own pushes by itself, alongside other push libraries. With
+`BubblAutoIntegrationEnabled` set to `NO` in Info.plist it doesn't, and the AppDelegate hands
+them over. Swift: `import BubblReactNativeSdk` (the iOS SDK is in this module), then
+`Bubbl.setPushToken(deviceToken)`, `Bubbl.willPresent(…)` and `Bubbl.didReceive(…)` as in the
+iOS SDK. Objective-C:
 
-// Or toggle it after boot.
-await Bubbl.disableDefaultNotificationModal();
+```objc
+#import <UserNotifications/UserNotifications.h>
+#import <BubblReactNativeSdk/BubblReactNativeSdk-Swift.h>
+
+[BubblPush setPushToken:deviceToken];
+if ([BubblPush willPresent:notification completionHandler:completionHandler]) return;
+if ([BubblPush didReceive:response completionHandler:completionHandler]) return;
 ```
 
-Apps with their own notification inbox/history can still ask the SDK to show
-the bundled detail UI for a stored payload:
+## Start
+
+Once, early: at the top of `index.js`, or with Expo Router (which has no `index.js`) at the top
+of `app/_layout.tsx`, outside the component:
 
 ```ts
-await Bubbl.openNotificationModal(payload);
+import { Bubbl } from '@bubblsdk/react-native-sdk';
+
+Bubbl.start('pk_live_…', { baseUrl: 'https://…' });
 ```
 
-This opens the default modal/detail UI without posting another device
-notification.
+A mistake (an empty key, an http:// URL) is logged natively, never thrown; calls before `start`
+do nothing. Geofences and pushes keep working with the app closed: the native SDK starts itself
+from its saved settings when the OS wakes the app, without JavaScript.
 
-## Android Notification Taps
+Where there's no native module, Bubbl's calls do nothing and say why once in the console: on the
+web, in Expo Go, and in a build from before the install (rebuild it). In your Jest tests, use the
+mock, whose functions are `jest.fn`s:
 
-Firebase auto-rendered notifications launch the app's `MainActivity` with the
-notification payload as intent extras. Forward those launcher intents into the
-SDK so notification taps open the app and route to the right modal.
+```ts
+jest.mock('@bubblsdk/react-native-sdk', () => require('@bubblsdk/react-native-sdk/jest'));
+```
 
-Use `openDefaultModal(...)` when the SDK should show the bundled modal:
+## Use
 
-```kotlin
-import android.content.Intent
-import android.os.Bundle
-import com.facebook.react.ReactActivity
-import tech.bubbl.reactnative.BubblSdkNotificationIntents
+```ts
+await Bubbl.permissions.requestLocation({ always: true }); // "while in use", then "always"
+await Bubbl.permissions.requestNotifications();
+
+Bubbl.setSegments(['vip']);
+Bubbl.track('purchase.completed', { total: 12.5 });
 
-class MainActivity : ReactActivity() {
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        BubblSdkNotificationIntents.openDefaultModal(this, intent)
-    }
+const subscription = Bubbl.addEventListener((event) => {
+  if (event.type === 'geofence.entered') console.log('entered', event.locationId);
+});
+
+// Show notifications yourself while the app is open (in the background Bubbl posts its own; if
+// JS can't answer, say mid-reload, Bubbl shows it, so none is lost):
+Bubbl.setNotificationListener((message) => {
+  showMyBanner(message);
+  Bubbl.reportDisplayed(message);
+  return true;
+});
 
-    override fun onNewIntent(intent: Intent) {
-        super.onNewIntent(intent)
-        setIntent(intent)
-        BubblSdkNotificationIntents.openDefaultModal(this, intent)
-    }
-}
+const diagnostics = await Bubbl.diagnostics();
 ```
 
-Use `openHostModal(...)` when the app renders its own modal. The SDK records
-the tap, keeps the payload pending across cold start, and emits
-`notificationTapped` once the React Native bridge subscribes:
+Consent (`setConsent`, `optOut`, `deleteMyData`, `setLocationEnabled`), the report functions,
+`submitSurvey`, `openCta`, `present` and `isBubblMessage` are as in the public API.
 
-```kotlin
-BubblSdkNotificationIntents.openHostModal(this, intent)
+Sandbox (a `pk_test_` key): the device shows up in the dashboard as a test device, pending until
+approved there with the code Bubbl logs and shows, or from the app:
+
+```ts
+const { approved, message } = await Bubbl.registerTestDevice('K7Q-2MX');
+const { environment, testDevice } = await Bubbl.diagnostics(); // 'sandbox', { status, code? }
 ```
 
-## Events
+Messages from a Sandbox carry `isSandbox: true`.
+
+A device credential issued outside the app (installs provisioned ahead of time, your own pairing
+flow) starts Bubbl instead of an API key, the same way at every launch:
 
 ```ts
-const subscription = Bubbl.events.addListener((event) => {
-  if (event.type === 'notificationReceived') {
-    // Host apps can inspect or custom-render notification payloads here.
-  }
-});
+Bubbl.startWithCredential({ keyId, secret, installId }, { baseUrl: 'https://…' });
+```
+
+The device doesn't register itself. The secret goes only to the native SDK (the Keychain, the
+Android Keystore); keep it out of your own logs. If the server refuses the credential, Bubbl stops
+and says so (`credential.rejected`, `diagnostics().credentialRejected`) until it's started with a
+new one.
 
-subscription.remove();
+## Develop
+
+```sh
+npm install
+npm test            # facade and config plugin tests
+npm run typecheck
+npm run build       # lib/ and plugin/build
 ```
 
-## Notes
+`example/` is a React Native app using the package from this folder. On Android it uses the
+Bubbl Android SDK from `~/.m2` until 5.0 is on Maven Central:
+
+```sh
+(cd ../android && ./gradlew publishToMavenLocal)
+node ../scripts/fake-device-api.mjs &      # a stand-in device API on port 8787
+adb reverse tcp:8787 tcp:8787
+cd example && npx react-native run-android
+```
 
-- Android depends on `tech.bubbl.sdk:bubbl-sdk` and requires `minSdkVersion 27` or higher.
-- iOS depends on the `BubblSDK` CocoaPods/Swift package release and requires iOS 15 or higher.
-- Host apps must declare push/location permissions. Android needs coarse/fine/background location, foreground-service location, and notification permissions. iOS needs location usage descriptions and `UIBackgroundModes` entries for `location` and `remote-notification`.
+`example-expo/` is an Expo app (SDK 57) with the package from this folder (`file:..`) and the
+config plugin, `ios.imageNotifications` on. It's for checking prebuild output; build the package
+first:
+
+```sh
+npm run sync:ios && npm run build
+cd example-expo && npm install
+npx expo prebuild --platform ios      # on macOS; then pod install in ios/
+```