[Woo POS][Local Catalog] Beta-fix Add Better Analytics to Background Task Refresh System

[joshheald]

N.B. – replaces #16011, as we decided to move it to a beta fix

Description

This PR adds detailed analytics tracking to the existing background task refresh system to help us understand
how background syncing works in real-world conditions. This will inform our choices for POS local catalog sync, whether we can use the same App Refresh task or would need a background processing task.

@toupper @jaclync What do you think – 23.1, or put it in the 23.0 beta? I'm happy either way, but have done 23.1 for now.

Also, if you think there's anything else we should try to track, let me know.

Changes

Analytics Updates

• Updated WooAnalyticsEvent.BackgroundUpdates to track more system info
• Added dataSyncedDetailed() event that captures:
  • How long the task took and how much time iOS gave us
  • Network type (wifi, cellular, ethernet) and connection flags
  • Device power status, battery level, and power-saving modes
  • Time since the last background refresh

System Info Collection

• New BackgroundTaskSystemInfo struct to gather device/network info
• Network detection using NWPathMonitor
• Battery monitoring

Analytics Properties

Property	Type	What it tracks
time_taken	Int64	How long the background task took (seconds)
background_time_granted	Int64	How much time iOS gave us (optional)
network_type	String	"wifi", "cellular", "ethernet", "no_connection"
is_expensive_connection	Bool	Roaming, hotspots, limited data plans
is_low_data_mode	Bool	iOS Data Saver feature enabled
is_powered	Bool	Device plugged in or charging
battery_level	Float64	Battery percentage (0.0 to 1.0)
is_low_power_mode	Bool	iOS Low Power Mode enabled
time_since_last_run	Int64	Seconds since last background refresh (optional)

Steps to reproduce

1. Build and install the app on a real device (background tasks don't work in Simulator)
2. Set up test conditions:
   - Turn Low Data Mode on/off: Settings → Cellular → Cellular Data Options → Low Data Mode
   - Turn Low Power Mode on/off: Settings → Battery → Low Power Mode
   - Try different networks: WiFi, Cellular, WiFi hotspot
3. Test background task. Either wait half an hour or so (could be much longer) or:
   - Run from Xcode, adding a breakpoint after the task is scheduled (at the end of AppDelegate.applicationDidEnterBackground(_:))
   - In Xcode debug console, run this command:
   - e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.automattic.woocommerce.refresh"]
   - Allow the app to run on
4. Check the analytics data:
   - Look for Tracked background_data_synced in the logs
   - Make sure all the properties show up and look correct:
   • network_type should show your current connection
   • is_low_data_mode should match what you set in Settings
   • is_low_power_mode should match what you set in Settings
   • battery_level should show current battery percentage
   • is_powered should show if you're charging
   • Note that if you are attached to the debugger, normal sheduled tasks won't run and the background_time_granted won't be logged, because the app is essentially in the foreground even when you background it.
5. Try different cases:
   - WiFi with/without Low Data Mode
   - Cellular with/without roaming (if you can)
   - Different battery levels and charging states
   - Run while app is in background vs foreground

Expected Results

Analytics should show detailed info like:

  background_data_synced: {
    time_taken: 2,
    network_type: "wifi",
    is_expensive_connection: false,
    is_low_data_mode: true,
    is_powered: false,
    battery_level: 0.65,
    is_low_power_mode: false,
    time_since_last_run: 1847
  }

Testing information

I've tested this on an iPhone running iOS 18, with both simulated and real BGAppRefreshTasks. Screenshot below shows a real task's logged result.

Screenshots

---

• I have considered if this change warrants user-facing release notes and have added them to RELEASE-NOTES.txt if necessary.

[dangermattic]

	1 Warning
⚠️	This PR is assigned to the milestone 23.0 ❄️. The due date for this milestone has already passed. Please assign it to a milestone with a later deadline or check whether the release for this milestone has already been finished.

Generated by 🚫 Danger

[wpmobilebot]

📲 You can test the changes from this Pull Request in WooCommerce iOS Prototype by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce iOS Prototype
	Build Number	pr16014-7758a92
	Version	23.0
	Bundle ID	com.automattic.alpha.woocommerce
	Commit	7758a92
	Installation URL	5c1ie5icgajq0

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

[jaclync]

LGTM tested again on iPhone 16 Pro Max, iOS 18.6, and saw background_data_synced logged with the expected properties ✅ Will merge the PR once I verified the event properties in Tracks.

[jaclync]

Update: beta build 23.0.0.1 is now available in TestFlight.

[sentry]

Suspect Issues

This pull request was deployed and Sentry observed the following issues:

• ‼️ EXC_BREAKPOINT: _Concurrency/CheckedContinuation.s... in appStore

_{Did you find this useful? React with a 👍 or 👎}

[jaclync]

@joshheald 👋 this is a new crash in 23.0 from the tracking change. Do you think moving the cancel before resuming the continuation might help?

woocommerce-ios/WooCommerce/Classes/Tools/BackgroundTasks/BackgroundTaskRefreshDispatcher.swift

Lines 180 to 181 in 75aeefa

	continuation.resume(returning: NetworkInfo(path: path))
	monitor.cancel()

[joshheald]

@joshheald 👋 this is a new crash in 23.0 from the tracking change. Do you think moving the cancel before resuming the continuation might help?

woocommerce-ios/WooCommerce/Classes/Tools/BackgroundTasks/BackgroundTaskRefreshDispatcher.swift

Lines 180 to 181 in 75aeefa

	continuation.resume(returning: NetworkInfo(path: path))
	monitor.cancel()

That's annoying.
Yes, it probably would. We could also use the nillable continuation pattern as extra safety. I'll make a fix.

[joshheald]

Discussion can continue in WOOMOB-1204