Skip to content

Conversation

@melekr
Copy link
Collaborator

@melekr melekr commented Dec 13, 2025

Context

WebGL users can lose unsent Backtrace reports when:

  • BacktraceDatabase writes aren’t flushed from IDBFS to IndexedDB before tab close/background.

and/or

  • BacktraceDatabase is disabled/unavailable, causing network/server send failures to be dropped.

Solution

Persist offline reports reliably (IDBFS flush hooks + PlayerPrefs fallback queue)

This PR adds two WebGL-specific reliability layers consistent with existing Backtrace database settings:

  1. IDBFS flush support
  • Adds BacktraceSync.jslib exposing FS.syncfs
  • Adds BacktraceWebGLSync.cs wrapper
  • Installs page lifecycle hooks (pagehide, beforeunload, visibilitychange, freeze) and calls FS.syncfs at key SDK lifecycle points to reduce data loss.
  1. Fallback offline queue when BacktraceDatabase is unavailable:
  • Adds WebGLOfflineDatabase.cs PlayerPrefs queue.
  • Queue bounds derive from BacktraceConfiguration database settings (MaxRecordCount, MaxDatabaseSize, RetryLimit, RetryOrder, RetryInterval, AutoSendMode)
  • Enforces WebGL safe hard caps to avoid excessive PlayerPrefs/browser storage use
  • Replays queued reports on an interval when AutoSendMode is enabled.

Notes / Limitations

  • FS.syncfs is best-effort and async: abrupt tab termination can still lose data.
  • PlayerPrefs queue is intentionally bounded: oversized reports are not persisted.

Sample Reports

ref: BT-6231

- Flush IDBFS to IndexedDB on browser lifecycle events.
- Add PlayerPrefs offline queue fallback when BacktraceDatabase is unavailable.
@melekr melekr requested a review from rick-bt December 13, 2025 00:09
@melekr melekr self-assigned this Dec 13, 2025
@melekr melekr requested a review from konraddysput December 15, 2025 18:33
Copy link
Collaborator

@konraddysput konraddysput left a comment

Choose a reason for hiding this comment

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

BacktraceClient represents a business logic not related to the database. We have a dedicated class implementation for it, which is BacktraceDatabase. Mixing business logic and database implementation in the client is the wrong decision long term. Instead, you need to use BacktraceDatabase and use abstraction to properly implement a proper database logic for webgl /webgl database operations.

Please also look at the project structure to follow the file pattern.


// WebGL builds may have multiple BacktraceClient instances if DestroyOnLoad is enabled.
// Ensure only one instance performs offline queue replay to avoid duplicate sends.
private static BacktraceClient _webglOfflineReplayOwner;
Copy link
Collaborator

Choose a reason for hiding this comment

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

we already have a static Backtrace instance available here.

Comment on lines +135 to +143
#if UNITY_WEBGL
private WebGLOfflineDatabase _webglOfflineDatabase;
private Coroutine _webglOfflineReplayCoroutine;
private bool _webglOfflineReplayInProgress;

// WebGL builds may have multiple BacktraceClient instances if DestroyOnLoad is enabled.
// Ensure only one instance performs offline queue replay to avoid duplicate sends.
private static BacktraceClient _webglOfflineReplayOwner;
#endif
Copy link
Collaborator

Choose a reason for hiding this comment

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

It should be moved to BacktraceDatabase - BacktraceDatabase offerts the same Untiy scope.

}
}
#if UNITY_WEBGL
private void InitializeWebGLOfflineSupport()
Copy link
Collaborator

Choose a reason for hiding this comment

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

It should be abstracted in the BacktraceDatabase implementation - we have the Start/Awake support there.

@melekr
Copy link
Collaborator Author

melekr commented Dec 15, 2025

BacktraceClient represents a business logic not related to the database. We have a dedicated class implementation for it, which is BacktraceDatabase. Mixing business logic and database implementation in the client is the wrong decision long term. Instead, you need to use BacktraceDatabase and use abstraction to properly implement a proper database logic for webgl /webgl database operations.

Please also look at the project structure to follow the file pattern.

webgl db logic can be easily moved out of BacktraceClient, and the implementation above does not affect platforms other than the currently unsupported webgl. ~

The fine-line/strategy -here- was to diverge temporarily and quickly unblock webgl integrators while we work on providing real targeted support for webgl as a first-class platform (rather than relying on default/general/other platforms implementations).

If this PR adds too much noise, we can close it and work on webgl offline support after/under the broader webgl scope.

@melekr melekr closed this Dec 15, 2025
@melekr melekr reopened this Dec 16, 2025
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.

3 participants