Skip to content

fix(ios): forward all background URL session events to the SDK per docs#6

Merged
jaymaycry merged 1 commit into
mainfrom
fix/ios-background-session-docs
Jun 2, 2026
Merged

fix(ios): forward all background URL session events to the SDK per docs#6
jaymaycry merged 1 commit into
mainfrom
fix/ios-background-session-docs

Conversation

@jaymaycry

Copy link
Copy Markdown
Contributor

Why

The background URL session handling added in 0.2.0 (#2) used an identifier-prefix check (handlesBackgroundURLSession) to route only MotionTag-owned sessions to the SDK. That is not what the MotionTag iOS guide prescribes, and not what MotionTag's official Flutter SDK AppDelegate does:

override func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
    MotionTagCore.sharedInstance.processBackgroundSessionEvents(with: identifier, completionHandler: completionHandler)
}

Every identifier is forwarded unconditionally — the SDK decides internally which sessions are its own. Verified against the SDK 6.5.0 binary: registerCallback:forIdentifier: stores the handler and only invokes it when the SDK's own session finishes events, so foreign handlers go stale rather than being double-called.

The prefix check was also fragile: a future SDK version changing its session identifier would silently break background-upload recovery again.

What

  • plugin/withIosAppDelegate.js: generated override is now a plain unconditional forward (matches the Flutter reference; existing misplaced/old blocks are replaced on expo prebuild)
  • ios/MotionTagBootstrap.swift: removed handlesBackgroundURLSession(identifier:)
  • README.md: bare-RN snippet reverted to the docs pattern; identifier-prefix maintenance note dropped from the SDK-bump checklist

Note for consumers

handlesBackgroundURLSession existed only in 0.2.0/0.3.0 (released today) and is consumed only by plugin-generated code — re-run npx expo prebuild after updating and the reference disappears. Bare-RN hosts following the old README snippet should simplify to the unconditional forward.

Verification

  • expo prebuild regenerates the example AppDelegate with the docs-exact override; old generated blocks are migrated
  • No references to the removed API remain in the repo

🤖 Generated with Claude Code

The identifier-routing added in 0.2.0 (handlesBackgroundURLSession prefix
check, with non-matching sessions going to super / completionHandler())
deviated from the MotionTag iOS guide. The guide and the official Flutter
SDK's AppDelegate forward every identifier unconditionally - the SDK decides
internally which sessions are its own and only calls the completion handler
for those (verified against the SDK 6.5.0 binary: registerCallback ignores
foreign identifiers' handlers rather than completing them).

The prefix check was also fragile: a future SDK version changing its session
identifier would silently break background upload recovery again.

Removes MotionTagBootstrap.handlesBackgroundURLSession (added in 0.2.0,
consumed only by plugin-generated code; re-run expo prebuild after updating).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@jaymaycry jaymaycry merged commit 0f02219 into main Jun 2, 2026
1 check passed
@github-actions github-actions Bot mentioned this pull request Jun 2, 2026
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.

1 participant