DataStore
1 month ago
Providers
3 months ago
Fulfillment.php
1 month ago
FulfillmentException.php
3 months ago
FulfillmentOrderNotes.php
3 months ago
FulfillmentUtils.php
2 months ago
FulfillmentsController.php
3 months ago
FulfillmentsManager.php
2 months ago
FulfillmentsRenderer.php
1 month ago
FulfillmentsSettings.php
3 months ago
FulfillmentsTracker.php
3 months ago
OrderFulfillmentsRestController.php
1 month ago
ShippingProviders.php
3 months ago
FulfillmentsTracker.php
385 lines
| 1 | <?php |
| 2 | |
| 3 | declare(strict_types=1); |
| 4 | |
| 5 | namespace Automattic\WooCommerce\Admin\Features\Fulfillments; |
| 6 | |
| 7 | use WC_Tracks; |
| 8 | |
| 9 | /** |
| 10 | * FulfillmentsTracker class. |
| 11 | * |
| 12 | * Centralizes all telemetry for the Fulfillments feature. Every tracked event is recorded via |
| 13 | * WC_Tracks::record_event() which sends it to the analytics pipeline with a "wcadmin_" prefix. |
| 14 | * |
| 15 | * Tracked events (WOOPLUG-5197): |
| 16 | * |
| 17 | * 1. Core Funnel (Adoption): |
| 18 | * - fulfillment_modal_opened : Merchant opens the fulfillment editor drawer. (Frontend only) |
| 19 | * - fulfillment_created : A new fulfillment is saved. (REST controller) |
| 20 | * - fulfillment_updated : An existing fulfillment is modified. (REST controller) |
| 21 | * - fulfillment_deleted : A fulfillment is deleted. (REST controller) |
| 22 | * |
| 23 | * 2. Tracking Information (Usage Patterns): |
| 24 | * - fulfillment_tracking_added : Tracking info is attached to a fulfillment. (REST controller) |
| 25 | * - fulfillment_tracking_lookup_attempted : Tracking number auto-lookup is attempted. (FulfillmentsManager) |
| 26 | * |
| 27 | * 3. Efficiency / Power-User: |
| 28 | * - fulfillment_bulk_action_used : Bulk fulfill/unfulfill from the orders list. (FulfillmentsRenderer) |
| 29 | * - fulfillment_filter_used : Orders list filtered by fulfillment status/provider. (FulfillmentsRenderer) |
| 30 | * |
| 31 | * 4. Customer Communication: |
| 32 | * - fulfillment_notification_sent : A fulfillment email is queued to the customer. (REST controller) |
| 33 | * - fulfillment_email_template_customized : Merchant saves fulfillment email template settings. (FulfillmentsManager) |
| 34 | * |
| 35 | * 5. Friction / Errors: |
| 36 | * - fulfillment_validation_error : A create/update/delete action fails validation. (REST controller) |
| 37 | * |
| 38 | * @since 10.7.0 |
| 39 | */ |
| 40 | class FulfillmentsTracker { |
| 41 | |
| 42 | // ────────────────────────────────────────────── |
| 43 | // 1. Core Funnel: Fulfillment Creation & Management |
| 44 | // ────────────────────────────────────────────── |
| 45 | |
| 46 | /** |
| 47 | * Track when a merchant opens the fulfillment editor modal/sidebar. |
| 48 | * |
| 49 | * Tracked from: Frontend (JS recordEvent). |
| 50 | * Measures: Feature discoverability and adoption. |
| 51 | * |
| 52 | * @since 10.7.0 |
| 53 | * |
| 54 | * @param string $source Where the modal was opened from ("orders_list" or "order_detail_page"). |
| 55 | * @param int $order_id The ID of the order being viewed. |
| 56 | * |
| 57 | * @return void |
| 58 | */ |
| 59 | public static function track_fulfillment_modal_opened( string $source, int $order_id ): void { |
| 60 | WC_Tracks::record_event( |
| 61 | 'fulfillment_modal_opened', |
| 62 | array( |
| 63 | 'source' => $source, |
| 64 | 'order_id' => $order_id, |
| 65 | ) |
| 66 | ); |
| 67 | } |
| 68 | |
| 69 | /** |
| 70 | * Track when a new fulfillment is successfully saved. |
| 71 | * |
| 72 | * Tracked from: OrderFulfillmentsRestController::create_fulfillment(). |
| 73 | * Measures: Core adoption; whether merchants create full vs. partial shipments. |
| 74 | * |
| 75 | * @since 10.7.0 |
| 76 | * |
| 77 | * @param string $source The source of the fulfillment ("fulfillments_modal", "bulk_action", or "api"). |
| 78 | * @param string $initial_status The initial status of the fulfillment ("draft" or "fulfilled"). |
| 79 | * @param string $fulfillment_type Whether all remaining items were included ("full" or "partial"). |
| 80 | * @param int $item_count Total quantity of items in the fulfillment (sum of item quantities). |
| 81 | * @param int $total_quantity Total quantity of all items in the order. |
| 82 | * @param bool $notification_sent Whether the customer notification was requested. |
| 83 | * @return void |
| 84 | */ |
| 85 | public static function track_fulfillment_creation( string $source, string $initial_status, string $fulfillment_type, int $item_count, int $total_quantity, bool $notification_sent ): void { |
| 86 | WC_Tracks::record_event( |
| 87 | 'fulfillment_created', |
| 88 | array( |
| 89 | 'source' => $source, |
| 90 | 'initial_status' => $initial_status, |
| 91 | 'fulfillment_type' => $fulfillment_type, |
| 92 | 'item_count' => $item_count, |
| 93 | 'total_quantity' => $total_quantity, |
| 94 | 'notification_sent' => $notification_sent, |
| 95 | ) |
| 96 | ); |
| 97 | } |
| 98 | |
| 99 | /** |
| 100 | * Track when an existing fulfillment is successfully updated. |
| 101 | * |
| 102 | * Tracked from: OrderFulfillmentsRestController::update_fulfillment(). |
| 103 | * Measures: How often merchants modify fulfillments and which fields change most. |
| 104 | * |
| 105 | * @since 10.7.0 |
| 106 | * |
| 107 | * @param string $source The source of the update ("fulfillments_modal" or "api"). |
| 108 | * @param int $fulfillment_id The ID of the fulfillment being updated. |
| 109 | * @param string $original_status The status before the update ("draft" or "fulfilled"). |
| 110 | * @param array $changed_fields The changes as returned by Fulfillment::get_changes(). Core data |
| 111 | * props (e.g. 'status') at top level, meta changes under 'meta_data'. |
| 112 | * Serialized as JSON by WC_Tracks. |
| 113 | * @param bool $notification_sent Whether a customer re-notification was requested. |
| 114 | * |
| 115 | * @return void |
| 116 | */ |
| 117 | public static function track_fulfillment_update( string $source, int $fulfillment_id, string $original_status, array $changed_fields, bool $notification_sent ): void { |
| 118 | WC_Tracks::record_event( |
| 119 | 'fulfillment_updated', |
| 120 | array( |
| 121 | 'source' => $source, |
| 122 | 'fulfillment_id' => $fulfillment_id, |
| 123 | 'original_status' => $original_status, |
| 124 | 'changed_fields' => $changed_fields, |
| 125 | 'notification_sent' => $notification_sent, |
| 126 | ) |
| 127 | ); |
| 128 | } |
| 129 | |
| 130 | /** |
| 131 | * Track when a fulfillment is successfully deleted. |
| 132 | * |
| 133 | * Tracked from: OrderFulfillmentsRestController::delete_fulfillment(). |
| 134 | * Measures: How often merchants remove fulfillments and at what stage. |
| 135 | * |
| 136 | * @since 10.7.0 |
| 137 | * |
| 138 | * @param string $source The source of the deletion ("fulfillments_modal" or "api"). |
| 139 | * @param int $fulfillment_id The ID of the fulfillment being deleted. |
| 140 | * @param string $status_at_deletion The status at the time of deletion ("draft" or "fulfilled"). |
| 141 | * @param bool $notification_sent Whether a deletion notification was requested. |
| 142 | * |
| 143 | * @return void |
| 144 | */ |
| 145 | public static function track_fulfillment_deletion( string $source, int $fulfillment_id, string $status_at_deletion, bool $notification_sent ): void { |
| 146 | WC_Tracks::record_event( |
| 147 | 'fulfillment_deleted', |
| 148 | array( |
| 149 | 'source' => $source, |
| 150 | 'fulfillment_id' => $fulfillment_id, |
| 151 | 'status_at_deletion' => $status_at_deletion, |
| 152 | 'notification_sent' => $notification_sent, |
| 153 | ) |
| 154 | ); |
| 155 | } |
| 156 | |
| 157 | // ────────────────────────────────────────────── |
| 158 | // 2. Tracking Information Workflow |
| 159 | // ────────────────────────────────────────────── |
| 160 | |
| 161 | /** |
| 162 | * Track when tracking information is successfully added to a fulfillment. |
| 163 | * |
| 164 | * Tracked from: OrderFulfillmentsRestController (create and update flows). |
| 165 | * Measures: How merchants add tracking info (auto-lookup vs. manual vs. API) and which |
| 166 | * carriers are used. The provider_name property for custom providers is used to |
| 167 | * identify the most frequently added custom carriers, informing the roadmap for |
| 168 | * expanding native carrier support. |
| 169 | * |
| 170 | * @since 10.7.0 |
| 171 | * |
| 172 | * @param int $fulfillment_id The ID of the fulfillment to which tracking was added. |
| 173 | * @param string $entry_method How the tracking was added ("ui_auto_lookup", "ui_manual_select", "ui_manual_custom", or "api"). |
| 174 | * @param string $provider_name The name/key of the shipping provider (e.g., "usps", "fedex"). |
| 175 | * @param bool $is_custom_provider Whether the provider is a custom (non-native) provider. |
| 176 | * |
| 177 | * @return void |
| 178 | */ |
| 179 | public static function track_fulfillment_tracking_added( int $fulfillment_id, string $entry_method, string $provider_name, bool $is_custom_provider ): void { |
| 180 | WC_Tracks::record_event( |
| 181 | 'fulfillment_tracking_added', |
| 182 | array( |
| 183 | 'fulfillment_id' => $fulfillment_id, |
| 184 | 'entry_method' => $entry_method, |
| 185 | 'provider_name' => $provider_name, |
| 186 | 'is_custom_provider' => $is_custom_provider, |
| 187 | ) |
| 188 | ); |
| 189 | } |
| 190 | |
| 191 | /** |
| 192 | * Track when a tracking number auto-lookup is attempted. |
| 193 | * |
| 194 | * Tracked from: FulfillmentsManager::try_parse_tracking_number(). |
| 195 | * Measures: Effectiveness of auto-detection. A high failure rate indicates the need to improve |
| 196 | * carrier detection logic. The url_generated flag checks if a functional tracking URL |
| 197 | * was constructed (a success requires both provider identification AND URL generation). |
| 198 | * |
| 199 | * @since 10.7.0 |
| 200 | * |
| 201 | * @param string $lookup_status The lookup result ("success" or "not_found"). |
| 202 | * @param string $provider_identified The standardized carrier name identified (e.g., "usps"). Empty if not found. |
| 203 | * @param bool $url_generated Whether the system successfully constructed a tracking URL. |
| 204 | * |
| 205 | * @return void |
| 206 | */ |
| 207 | public static function track_fulfillment_tracking_lookup_attempt( string $lookup_status, string $provider_identified, bool $url_generated = false ): void { |
| 208 | WC_Tracks::record_event( |
| 209 | 'fulfillment_tracking_lookup_attempted', |
| 210 | array( |
| 211 | 'lookup_status' => $lookup_status, |
| 212 | 'provider_identified' => $provider_identified, |
| 213 | 'url_generated' => $url_generated, |
| 214 | ) |
| 215 | ); |
| 216 | } |
| 217 | |
| 218 | // ────────────────────────────────────────────── |
| 219 | // 3. Efficiency & Power-User Features |
| 220 | // ────────────────────────────────────────────── |
| 221 | |
| 222 | /** |
| 223 | * Track when a merchant applies a fulfillment-related bulk action from the orders list. |
| 224 | * |
| 225 | * Tracked from: FulfillmentsRenderer::handle_fulfillment_bulk_actions(). |
| 226 | * Measures: Whether merchants use the time-saving bulk-fulfill feature. |
| 227 | * |
| 228 | * @since 10.7.0 |
| 229 | * |
| 230 | * @param string $action The action performed ("fulfill_orders" or "unfulfill_orders"). |
| 231 | * @param int $order_count The number of orders selected for the bulk action. |
| 232 | * |
| 233 | * @return void |
| 234 | */ |
| 235 | public static function track_fulfillment_bulk_action_used( string $action, int $order_count ): void { |
| 236 | WC_Tracks::record_event( |
| 237 | 'fulfillment_bulk_action_used', |
| 238 | array( |
| 239 | 'action' => $action, |
| 240 | 'order_count' => $order_count, |
| 241 | ) |
| 242 | ); |
| 243 | } |
| 244 | |
| 245 | /** |
| 246 | * Track when the orders list is filtered using a fulfillment-related filter. |
| 247 | * |
| 248 | * Tracked from: FulfillmentsRenderer::filter_orders_list_table_query(). |
| 249 | * Measures: Whether merchants use fulfillment filters and which values they filter by most. |
| 250 | * |
| 251 | * @since 10.7.0 |
| 252 | * |
| 253 | * @param string $filter_by The filter field ("fulfillment_status" or "shipping_provider"). |
| 254 | * @param string $filter_value The specific value selected (e.g., "partially_fulfilled", "usps"). |
| 255 | * |
| 256 | * @return void |
| 257 | */ |
| 258 | public static function track_fulfillment_filter_used( string $filter_by, string $filter_value ): void { |
| 259 | WC_Tracks::record_event( |
| 260 | 'fulfillment_filter_used', |
| 261 | array( |
| 262 | 'filter_by' => $filter_by, |
| 263 | 'filter_value' => $filter_value, |
| 264 | ) |
| 265 | ); |
| 266 | } |
| 267 | |
| 268 | // ────────────────────────────────────────────── |
| 269 | // 4. Customer Communication |
| 270 | // ────────────────────────────────────────────── |
| 271 | |
| 272 | /** |
| 273 | * Track when a fulfillment notification email is successfully queued to a customer. |
| 274 | * |
| 275 | * Tracked from: OrderFulfillmentsRestController (create, update, and delete flows). |
| 276 | * Measures: Whether the communication loop is being closed; how often merchants notify customers. |
| 277 | * |
| 278 | * @since 10.7.0 |
| 279 | * |
| 280 | * @param string $trigger_action The action that triggered the notification ("fulfillment_created", "fulfillment_updated", or "fulfillment_deleted"). |
| 281 | * @param int $fulfillment_id The ID of the fulfillment. |
| 282 | * @param int $order_id The ID of the associated order. |
| 283 | * |
| 284 | * @return void |
| 285 | */ |
| 286 | public static function track_fulfillment_notification_sent( string $trigger_action, int $fulfillment_id, int $order_id ): void { |
| 287 | WC_Tracks::record_event( |
| 288 | 'fulfillment_notification_sent', |
| 289 | array( |
| 290 | 'trigger_action' => $trigger_action, |
| 291 | 'fulfillment_id' => $fulfillment_id, |
| 292 | 'order_id' => $order_id, |
| 293 | ) |
| 294 | ); |
| 295 | } |
| 296 | |
| 297 | /** |
| 298 | * Track when a merchant saves changes to a fulfillment email template in settings. |
| 299 | * |
| 300 | * Tracked from: FulfillmentsManager (hooked to woocommerce_update_options_email_{id}). |
| 301 | * Measures: Whether merchants customize fulfillment email templates. |
| 302 | * |
| 303 | * @since 10.7.0 |
| 304 | * |
| 305 | * @param string $template_name The email template ID that was customized (e.g., "customer_fulfillment_created"). |
| 306 | * |
| 307 | * @return void |
| 308 | */ |
| 309 | public static function track_fulfillment_email_template_customized( string $template_name ): void { |
| 310 | WC_Tracks::record_event( |
| 311 | 'fulfillment_email_template_customized', |
| 312 | array( |
| 313 | 'template_name' => $template_name, |
| 314 | ) |
| 315 | ); |
| 316 | } |
| 317 | |
| 318 | // ────────────────────────────────────────────── |
| 319 | // 5. Friction & Error Tracking |
| 320 | // ────────────────────────────────────────────── |
| 321 | |
| 322 | /** |
| 323 | * Track when a fulfillment action fails due to a validation error. |
| 324 | * |
| 325 | * Tracked from: OrderFulfillmentsRestController (create, update, and delete flows). |
| 326 | * Measures: Where users encounter errors; helps proactively identify bugs and UX problems. |
| 327 | * |
| 328 | * @since 10.7.0 |
| 329 | * |
| 330 | * @param string $action_attempted The action that was attempted ("create", "update", "delete", or "fulfill"). |
| 331 | * @param string $error_code The error code from the exception. |
| 332 | * @param string $source The source of the error ("fulfillments_modal", "bulk_action", or "api"). |
| 333 | * |
| 334 | * @return void |
| 335 | */ |
| 336 | public static function track_fulfillment_validation_error( string $action_attempted, string $error_code, string $source ): void { |
| 337 | WC_Tracks::record_event( |
| 338 | 'fulfillment_validation_error', |
| 339 | array( |
| 340 | 'action_attempted' => $action_attempted, |
| 341 | 'error_code' => $error_code, |
| 342 | 'source' => $source, |
| 343 | ) |
| 344 | ); |
| 345 | } |
| 346 | |
| 347 | // ────────────────────────────────────────────── |
| 348 | // Helpers |
| 349 | // ────────────────────────────────────────────── |
| 350 | |
| 351 | /** |
| 352 | * Determine the tracking entry method from the request source and fulfillment meta data. |
| 353 | * |
| 354 | * Maps the shipping option meta value to the standardized entry_method values expected |
| 355 | * by the fulfillment_tracking_added event. Whether the provider is custom or native is |
| 356 | * tracked separately via the is_custom_provider property on the event. |
| 357 | * |
| 358 | * - "ui_auto_lookup" : Tracking number was auto-detected via the lookup API. |
| 359 | * - "ui_manual" : Merchant manually selected or entered a provider. |
| 360 | * - "api" : Tracking was added via the REST API (not through the UI). |
| 361 | * |
| 362 | * @since 10.7.0 |
| 363 | * |
| 364 | * @param string $source The request source ("fulfillments_modal" or "api"). |
| 365 | * @param string $shipping_option The shipping option meta value ("tracking-number", "manual-entry", or "no-info"). |
| 366 | * |
| 367 | * @return string The entry method identifier. |
| 368 | */ |
| 369 | public static function determine_tracking_entry_method( string $source, string $shipping_option ): string { |
| 370 | if ( 'fulfillments_modal' !== $source ) { |
| 371 | return 'api'; |
| 372 | } |
| 373 | |
| 374 | if ( 'tracking-number' === $shipping_option ) { |
| 375 | return 'ui_auto_lookup'; |
| 376 | } |
| 377 | |
| 378 | if ( 'manual-entry' === $shipping_option ) { |
| 379 | return 'ui_manual'; |
| 380 | } |
| 381 | |
| 382 | return 'api'; |
| 383 | } |
| 384 | } |
| 385 |