[Woo POS][Local Catalog] Add Better Analytics to Background Task Refresh System #16011

joshheald · 2025-08-14T14:13:14Z

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

Build and install the app on a real device (background tasks don't work in Simulator)
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
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
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.
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.

wpmobilebot · 2025-08-14T14:22:58Z

📲 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	`pr16011-9a05702`
	Version	`23.0`
	Bundle ID	`com.automattic.alpha.woocommerce`
	Commit	`9a05702`
	Installation URL	707il5pp3vovo

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

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.

I'd say yes to 23.0 beta, mostly because I'm the release DRI 😆 . Otherwise, I feel like this isn't a very urgent change. It'd be the first time I'm generating a new beta, is the process to change the PR base to the release 23.0 branch and then I'll generate a new beta from the release dashboard?

I put the app on an iPad device to the background for more than an hour and didn't see any logs when I came back. I updated the scheduled time to 5 minutes, and didn't see an event until maybe an hour later. The first event below was naturally triggered, and the second was triggered from the console.

2025/08/15 06:38:34:448  🔵 Tracked background_data_synced, properties: [battery_level: 0.949999988079071, network_type: wifi, is_low_power_mode: false, is_low_data_mode: false, is_powered: true, blog_id: -1, background_time_granted: 119, is_expensive_connection: false, time_taken: 2, ...]
2025/08/15 06:47:29:408  🔵 Tracked background_data_synced, properties: [is_powered: true, time_since_last_run: 534, is_low_data_mode: false, network_type: wifi, is_low_power_mode: false, blog_id: -1, is_expensive_connection: false, battery_level: 0.949999988079071, time_taken: 1, ...]

Even though I only saw these two events (the app log file included the last 3 hours), the battery settings showed that the app spent 27 minutes in the background 🤔

jaclync · 2025-08-15T02:47:15Z

WooCommerce/Classes/Tools/BackgroundTasks/BackgroundTaskRefreshDispatcher.swift

        // Launch all refresh tasks in parallel.
        let refreshTasks = Task {
            do {
+                let systemInfo = await BackgroundTaskSystemInfo()


nit: how about initializing the system info async when it's ready to track the event later? just in case it takes a bit of time (maybe it's close to zero) that can affect the time for the main tasks below. Or is it here to capture the device status at the beginning of the refresh task?

This won't delay the tasks below – let await doesn't block further execution until the variable is accessed, after the tasks run.

You're right though, the reason it's here is to capture the status at the beginning of the task, because that will give us the accurate background time granted value.

Ooops, no, I should use async let for that. I'll try it.

jaclync · 2025-08-15T02:54:16Z

WooCommerce/Classes/Tools/BackgroundTasks/BackgroundTaskRefreshDispatcher.swift

                let timeTaken = round(Date.now.timeIntervalSince(startTime))
-                ServiceLocator.analytics.track(event: .BackgroundUpdates.dataSynced(timeTaken: timeTaken))
+                let timeSinceLastRun = lastRunTime?.timeIntervalSinceNow.magnitude


nit: how about consolidating the format of these two durations? either rounded (maybe better for visualization in Tracks event view) or double (probably better).

Since timeTaken is preexisting, I don't really want to change that to keep the data consistent. I'll round it for both.

jaclync · 2025-08-15T02:55:33Z

WooCommerce/Classes/Analytics/WooAnalyticsEvent+BackgroudUpdates.swift

            WooAnalyticsEvent(statName: .backgroundDataSynced, properties: [Keys.timeTaken: timeTaken])
        }

+        static func dataSyncedDetailed(


couldn't comment on an unchanged line, meant to comment on L20. as in the CI lint error, we can delete the dataSynced(timeTaken:) as it's not used anymore. let's also make sure to update the new event properties in the existing Tracks event.

jaclync · 2025-08-15T02:57:03Z

WooCommerce/Classes/Extensions/UserDefaults+Woo.swift


        // Background Task Refresh
        case latestBackgroundOrderSyncDate
+        case lastBackgroundRefreshTime


nit: maybe this could indicate that it's the "completion" time to be more exact.

Suggested change

case lastBackgroundRefreshTime

case lastBackgroundRefreshCompletionTime

jaclync · 2025-08-15T03:00:27Z

WooCommerce/Classes/Tools/BackgroundTasks/BackgroundTaskRefreshDispatcher.swift

+
+private struct BackgroundTaskSystemInfo {
+    let backgroundTimeGranted: TimeInterval?
+    let networkInfo: NetworkInfo


nit: this could be private

jaclync · 2025-08-15T03:04:40Z

WooCommerce/Classes/Tools/BackgroundTasks/BackgroundTaskRefreshDispatcher.swift

+        let device = UIDevice.current
+        device.isBatteryMonitoringEnabled = true
+
+        self.isPowered = device.batteryState == .charging || device.batteryState == .full


nit: how about just logging the battery state?

I think that will just log an int, not a useful string. Also during analysis, we'd have to check for both values which indicate that it's plugged in.

jaclync · 2025-08-15T03:05:07Z

WooCommerce/Classes/Analytics/WooAnalyticsEvent+BackgroudUpdates.swift

+            static let batteryLevel = "battery_level"
+            static let isLowPowerMode = "is_low_power_mode"
+            static let timeSinceLastRun = "time_since_last_run"
+            static let completionStatus = "completion_status"


nit: this isn't used, also noted in the CI lint error

jaclync · 2025-08-15T03:06:07Z

WooCommerce/Classes/Tools/BackgroundTasks/BackgroundTaskRefreshDispatcher.swift

        let refreshTasks = Task {
            do {
+                let systemInfo = await BackgroundTaskSystemInfo()
+                let lastRunTime = UserDefaults.standard[.lastBackgroundRefreshTime] as? Date


super nit: this could probably be moved to where the event is tracked?

toupper · 2025-08-15T09:28:52Z

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.

I'd say 23.0 beta, so we have more data when we needed. That said it's not urgent, so I leave the decision to @jaclync as the release manager.

joshheald · 2025-08-15T12:01:10Z

I'd say yes to 23.0 beta, mostly because I'm the release DRI 😆 . Otherwise, I feel like this isn't a very urgent change. It'd be the first time I'm generating a new beta, is the process to change the PR base to the release 23.0 branch and then I'll generate a new beta from the release dashboard?

OK, let's do it.

I've made a new branch, from release/23.0, and cherry-picked the changes across. We can't just change the base, that'll bring loads of other commits in...

I've made a new PR for it: #16014, and I've closed this one in favour of that.

You should be able to add a new release in the release tool for the 23.0 version. Let me know if you have any trouble though!

jaclync · 2025-08-18T02:10:44Z

We can't just change the base, that'll bring loads of other commits in...

Yea, if keeping the same PR, it'd require deleting commits from trunk manually by rebasing children of the branch iteratively. New PR looks good.

joshheald added 4 commits August 14, 2025 13:08

Add statistic tracking to background update tasks

b154c9a

Fix network info tracking on background tasks

919594c

Use concurrency instead of semaphores for async

91837a6

Tidy up comments and structure

c05ec92

joshheald added this to the 23.1 milestone Aug 14, 2025

joshheald added category: tracks Related to analytics, including Tracks Events. feature: POS labels Aug 14, 2025

joshheald assigned jaclync Aug 14, 2025

joshheald marked this pull request as ready for review August 14, 2025 14:17

joshheald unassigned jaclync Aug 14, 2025

joshheald requested a review from jaclync August 14, 2025 14:17

jaclync approved these changes Aug 15, 2025

View reviewed changes

joshheald added 2 commits August 15, 2025 11:56

Changes from code review

adf6881

Don’t wait for the system info before refreshing

9a05702

joshheald changed the base branch from trunk to release/23.0 August 15, 2025 11:50

joshheald changed the base branch from release/23.0 to trunk August 15, 2025 11:50

joshheald closed this Aug 15, 2025

joshheald mentioned this pull request Aug 15, 2025

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

Merged

1 task

	case lastBackgroundRefreshTime
	case lastBackgroundRefreshCompletionTime

[Woo POS][Local Catalog] Add Better Analytics to Background Task Refresh System #16011

[Woo POS][Local Catalog] Add Better Analytics to Background Task Refresh System #16011

Uh oh!

Conversation

joshheald commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Analytics Updates

System Info Collection

Analytics Properties

Steps to reproduce

Expected Results

Testing information

Screenshots

Uh oh!

wpmobilebot commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jaclync left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

toupper commented Aug 15, 2025

Uh oh!

joshheald commented Aug 15, 2025

Uh oh!

jaclync commented Aug 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

joshheald commented Aug 14, 2025 •

edited

Loading

wpmobilebot commented Aug 14, 2025 •

edited

Loading

jaclync left a comment •

edited

Loading