dev: added docs for core profiler (#39963)
* dev: added docs for core profiler * lint * Add changefile(s) from automation for the following project(s): woocommerce --------- Co-authored-by: github-actions <github-actions@github.com>
This commit is contained in:
RJ
GitHub
parent
26fde13e00
commit
3f3f032ed5
|
|
@ -0,0 +1,90 @@
|
|||
# Core Profiler
|
||||
|
||||
The Core Profiler feature is a modernized and simplified new user setup experience for WooCommerce core. It is the first thing a new merchant will see upon installation of WooCommerce.
|
||||
|
||||
It requests the minimum amount of information from a merchant to get their store up and running, and suggests some optional extensions that may fulfil common needs for new stores.
|
||||
|
||||
There are 4 pages in the Core Profiler:
|
||||
|
||||
1. Introduction & Data sharing opt-in
|
||||
2. User Profile - Some questions determining the user's entry point to the WooCommerce setup
|
||||
3. Business Information - Store Details and Location
|
||||
4. Extensions - Optional extensions that may be useful to the merchant
|
||||
|
||||
If the merchant chooses to install any extensions that require Jetpack, they will then be redirected to WordPress.com to login to Jetpack after the extensions page. Upon completion of that, they will be returned back to the WooCommerce Admin homescreen which contains the Task List. The Task List will provide next steps for the merchant to continue with their store setup.
|
||||
|
||||
## Development
|
||||
|
||||
The Core Profiler is gated behind the `core-profiler` feature flag, but is enabled by default.
|
||||
|
||||
This feature is the first feature in WooCommerce to use XState for state management, and so naming and organisational conventions will be developed as the team's experience with XState grows.
|
||||
|
||||
Refer to the [XState Dev Tooling](xstate.md) documentation for information on how to use the XState visualizer to debug the state machines.
|
||||
|
||||
The state machine for the Core Profiler is centrally located at `./client/core-profiler/index.tsx`, and is responsible for managing the state of the entire feature. It is responsible for rendering the correct page based on the current state, handling events that are triggered by the user, triggering side effects such as API calls and handling the responses. It also handles updating the browser URL state as well as responding to changes in it.
|
||||
|
||||
While working on this feature, bear in mind that the state machine should interact with WordPress and WooCommerce via actions and services, and the UI code should not be responsible for any API calls or interaction with WordPress Data Stores. This allows us to easily render the UI pages in isolation, for example use in Storybook. The UI pages should only send events back to the state machine in order to trigger side effects.
|
||||
|
||||
## Saving and retrieving data
|
||||
|
||||
As of writing, the following options are saved (and retrieved if the user has already completed the Core Profiler):
|
||||
|
||||
- `blogname`: string
|
||||
|
||||
This stores the name of the store, which is used in the store header and in the browser tab title, among other places.
|
||||
|
||||
- `woocommerce_onboarding_profile`:
|
||||
|
||||
```typescript
|
||||
{
|
||||
business_choice: "im_just_starting_my_business" | "im_already_selling" | "im_setting_up_a_store_for_a_client" | undefined
|
||||
selling_online_answer: "yes_im_selling_online" | "no_im_selling_offline" | "im_selling_both_online_and_offline" | undefined
|
||||
selling_platforms: ("amazon" | "adobe_commerce" | "big_cartel" | "big_commerce" | "ebay" | "ecwid" | "etsy" | "facebook_marketplace" | "google_shopping" | "pinterest" | "shopify" | "square" | "squarespace" | "wix" | "wordpress")[] | undefined
|
||||
is_store_country_set: true | false
|
||||
industry: "clothing_and_accessories" | "health_and_beauty" | "food_and_drink" | "home_furniture_and_garden" | "education_and_learning" | "electronics_and_computers" | "other"
|
||||
}
|
||||
```
|
||||
|
||||
This stores the merchant's onboarding profile, some of which are used for suggesting extensions and toggling other features.
|
||||
|
||||
- `woocommerce_default_country`: e.g 'US:CA', 'SG', 'AU:VIC'
|
||||
|
||||
This stores the location that the WooCommerce store believes it is in. This is used for determining extensions eligibility.
|
||||
|
||||
- `woocommerce_allow_tracking`: 'yes' | 'no'
|
||||
|
||||
This determines whether we return telemetry to Automattic.
|
||||
|
||||
As this information is not automatically updated, it would be best to refer directly to the data types present in the source code for the most up to date information.
|
||||
|
||||
### API Calls
|
||||
|
||||
The following WP Data API calls are used in the Core Profiler:
|
||||
|
||||
- `resolveSelect( ONBOARDING_STORE_NAME ).getFreeExtensions()`
|
||||
|
||||
This is used to retrieve the list of extensions that will be shown on the Extensions page. It makes an API call to the WooCommerce REST API, which will make a call to WooCommerce.com if permitted. Otherwise it retrieves the locally stored list of free extensions.
|
||||
|
||||
- `resolveSelect( COUNTRIES_STORE_NAME ).getCountries()`
|
||||
|
||||
This is used to retrieve the list of countries that will be shown in the Country dropdown on the Business Information page. It makes an API call to the WooCommerce REST API.
|
||||
|
||||
- `resolveSelect( COUNTRIES_STORE_NAME ).geolocate()`
|
||||
|
||||
This is used to retrieve the country that the store believes it is in. It makes an API call to the WordPress.com geolocation API, if permitted. Otherwise it will not be used.
|
||||
|
||||
- `resolveSelect( PLUGINS_STORE_NAME ).isJetpackConnected()`
|
||||
|
||||
This is used to determine whether the store is connected to Jetpack.
|
||||
|
||||
- `resolveSelect( ONBOARDING_STORE_NAME ).getJetpackAuthUrl()`
|
||||
|
||||
This is used to retrieve the URL that the browser should be redirected to in order to connect to Jetpack.
|
||||
|
||||
### Extensions Installation
|
||||
|
||||
The Core Profiler has a loading screen that is shown after the Extensions page. This loading screen is meant to hide the installation of Extensions, while also giving the user a sense of progress. At the same time, some extensions take extremely long to install, and thus we have a 30 second timeout.
|
||||
|
||||
The selected extensions will be put into an installation queue, and the queue will be processed sequentially while the loader is on screen.
|
||||
|
||||
Beyond the 30 second timeout, the remaining plugins will be installed in the background, and the user will be redirected to the WooCommerce Admin homescreen or the Jetpack connection page.
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# WooCommerce Onboarding
|
||||
# WooCommerce Onboarding (DEPRECATED)
|
||||
|
||||
**Refer to the new [Core Profiler](./core-profiler.md) documentation for the latest onboarding experience.**
|
||||
|
||||
**Some parts of this documentation are still relevant and will be gradually moved to the new Core Profiler documentation.**
|
||||
|
||||
The onboarding feature is a reimagined new user setup experience for WooCommerce core. It contains two sections aimed at getting merchants started with their stores. The merchant begins with the "profile wizard", which helps with initial steps like setting a store address, making extension recommendations, and connecting to Jetpack for additional features. Once the profile wizard is complete, the merchant can purchase & install optional extensions via WooCommerce.com, before continuing to the "task list". From the task list, merchants are walked through a variety of items to help them start selling, such as adding their first product and setting up payment methods.
|
||||
|
||||
|
|
@ -6,7 +10,7 @@ The onboarding feature is a reimagined new user setup experience for WooCommerce
|
|||
|
||||
If you run the development version of WooCommerce Admin from GitHub directly, no further action should be needed to enable Onboarding.
|
||||
|
||||
Users of the published WooCommerce Admin plugin need to either opt-in to using the new onboarding experience manually, or become part of the a/b test in core. See https://github.com/woocommerce/woocommerce/pull/24991 for more details on the testing implementation.
|
||||
Users of the published WooCommerce Admin plugin need to either opt-in to using the new onboarding experience manually, or become part of the a/b test in core. See [https://github.com/woocommerce/woocommerce/pull/24991](https://github.com/woocommerce/woocommerce/pull/24991) for more details on the testing implementation.
|
||||
|
||||
To enable the new onboarding experience manually, log-in to `wp-admin`, and go to `WooCommerce > Settings > Help > Setup Wizard`. Click `Enable` under the `New onboarding experience` heading.
|
||||
|
||||
|
|
@ -63,7 +67,7 @@ To make the connection from the new onboarding experience possible, we build our
|
|||
|
||||
Both of these endpoints use WooCommerce Core's `WC_Helper_API` directly. The main difference with our connection (compared to the connection on the subscriptions page) is the addition of two additional query string parameters:
|
||||
|
||||
* `wccom-from=onboarding`, which is used to tell WooCommerce.com & WordPress.com that we are connecting from the new onboarding flow. This parameter is passed from the user's site to WooCommerce.com and finally into Calypso, so that the Calypso login and sign-up screens match the rest of the profile wizard (https://github.com/Automattic/wp-calypso/pull/35193). Without this parameter, you would end up on the existing WooCommerce OAuth screen.
|
||||
* `wccom-from=onboarding`, which is used to tell WooCommerce.com & WordPress.com that we are connecting from the new onboarding flow. This parameter is passed from the user's site to WooCommerce.com and finally into Calypso, so that the Calypso login and sign-up screens match the rest of the profile wizard [https://github.com/Automattic/wp-calypso/pull/35193](https://github.com/Automattic/wp-calypso/pull/35193). Without this parameter, you would end up on the existing WooCommerce OAuth screen.
|
||||
* `calypso_env` allows us to load different versions of Calypso when testing. See the Calypso section below.
|
||||
|
||||
To disconnect from WooCommerce.com, go to `WooCommerce > Extensions > WooCommerce.com Subscriptions > Connected to WooCommerce.com > Disconnect`.
|
||||
|
|
@ -77,7 +81,7 @@ We have a special Jetpack connection flow designed specifically for WooCommerce
|
|||
We use Jetpack's `build_connect_url` function directly, but add the following two query parameters:
|
||||
|
||||
* `calypso_env`, which allows us to load different versions of Calypso when testing. See the Calypso section below.
|
||||
* `from=woocommerce-onboarding`, which is used to conditionally show the WooCommerce themed Jetpack authorization process (https://github.com/Automattic/wp-calypso/pull/34380). Without this parameter, you would end up in the normal Jetpack authorization flow.
|
||||
* `from=woocommerce-onboarding`, which is used to conditionally show the WooCommerce themed Jetpack authorization process [https://github.com/Automattic/wp-calypso/pull/34380](https://github.com/Automattic/wp-calypso/pull/34380). Without this parameter, you would end up in the normal Jetpack authorization flow.
|
||||
|
||||
The user is prompted to install and connect to Jetpack as the first step of the profile wizard. If the user hasn't connected when they arrive at the task list, we also prompt them on certain tasks to make the setup process easier, such as the shipping and tax steps.
|
||||
|
||||
|
|
@ -89,7 +93,7 @@ To disconnect from Jetpack, go to `Jetpack > Dashboard > Connections > Site conn
|
|||
|
||||
Both the WooCommerce.com & Jetpack connection processes (outlined below) send the user to [Calypso](https://github.com/Automattic/wp-calypso), the interface that powers WordPress.com, to sign-up or login.
|
||||
|
||||
By default, a merchant will end up on a production version of Calypso (https://wordpress.com). If we make changes to the Calypso part of the flow and want to test them, we can do so with a `calypso_env` query parameter passed by both of our connection methods.
|
||||
By default, a merchant will end up on a production version of Calypso [https://wordpress.com](https://wordpress.com). If we make changes to the Calypso part of the flow and want to test them, we can do so with a `calypso_env` query parameter passed by both of our connection methods.
|
||||
|
||||
To change the value of `calypso_env`, set `WOOCOMMERCE_CALYPSO_ENVIRONMENT` to one of the following values in your `wp-config.php`:
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,50 @@
|
|||
# XState Dev Tooling
|
||||
|
||||
XState is a state management framework for Javascript applications. It is based on the concept of [finite state machines](https://en.wikipedia.org/wiki/Finite-state_machine) and statecharts.
|
||||
|
||||
In order to help you visualize and debug the state machines within WooCommerce Core, XState provides a [visualizer](https://stately.ai/viz) that you can use in your browser.
|
||||
|
||||
|
||||
## Enabling the visualizer
|
||||
|
||||
To enable this, run this command in your browser's developer console:
|
||||
|
||||
```js
|
||||
localStorage.setItem('xstate_inspect', 'true');
|
||||
```
|
||||
|
||||
Then, a new tab with the XState visualizer should appear for pages that have state machines.
|
||||
|
||||
## Using the visualizer
|
||||
|
||||
|
||||
### Main View
|
||||
|
||||
The main panel in the visualizer will show you the current state of the state machine. Current states are shown with a blue border, and available transitions are solid blue bubbles. If the events are simple without payload requirements, you can click on the transition bubbles to trigger the transition. Otherwise, you can use the 'Send event' button on the bottom right of the visualizer to send events to the state machine.
|
||||
|
||||
|
||||
### State Tab
|
||||
|
||||
The context is the working memory that the state machine has access to. It is a plain Javascript object that can be modified by the state machine.
|
||||
|
||||
Within the 'State' tab, you can see the printouts of three objects: "Value", "Context", and "State".
|
||||
|
||||
The 'Value' object is simply the current state that the state machine is in, and it may be an object if there are nested state machines.
|
||||
|
||||
The 'Context' object is the current context of the state machine. It is a plain Javascript object that can be modified by the state machine. The context is used to store information that is relevant to the state machine, but not part of the state itself. For example, the context may contain information about the user, or the current page that the user is on.
|
||||
|
||||
The 'State' object is the current state of the state machine. It contains information about the current state, the events that led to the current state, as well as the history object which contains the previous states.
|
||||
|
||||
### Events Tab
|
||||
|
||||
The 'Events' tab shows the events that have occurred since the state machine was initialized. You can click on the events to see the payload of the events.
|
||||
|
||||
Clicking on 'Show built-in events' will include built-in events in the list. These are non-user events that are triggered by the state machine itself, such as invoked promises.
|
||||
|
||||
These events are useful for debugging, as they can help you understand what events have occurred and what the payload of the events are, and provides a similar functionality to Redux Dev Tools.
|
||||
|
||||
### Actors Tab
|
||||
|
||||
If there is more than one state machine active (e.g, there are multiple state machines or there are child state machines), you can select which one to inspect by clicking on the 'Actors' tab on the top right of the visualizer.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Significance: patch
|
||||
Type: dev
|
||||
|
||||
Added documentation for the Core Profiler
|
||||
Loading…
Reference in New Issue