Skip to content

fix: [SDK-5698] let initialize and login reach native - #2017

Open
abdulraqeeb33 wants to merge 2 commits into
mainfrom
ar/sdk-5698-rn
Open

abdulraqeeb33 wants to merge 2 commits into
mainfrom
ar/sdk-5698-rn

Conversation

@abdulraqeeb33

@abdulraqeeb33 abdulraqeeb33 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Important

Blocked on the never-crash rollout, not just an AAR/version bump. See "Why this cannot merge yet" below. Native's never-crash behavior sits behind SDK_NEVER_CRASH_ENABLED, which defaults to off, and the legacy path still throws on a null.

Description

One Line Summary

Remove input validation that was added to the wrapper by mistake, so the native SDK owns it.

Details

Motivation: this undoes a wrapper-side mistake

SDK-5327 added null and empty checks to every client SDK at once, wrappers included. For most APIs that was harmless duplication. For initialize and login it was the wrong layer, and it caused a bug.

Validation belongs in the native SDK. It is the only layer that knows what an invalid input should actually do, and duplicating it per wrapper means six implementations drifting from each other and from native. The wrapper's job is to pass the call through.

initialize shows why this matters concretely. Native falls back to the app ID cached by an earlier launch when the one it is given is unusable. The wrapper guard returned before native was ever called, so that fallback never ran, the SDK stayed unstarted, and the next login failed. The wrapper was not preventing a bug, it was creating one. That is the SDK-5366 chain, and the fix is to delete the guard rather than to catch the symptom downstream.

So this PR is a correction, not a feature: the check should have gone into native in the first place.

Why this cannot merge yet

Native Android's never-crash behavior is behind a remote feature flag, and it is off by default:

// NeverCrashKillSwitch.kt
// Absent means the legacy implementation, so the rollout stays off until Turbine sends the flag.
@Volatile
var useLegacy: Boolean = true

When the flag is off, NeverCrashKillSwitch.create() returns the legacy OneSignalImp, which still throws by design:

if (appId == null) throw nullParameter("initWithContext", "appId")
if (externalId == null) throw nullParameter("login", "externalId")

The helper is commented "The kill switch's fallback keeps the crash a Java null used to hit in the non-null facade." The nullable signatures from #2841 are real, but the log-and-ignore behavior behind them only applies on the V2 path.

So merging needs both:

  1. A released Android SDK containing the never-crash change, and the pin bumped to it.
  2. SDK_NEVER_CRASH_ENABLED actually rolled out, since the flag is evaluated per app from mirrored startup flags.

Until then, removing the guard reintroduces exactly the SDK-5304 crash for every app the flag has not reached. My original description claimed Android already logs and ignores a null; that was wrong, and it was wrong in the same way across all six wrapper PRs.

Scope

Only initialize and login in src/index.ts.

isNativeModuleLoaded stays. So do the alias, email, SMS, tag, trigger, and outcome guards, along with encodeNullsForIOS, the Live Activity checks, and removeGroupedNotifications. Those native parameters are still non-null.

Testing

Unit testing

Four tests in src/index.test.ts asserted "do not call native" for a null and an empty value. They now assert the value is forwarded, which is the new contract.

I verified they can actually fail rather than trusting the green run: restoring the initialize guard turns its two tests red (2 failed | 436 passed).

Full suite: 438 passed. vp check src reports no formatting, lint, or type errors.

Manual testing

Not exercised on a device. It cannot be meaningfully exercised until the dependency bump: on the pinned 5.11.0, a null still reaches non-null Kotlin parameters on Android.

Affected code checklist

  • Notifications
  • Outcomes
  • Sessions
  • In-App Messaging
  • REST API requests
  • Public API changes

Checklist

Overview

  • I have filled out all REQUIRED sections above
  • PR does one thing
  • Any Public API changes are explained in the PR details and conform to existing APIs

Testing

  • I have included test coverage for these changes, or explained why they are not needed
  • All automated tests pass, or I explained why that is not possible
  • I have personally tested this on my device, or explained why that is not possible

Final pass

  • Code is as readable as possible.
  • I have reviewed this PR myself, ensuring it meets each checklist item

Both guards returned before calling native. Initialize was the damaging
one: native falls back to the cached app id, and short-circuiting skipped
that fallback, leaving the SDK unstarted so the next login failed.

Safe on both platforms, checked rather than assumed:

  Android  initWithContext and login now take String? and log and ignore
           a null, after the never-crash change.
  iOS      initialize: explicitly handles nil and falls back to the
           cached app id. The RN bridge's login already rejects a nil or
           empty externalId itself, in RCTOneSignalEventEmitter.mm, so
           native iOS login never sees one.

isNativeModuleLoaded stays. So do the alias, email, SMS, tag, trigger,
and outcome guards: those native parameters are still non-null.

The four tests that asserted "do not call native" now assert the call is
forwarded. Reverting either guard turns them red, which I confirmed.

DO NOT MERGE until oneSignalVersion in android/build.gradle can be bumped
to a release containing the never-crash change. It pins 5.11.0, where
initWithContext and login take non-null Kotlin parameters.

Co-authored-by: Cursor <cursoragent@cursor.com>
@abdulraqeeb33
abdulraqeeb33 requested a review from a team November 20, 2026 16:16
@abdulraqeeb33
abdulraqeeb33 marked this pull request as ready for review November 20, 2026 17:21

@fadi-george fadi-george left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a few comments. The Android init latch one is the only one I'd block on.

Comment thread src/index.ts
if (!isNativeModuleLoaded(RNOneSignal)) return;
if (isMissing(appId, 'initialize: appId')) return;

RNOneSignal.initialize(appId);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: on Android, RNOneSignal.java:243 sets oneSignalInitDone = true no matter what. On a fresh install with no cached app id, initialize(null) fails init in the SDK, but the bridge still latches. A later initialize(realId) in the same process then hits the early return at :229 and gets dropped until restart. Before this PR the JS guard kept that from happening.

Could we only latch when appId is non-empty, or just let the SDK's own already-initialized check handle repeat calls? initWithContext's return value won't work here, since it returns true once init is queued, before the app id is resolved.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, and you are right that initWithContext's return value will not help. Not fixed.

It sits behind a bigger blocker I had wrong: this needs SDK_NEVER_CRASH_ENABLED rolled out, not just the oneSignalVersion bump. Legacy OneSignalImp still throws on null by design.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now fixed in 217ae1c. oneSignalInitDone latches only once an app id is present, so a later initialize with a real one is no longer swallowed. Left your point about the return value in the comment, since it explains why the obvious fix does not work.

Comment thread src/index.ts
if (!isNativeModuleLoaded(RNOneSignal)) return;
if (isMissing(externalId, 'login: externalId')) return;

RNOneSignal.login(externalId);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: removing isMissing also removes the string type check, for both initialize and login. If untyped JS passes a number, Android's JavaTurboModule now throws a conversion exception instead of us logging and returning. Maybe keep a small guard like if (value != null && typeof value !== 'string') so null and "" still reach native.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch that isMissing was doing double duty here. If a guard stays it should be type-only, so null and "" still reach native. Not done yet.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now fixed in 217ae1c. Added isNotStringOrNullish, which rejects a non-string but lets null, undefined and "" through for native to decide on. Covered by two tests.

Comment thread src/index.test.ts Outdated
});

test('should not initialize if appId is empty', () => {
test('should forward an empty appId to native, which falls back to the cached app id', () => {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: this holds on Android, but on iOS "" gets rejected by OSInputGuard and only nil falls back to the cached id. Maybe reword the title, or map "" to null if it should fall back on both.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, the title overclaims. iOS rejects "" and only nil falls back.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now fixed in 217ae1c. Both titles are narrowed to what they actually assert.

Comment thread src/index.ts
@@ -137,7 +137,6 @@ export namespace OneSignal {
/** Initializes the OneSignal SDK. This should be called during startup of the application. */
export function initialize(appId: string) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: null is now an intended input here, but the Spec (NativeOneSignal.ts:8) still types appId: string, and the iOS bridge (RCTOneSignalEventEmitter.mm:136) still marks it _Nonnull. It works at runtime since TurboModules pass nil through, but string | null and _Nullable would match the behavior.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. string | null on the Spec and _Nullable on the bridge would match the intent. Not done yet.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Half done in 217ae1c: the iOS bridge parameter is _Nullable now.

Left the Spec as appId: string. Changing it means codegen plus a native build to verify, and CI here is JS-only, so I would be pushing an unverified codegen change. Happy to do it if you want it in this PR.

Comment thread src/index.ts
if (isMissing(appId, 'initialize: appId')) return;

RNOneSignal.initialize(appId);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: when native ignores init (null appId and nothing cached), the startup reads below still run, so the user sees "failed to read initial state" instead of the real problem.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noted. The startup read failure would mask the real cause.

@abdulraqeeb33

Copy link
Copy Markdown
Contributor Author

The init latch is a real hole, agreed, and initWithContext's return value will not help for the reason you gave. Not fixed yet.

It also sits behind a larger blocker I had wrong: this needs SDK_NEVER_CRASH_ENABLED rolled out, not just the oneSignalVersion bump. Legacy OneSignalImp still throws on null by design. The description now leads with that.

On the dropped type check: good point that isMissing was doing double duty. If we keep a guard there it should be type-only, so null and "" still reach native.

RNOneSignal.java set oneSignalInitDone regardless of outcome. With no app
id and nothing cached, init fails but the latch still happens, so a later
initialize with a real app id hit the already-initialized early return for
the rest of the process. It now latches only once an app id is present.
initWithContext's return value cannot stand in: it reports that init was
queued, before the app id is resolved.

Removing isMissing also removed the string type check it was doing double
duty for, so an untyped caller passing a number would hit a TurboModule
conversion error. Added isNotStringOrNullish, which rejects a non-string
while letting null, undefined and "" through for native to decide on.

Marked the iOS initialize bridge parameter _Nullable, since nil is now an
intended input there.

Two test titles claimed behavior they did not check, and are narrowed to
what they assert.

Left out: typing appId as string | null in the TurboModule Spec. It needs
codegen plus a native build to verify, and CI here is JS-only.

Review feedback from fadi-george on #2017.

Co-authored-by: Cursor <cursoragent@cursor.com>
@abdulraqeeb33

Copy link
Copy Markdown
Contributor Author

Follow-up: all five are addressed in 217ae1c, except typing the Spec appId as string | null. That one needs codegen plus a native build and CI here is JS-only, so I left it rather than push something unverified. Say the word and I will add it.

The flag-rollout blocker still stands.

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.

2 participants