Skip to content

Feature - Beam Native Library for Campaigns and Push Notifications - #4799

Merged
DiasAtBeamable merged 172 commits into
mainfrom
feature/beamNativeLibraries
Aug 18, 2026
Merged

Feature - Beam Native Library for Campaigns and Push Notifications#4799
DiasAtBeamable merged 172 commits into
mainfrom
feature/beamNativeLibraries

Conversation

@DiasAtBeamable

@DiasAtBeamable DiasAtBeamable commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

Brief Description

Lands the beamNativeLibraries line of work: a new top-level home for Beamable's native mobile
libraries, a first-class local Beamable stack in the CLI, Web SDK support for React Native, and the
message-rail federation plumbing that ties them together.

This is a long-running feature branch — 121 non-merge commits, 743 files, ~447k insertions (the bulk
is auto-generated client code and vendored native sources). Please squash merge.

1. beam-native-mobile/ — native mobile libraries (new top-level directory)
Consolidates the previously scattered notification/deeplink code into one tree with a consistent
Beamable naming scheme:

  • NativeSources/Android + NativeSources/iOS — the BeamableNotifications libraries. Local and
    remote push over FCM/APNs with a unified handler path, custom notification styles
    (default / bigPicture / bigText / action buttons) with parity between platforms, notification
    categories persisted for killed-app flows, iOS Live Activities (including remote updates and
    action buttons) and a Notification Content Extension for advanced styles, deeplink normalization,
    and delivered/opened/clicked/converted analytics reported as Beamable analytics events (the old
    Slack-webhook path is gone). Includes unit tests for the Android library.
  • ReactNative/ — a single React Native package (replaces the separate per-feature RN libraries and
    the standalone @beamable/sdk-react-native adapter), with an Expo config plugin, permission
    handling, push opt-in/opt-out, and bindings for account management, in-game messages, and message
    rail.
  • Unity/, Unity.Web/, Unreal/ — engine wrappers over the same prebuilt artifacts. The Unreal
    plugin moved to EnginePlugins with install/packaging scripts; Unity.Web bridges the Web SDK
    into Unity.
  • Samples/ReactNative + Samples/WebSDKUsageSample — a tabbed RN sample app exercising push,
    custom styles, countdown/rich-media Live Activities, mailbox/message rail, and running against a
    local stack.

2. CLI — local Beamable stack (beam local …)
New LocalStack command family (init, up, stop, ps, logs, validate) plus the services
behind it: LocalStackTemplate, LocalStackProcess, LocalStackPortGuard, LocalStackDockerWatchdog,
LocalStackJobObject, LocalRealmService, LogTail. Highlights:

  • local up runs services attached without logs by default; --run-detached and --save-logs
    control that. local stop tears down child/orphaned processes and makes DB purge optional.
  • Readiness probing, retries for Scala/Mongo replica-set startup races, staggered launch, port
    conflict detection, freeing squatted Mongo ports, and a Docker container watchdog that restarts
    long-running services.
  • Windows fixes: port-permission failures, hung-process timeouts, process-tree management.
  • --java-home option (JavaPathOption) and clean Maven/Scala builds to avoid cross-module class skew.
  • Adds the message rail services (mail, messaging, notification), campaign, and analytics-gateway to
    the local topology.

3. CLI — beam web command group
web publish, web use, web status, web reset, web stop over a local npm registry
(WebLocalRegistryService), so a workspace can consume locally built web packages.
beam init and beam local up now default to the local registry; pass --no-web-registry to opt out.

4. Web SDK (web/)
Native React Native build target (dist/react-native, selected by Metro's "react-native" export
condition) with AsyncStorage-backed token/config/content storage as the default, a
react-native/polyfills entry, and TokenStorage.hydrate() awaited at the start of connect() so
async-persisted tokens are loaded before the expiry check. Also: realtime websocket can be disabled
(BeamConfig.realtime.enabled, connectRealtime() / disconnectRealtime()), config can be read from
a workspace .beamable / beam.config.json, websocket re-auth on expired token is fixed, and the
generated API surface is regenerated (adds CampaignApi, DataBindingApi, MessageRailApi).

5. Portal toolkit (0.5.0)
The five chart components (BeamLineChart, BeamBarChart, BeamDonutChart, BeamFunnelChart,
BeamSankeyChart) are exported again — they had hand-written forwarders but were missing from
REACT_HANDWRITTEN, so codegen emitted duplicates and the ambiguous export * names were dropped
entirely. Plus beam-tag-input, beam-date-picker, beam-tab[with-remove], typed custom-event props
in generated React types, and a .d.ts fix emitting globalThis.Element. See
beam-portal-toolkit/CHANGELOG.md.

6. Message rail federation
FederatedMessageRail / IMessageRailFederation (renamed from IMessageCampaignFederation) in
beamable.common, wired into federation type mappings and FederatedComponentGenerator, with the
Unity Common/Runtime and Editor/BeamCli bindings and OpenAPI models regenerated.

7. Tooling & docs
setup-native.sh / dev-native.sh (native artifact build + staging, with Gradle transform-cache
busting), scripts/beam-cli.sh, cli/scripts/run-local-stack.sh, web/LOCAL_DEV.md, and
beam-native-mobile/AGENTS.md. Per-feature .md design docs that lived on this branch were removed —
that content now lives in the docs repo. 10 new CLI test files cover the local-stack services
(port guard, watchdog, liveness, build step, web-registry step, kill token, log dir, Scala launch).

Checklist

  • Have you added appropriate text to the CHANGELOG.md files?
    • web/CHANGELOG.md and beam-portal-toolkit/CHANGELOG.md are updated.
    • ⚠️ client/Packages/com.beamable/CHANGELOG.md is not — the Unity-facing changes here
      (new native plugin packages, FederatedMessageRail, regenerated BeamCli contracts) probably
      warrant an entry before merge.

Add those to list or remove the list below altogether:

DiasAtBeamable and others added 30 commits June 17, 2026 18:17
…y paths, unify handler invocation, update documentation"
…ARY_GUIDE.html` for improved documentation
…mableProduct into feature/beamNativeLibraries
change: dev-native.sh now moves the aar to the Native Unity Plugin Package.
change: Moved Unity Editor Code from client/ to nativePlugin/Unity.
…mableProduct into feature/beamNativeLibraries
The Portal extension's calls to ListRegisteredPlayers / SendPushToPlayer /
CheckFcmConfig failed with 401 "requires an authenticated user" because
[AdminOnlyCallable] requires a logged-in player, which a Portal extension's
session does not carry. [ServerCallable] keeps the "*" admin-scope gate but
drops the authenticated-user requirement, so the admin Portal extension can
reach these back-office endpoints.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Beamable's stat search (/basic/stats/search) compares stat values as strings,
so ListRegisteredPlayers' numeric `push_devices > 0` criteria never matched the
string-stored count and the roster always came back empty. Switch to a string
`push_devices != "0"` comparison, which correctly returns players with a
non-zero device count and excludes fully-unregistered ("0") players.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- APNs: Added `mutable-content` for Notification Service Extension invocation, ensuring closed-app analytics and webhook execution.
- FCM: Switched to data-only messages to invoke `onMessageReceived` in all app states, enabling consistent handler processing.
- Introduced an in-memory `localStorage` shim backed by AsyncStorage to persist SDK realm markers (`beam_cid`/`beam_pid`) and prevent repeated guest player creation.
- Added `hydrateLocalStorage()` to preload persisted entries before `Beam.init()`.
- Ensured `hydrateLocalStorage()` is called in the `beamClient` before SDK initialization.
fix: Deeplink issues and removed expo-notifications to use BeamableNotifications instead.
Both branches independently removed expo-notifications and added the Android
notification deep-link bridge fix; merged cleanly except package-lock.json,
which was regenerated from the merged package.json.
…o feature/beamNativeLibraries

# Conflicts:
#	nativeLibraries/Samples/ReactNative/app/_layout.tsx
#	nativeLibraries/Samples/ReactNative/app/index.tsx
#	nativeLibraries/Samples/ReactNative/package-lock.json
#	nativeLibraries/Samples/ReactNative/package.json
#	nativeLibraries/Samples/ReactNative/src/beam/push.ts
#	nativeLibraries/Samples/ReactNative/src/notifications/beamableNotifications.ts
- Introduced comprehensive tests for ActivityIntentObserver, IntentDeepLinkExtractor, PushReceivedEvent, NotificationTemplate, and IntentDataReader.
- Enabled Robolectric for JVM unit testing by updating build.gradle with Android resources support and test dependencies.
- Introduced bulk send functionality targeting multiple players and devices.
- Added selectable rows, "select all," and "clear selection" options in player roster.
- Enhanced send status messaging for partial/failed deliveries.
- Extended player roster fields with game platform and device data.
@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Lightbeam link

@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Lightbeam link

@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Lightbeam link

@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Lightbeam link

@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Lightbeam link

@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Lightbeam link

@DiasAtBeamable
DiasAtBeamable marked this pull request as ready for review August 18, 2026 11:48
@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Lightbeam link

@github-actions

Copy link
Copy Markdown
Contributor

Web SDK Sample Build link

@github-actions

Copy link
Copy Markdown
Contributor

Lightbeam link

@DiasAtBeamable
DiasAtBeamable merged commit 4b1af88 into main Aug 18, 2026
29 checks passed
@DiasAtBeamable
DiasAtBeamable deleted the feature/beamNativeLibraries branch August 18, 2026 13:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants