[Local catalog] Analytics for sync, launch, and loading

[joshheald]

Merge after #16342

Description

This PR adds analytics for sync, launch, and loading with the local catalog.

See pdfdoF-84z-p2 for full details. Note that the checkout events will be tackled in WOOMOB-1686

Events

Event Identifier	Properties	Description
woo_pos_local_catalog_downloading_screen_shown		Tracked when the app doesn’t have the local catalog in local storage and the app dispalys “sync in progress” screen.
woo_pos_local_catalog_downloading_screen_exit_pos_tapped		Tracked when the user taps on Exit POS or presses back button while local catalog is being synced.
woo_pos_splash_screen_error_shown		Tracked when opening the POS fails (e.g. catalog is empty and there isn’t an internet connection).
woo_pos_splash_screen_retry_tapped		Tracked when the user taps on retry on the splash screen error.
woo_pos_local_catalog_stale_warning_shown	hours_since_last_sync	Tracked when the POS displays a stale catalog notice.
woo_pos_local_catalog_stale_warning_dismissed		Tracked when the user taps on dismiss on the stale catalog notice.
woo_pos_loaded(existing event)	sync_strategy (remote, local_catalog)	Existing event – new attribute that indicates whether the new syncing approach is enabled.
woo_pos_local_catalog_sync_started	sync_type (full/incremental),connection_type (wifi/cellular/unknown)	Tracked when the sync job starts the syncing.
woo_pos_local_catalog_sync_completed	sync_type, products_synced, variations_synced,total_products, total_variations, sync_duration_ms	Tracked when the sync job finishes successfully.
woo_pos_local_catalog_sync_failed	sync_type, error_context, error_type (network_error/authentication_error/unexpected_error/insufficient_free_space/catalog_integrity), error_description	Tracked when the sync job finishes unsuccessfully.
woo_pos_local_catalog_sync_skipped	reason (feature_flag_disabled/user_not_logged_in/no_site_selected/pos_inactive/catalog_too_large)	Tracked when the sync job is skipped.

I've tested using WPcom and site credentials connections, which can cause differences in error types

Test Steps

Some of these will be easier to test on a large store, e.g. largefuntesting.mystagingwebsite.com. To use this, set POSLocalCatalogEligibilityService.Constants.defaultCatalogSizeLimit to 100000.

When you need to see the splash screen events, log out first, then log in, as the splash screen is only shown for the first successful sync.

You can force a sync to fail by repeatedly failing a single page of products – set a network breakpoint on /wc/v3/products, then fail one particular page for it's initial attempt, and all 3 backed-off retries. Use a 500 or similar.

You can simulate database errors by editing the grdbManager.databaseConnection.write blocks in POSCatalogPersistenceService, and throwing errors there, e.g. throw DatabaseError(resultCode: .SQLITE_FULL)

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 larger than 300 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.

	1 Message
📖	This PR contains changes to Tracks-related logic. Please ensure (author and reviewer) the following are completed: The tracks events must be validated in the Tracks system. Verify the internal Tracks spreadsheet has also been updated. Please consider registering any new events. The PR must be assigned the category: tracks label.

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	pr16345-50e3729
	Version	23.6
	Bundle ID	com.automattic.alpha.woocommerce
	Commit	50e3729
	Installation URL	7gl4bmallogd8

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

[iamgabrielma]

Works well!

✅ pos_local_catalog_downloading_screen_shown
✅ pos_local_catalog_downloading_screen_exit_pos_tapped
✅ local_catalog_stale_warning_shown
✅ local_catalog_stale_warning_dismissed
✅ pos_local_catalog_sync_started

	[connection_type: wifi, sync_type: full]
	[sync_type: incremental, connection_type: wifi]

✅ pos_local_catalog_sync_completed

	[sync_duration_ms: 108584, products_synced: 4976, variations_synced: 12458, total_variations: 12458, sync_type: full, total_products: 4976]
	[total_variations: 12458, total_products: 4976, sync_type: incremental, products_synced: 0, sync_duration_ms: 2001, variations_synced: 0]

✅ pos_local_catalog_sync_failed

	[error_type: unexpected_error, sync_type: full, error_domain: Yosemite.POSCatalogSyncError, error_code: 5, error_description: Yosemite.POSCatalogSyncError.requestCancelled]

✅ pos_local_catalog_sync_skipped

	[reason: catalog_not_stale]
	[reason: catalog_too_large]

I did not test the following 2 cases:

• pos_splash_screen_error_shown
• pos_splash_screen_retry_tapped

[iamgabrielma]

Should we do this on the view's init to avoid tracking multiple events on potential view recreation?

[iamgabrielma]

Good catch, when decorating pos events we've always considered that POS mode would be active...until now. Each time we deal with tracking events makes me wonder of the scalability of what we have.

[joshheald]

Yeah. Even just finding and remembering to add them to the list is a pain, tbh...

[iamgabrielma]

A bunch of these seem to fallback to network_error, do we plan to specialize them further later on? Otherwise perhaps can be simplified, ie: classifyURLError differentiates between 4 cases to just log network_error anyway, so:

    private static func classifyURLError(_ error: URLError) -> String {
        switch error.code {
        case .timedOut:
            return "network_timeout"
        default:
            return "network_error"
        }
    }

[iamgabrielma]

All of them seem to be using waiting time + additional props, we could declare this at the top:

            let props = [Keys.waitingTime: elapsedTime]
                .merging(additionalProperties.mapValues { $0 as WooAnalyticsEventPropertyType }) { $1 }

            switch scenario {
            case .orderDetails:
                return WooAnalyticsEvent(
                    statName: .orderDetailWaitingTimeLoaded,
                    properties: props)

And update the case for pointOfSaleLoaded

[iamgabrielma]

Maybe is worth to make an enum for the syncType we use in analytics

[iamgabrielma]

Nit, just for readability

Suggested change

	return (0, 0)
	return (products: 0, variations: 0)

[iamgabrielma]

Consider extending or moving this to POSLocalCatalogIneligibleReason

extension POSLocalCatalogIneligibleReason {
    var skipReason: String {
        switch self {
        case .posTabNotEligible:
            return "pos_inactive"
        case .featureFlagDisabled:
     
...

[iamgabrielma]

siteSettings is currently only set internally on POSCatalogSyncCoordinator, consider if we need to expose it or we can keep it private.

[joshheald]

We also use it in tests. We could make a new internal init for that but it seems pretty clunky. We can perhaps just rely on the default nil to omit it here though.

[iamgabrielma]

Forgot to add some notes from testing:

The local catalog settings tab does not seem to show if there's an error syncing, which disallows me to retry and click on the full sync button if this happens. It could be coincidence as well, since the tab is a bit finicky and does not always show at the moment.

When you need to see the splash screen events, log out first, then log in, as the splash screen is only shown for the first successful sync.

I couldn't trigger this one to show the splash screen when log in/out, neither uninstalling the app. Not specifically related to the event itself.

[joshheald]

The local catalog settings tab does not seem to show if there's an error syncing, which disallows me to retry and click on the full sync button if this happens. It could be coincidence as well, since the tab is a bit finicky and does not always show at the moment.

Yeah, I'll add a new ticket for this. Because it's essentially settings screen UI I've not really done anything about it yet, but it's at risk of getting missed.

I couldn't trigger this one to show the splash screen when log in/out, neither uninstalling the app. Not specifically related to the event itself.

No worries, I've tested them and they work. Couldn't have registered them otherwise! It's easier with a large catalog store and overriding the max catalog size, but you have to wait a moment so that you're deemed eligible for local catalog, so there's a slight balance. With <1000 products and fast network it's very difficult to hit it.

Thanks for the other points... I'll take a look before merging.