WC Telemetry: add first_used and installation_date data to WCTracker

[jaclync]

Submission Review Guidelines:

• I have followed the WooCommerce Contributing Guidelines and the WordPress Coding Standards.
• I have checked to ensure there aren't other open Pull Requests for the same update/change.
• I have reviewed my code for security best practices.
• Following the above guidelines will result in quick merges and clear and detailed feedback when appropriate.

Changes proposed in this Pull Request:

Part of woocommerce/woocommerce-ios#10406

After the initial implementation of the telemetry endpoint #30415, this PR adds tracking for first_used and installation_date that are sent to WCTracker for a better understanding of the Woo mobile merchants.

first_used

When saving the mobile usage data for the first time, first_used field is set to be the same as last_used (the time of the request). For stores that already have the mobile usage data (last_used has been set), they won't have a first_used date so that we can track the usage more accurately.

installation_date

This is an optional field since earlier mobile versions don't track and send the installation date. It's set once when the field hasn't been set before, whether the store has existing mobile usage data or not.

💬 @shiki feel free to suggest a different definition based on the business requirements.

How to test the changes in this Pull Request:

Prerequisite: the site hasn't had any mobile usage data tracked yet (like a brand new site), and supports https so that it can use the REST API key & secret to make API requests. I personally use Local for development for the ease of adding SSL to the site.

1. Send a POST request to the /wp-json/wc-telemetry/tracker endpoint with body: { "platform": "ios", "version": "1.2", "installation_date": "2023-08-08T03:48:50Z" }. The response should have a 200 status, but no response body.
2. Via WP-CLI or similar, execute WC_Tracker::get_tracking_data() --> wc_mobile_usage should show an entry for ios, and the data underneath should include version: 1.2, installation_date: 2023-08-08T03:48:50+00:00, and the same first_used and last used dates in ISO 8601 format
   • Example: wp eval "var_dump(WC_Tracker::get_tracking_data()['wc_mobile_usage']);"
3. Send another POST request to the telemetry endpoint with body: { "platform": "ios", "version": "1.2", "installation_date": "2023-08-10T03:48:50Z" } --> in WCTracker from WP-CLI, wc_mobile_usage should show an entry for ios, and the data underneath should include version: 1.2, installation_date: 2023-08-08T03:48:50+00:00 (same as the previous value), and the first_used date should not be changed from the previous value while last used should be updated to the latest request time.
4. You can "reset" the mobile usage data for further testing by deleting the relevant option:
   • wp option delete woocommerce_mobile_app_usage

Note: If using wp shell to test, you may have to close the shell session and re-open if the option value is cached.

[github-actions]

Test Results Summary

Commit SHA: c8fbccb

Test 🧪	Passed ✅	Failed 🚨	Broken 🚧	Skipped ⏭️	Unknown ❔	Total 📊	Duration ⏱️
API Tests	259	0	0	2	0	261	1m 1s
E2E Tests	195	0	0	15	0	210	17m 36s

---

To view the full API test report, click here.
To view the full E2E test report, click here.
To view all test reports, visit the WooCommerce Test Reports Dashboard.

[github-actions]

Hi @coreymckrill,

Apart from reviewing the code changes, please make sure to review the testing instructions as well.

You can follow this guide to find out what good testing instructions should look like:
https://github.com/woocommerce/woocommerce/wiki/Writing-high-quality-testing-instructions

[shiki]

Thank you for working on this, @jaclync. It looks like this is generally want we want. I have one question.

I haven't really set up my development environment yet. But even if I did, I would ask help from the dev team to help review this. 😁

@coreymckrill would you be able to review this PR? 🙏

[shiki]

I'm not sure what will happen if the $installation_date is null. It looks like it will return a date regardless. We probably want to return a null instead.

I'm mentioning this because on the following code, we just copy over everything that is in $new. And I believe that includes $new['installation_date']. 🤔 So even if the client doesn't send installation_date, it will still be set?

woocommerce/plugins/woocommerce/includes/rest-api/Controllers/Telemetry/class-wc-rest-telemetry-controller.php

Lines 97 to 101 in 71d47d6

	} else {
	// Only sets `first_used` when the platform usage data hasn't been set before.
	$new['first_used'] = $new['last_used'];
	$data[ $platform ] = $new;
	}

Maybe we also want to add a unit test that the endpoint behaves as expected if the iOS and Android clients are old (they only pass version and platform). Maybe confirm that installation_date is not set in that scenario. I think we don't have a test for this yet. But please let me know if I just missed it. 😅

[coreymckrill]

So even if the client doesn't send installation_date, it will still be set?

Just tried this, and it's true. It just set the current date/time.

[jaclync]

Great catch on this case that I missed! I was able to reproduce it in a test case and API testing like Corey shared. Updated in f22cff1 for another look!

[coreymckrill]

👍 Worked as described in local testing. I also tried:

• Sending a request with an installation_date key but no value (400 Bad Request)
• Sending a second request with a different installation_date value from the first one (The first value is not overwritten)

I updated the testing instructions slightly to describe how to "reset" the usage data using WP-CLI.

[rodelgc]

Thanks for your code review and for adding an additional "reset" step, @coreymckrill. Approving and merging this one now.