Improvement: failure message shows that appID is missing

[jinliu9508]

Description

One Line Summary

Update the failure message so it is clear when appID is previously not provided.

Details

Motivation

The original failure message "Initialization failed. Cannot proceed." is vague and can potentially hide the real cause when appID is not provided as expected. We want to show this message so developers can immediately figure out the wrong usage.

Scope

OneSignalImp.kt will now save and throw a clearer error message when OneSignal is accessed before initWithContext is called with an appID.

Comparison with 5.1.x behavior

5.1.x:

• Calling initWithContext without an appId does not throw immediately.
  • The first time we access OneSignal afterward, we get:
    Caused by: java.lang.Exception: Must call 'initWithContext' before use
  • This points to the accessor call site, but it hides the real root cause: the missing appId.

5.4.x:

• The internal initWithContext(context) is now suspend and must be called from a coroutine.
  1. If a consumer migrates to 5.4.x and still calls the internal initWithContext directly on the main thread, they’ll get a compile-time error, which makes the incorrect usage obvious.
  2. Initialization is generally performed in a “fire-and-forget” coroutine. When the IO coroutine fails inside the SDK, there is no longer a meaningful JVM call stack back to the original caller (e.g., which Activity or method triggered init). It’s a separate async execution.
  • In this case, the error message is:
    suspendInitInternal: no appId provided or found in local storage. Please pass a valid appId to initWithContext().
  • This message clearly states the root cause (no appId supplied), but the consumer will need to locate where they call init in their own code to fix it.

Testing

Unit testing

Add a new test case to assert the error message.

Manual testing

Tested on Emulator Pixel 9 API 35:

1. Remove the appID and call OneSignal.initWithContext(context) in MainApplicationKT.kt
2. Fresh install and observe the error message asking to provide an appID.

Affected code checklist

• Notifications
  • Display
  • Open
  • Push Processing
  • Confirm Deliveries
• 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
  • If it is hard to explain how any codes changes are related to each other then it most likely needs to be more than one PR
• 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.
  • Simplify with less code, followed by splitting up code into well named functions and variables, followed by adding comments to the code.
• I have reviewed this PR myself, ensuring it meets each checklist item
  • WIP (Work In Progress) is ok, but explain what is still in progress and what you would like feedback on. Start the PR title with "WIP" to indicate this.

---

This change is 

[github-actions]

📊 Diff Coverage Report

Diff Coverage Report

Threshold: 80%

Changed Files Coverage

• ❌ OneSignalImp.kt: 61/255 lines (23.9%)
  • ⚠️ Below threshold: 194 uncovered lines

Overall Coverage

61/255 lines covered (23.9%)

❌ Coverage Check Failed

Files below 80% threshold:

• OneSignalImp.kt: 23.9% (194 uncovered lines)

📥 View workflow run

[jkasten2]

Can we also include the original stacktrace? This will make it easier to find which call to initWithContext was the cause of their issue.

Did you test how this scenario behaved in 5.1.x? Can you make a note of that in the PR?

[jinliu9508]

@jkasten2

Can we also include the original stacktrace? This will make it easier to find which call to initWithContext was the cause of their issue.

Did you test how this scenario behaved in 5.1.x? Can you make a note of that in the PR?

I see, it does makes things easier to surface the wrong usage that causes the issue. A saved exception is now created in for initWithContext before the background work so it can point to the caller that triggered init.

I’ve also updated the PR subscription to include the comparison with how this scenario behaved in 5.1.x. In 5.1.x, calling initWithContext without an appId did not fail immediately; the error only appeared later when accessing OneSignal, and the message didn’t expose the real root cause. The 5.4.x behavior is more direct and accurately surfaces the missing-appId error.