Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
woocommerce/plugins/woocommerce-admin/docs/features/onboarding.md

14 KiB
Raw Blame History

WooCommerce Onboarding

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.

Enabling Onboarding

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.

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.

New REST API endpoints

To power the new onboarding flow client side, new REST API endpoints have been introduced. These are purpose built endpoints that exist under the /wc-admin/onboarding/ namespace, and are not meant to be shipped in the core rest API package. The source is stored in src/API/Plugins.php, src/API/OnboardingProfile.php, and src/API/OnboardingTasks.php respectively.

  • POST /wc-admin/plugins/install - Install requested plugins.
  • GET /wc-admin/plugins/active - Returns a list of the currently active plugins.
  • POST /wc-admin/plugins/activate - Activates the requested plugins. Multiple plugins can be passed to activate at once.
  • GET /wc-admin/plugins/connect-jetpack - Generates a URL for connecting to Jetpack. A redirect_url is accepted, which is used upon a successful connection.
  • POST /wc-admin/plugins/request-wccom-connect - Generates a URL for the WooCommerce.com connection process.
  • POST /wc-admin/plugins/finish-wccom-connect - Finishes the WooCommerce.com connection process by storing the received access token.
  • POST /wc-admin/plugins/connect-square - Generates a URL for connecting to Square during the payments task.
  • GET /wc-admin/onboarding/profile - Returns the information gathered during the profile wizard. See the woocommerce_onboarding_profile_properties array for a list of fields.
  • POST /wc-admin/onboarding/profile - Sets data for the profile wizard. See the woocommerce_onboarding_profile_properties array for a list of fields.
  • POST /wc-admin/onboarding/tasks/import_sample_products - Used for importing sample products during the appearance task.
  • POST /wc-admin/onboarding/tasks/create_homepage - Used for creating a homepage using Gutenberg templates.

Onboarding filters

  • woocommerce_admin_onboarding_profile_properties filters the properties we track as part of the profile wizard (such as information from store/business details steps). When the completed property is set to true, the profile wizard is completely dismissed and hidden.
  • woocommerce_admin_onboarding_industries filters the list of allowed industries displayed in the profile wizard.
  • woocommerce_admin_onboarding_industry_image filters the images used for homepage templates in the appearance task. When creating a homepage, example images are used based on industry. These images are stored in images/onboarding.
  • woocommerce_admin_onboarding_product_types filters the product types displayed in the profile wizard.
  • woocommerce_admin_onboarding_plugins_whitelist filters the list of plugins that can installed & activated via onboarding. This acts as a whitelist so only certain plugins can be used via the /wc-admin/onboarding/profile/install and /wc-admin/onboarding/profile/activate endpoints.
  • woocommerce_admin_onboarding_themes filters the themes displayed in the profile wizard.
  • woocommerce_admin_onboarding_jetpack_connect_redirect_url filters the Jetpack connection redirect URL outlined in the Jetpack connection section below.
  • woocommerce_admin_onboarding_task_list filters the list of tasks on the task list dashboard. This allows extensions to add new tasks. See the extension docs for an example of how to do this.
  • woocommerce_rest_onboarding_profile_collection_params filters the collection parameters for requests to /wc-admin/onboarding/profile.
  • woocommerce_rest_onboarding_profile_object_query filters the query arguments for requests to /wc-admin/onboarding/profile.
  • woocommerce_rest_onboarding_prepare_onboarding_profile filters the response for requests to /wc-admin/onboarding/profile.

Options and settings

A few new WordPress options have been introduced to store information and settings during setup. It may be necessary to manual delete these options from your wp_options database to test a certain task or feature.

  • woocommerce_task_list_hidden. This option is used to conditionally show the entire task list. The task list can be hidden by the user after they have completed all tasks. Hiding the wizard stops it from showing in both full screen mode, and the collapsed inline version that shows above the dashboard analytics cards.
  • woocommerce_task_list_welcome_modal_dismissed. This option is used to show a congratulations modal during the transition between the profile wizard and task list.
  • woocommerce_task_list_prompt_shown. This option is used to conditionally show the "Is this card useful?" snackbar notice, shown once right after a user completes all the task list tasks.

We also use existing options from WooCommerce Core or extensions like WooCommerce Shipping & Tax or Stripe. The list below may not be complete, as new tasks are introduced, but you can generally find usage of these by searching for the getOptions selector.

  • woocommerce_setup_jetpack_opted_in and wc_connect_options are both used to control Jetpack's Terms of Service opt-in, which is necessary to set for a user during the connection process, so that they can use services like automated tax rates.
  • woocommerce_allow_tracking is used to control Tracks opt-in, allowing us to gather usage data from WooCommerce Admin and WooCommerce core.
  • woocommerce_demo_store and woocommerce_demo_store_notice are used on the appearance task for the store notice step.
  • woocommerce_ppec_paypal_settings and woocommerce_stripe_settings are used in the payments task and connection steps.

WooCommerce.com Connection

During the profile wizard, merchants can select paid product type extensions (like WooCommerce Memberships) or a paid theme. To make installation easier and to finish purchasing, it is necessary to make a WooCommerce.com connection. We also prompt users to connect on the task list if they chose extensions in the profile wizard, but did not finish connecting.

To make the connection from the new onboarding experience possible, we build our own connection endpoints /wc-admin/plugins/request-wccom-connect and /wc-admin/plugins/finish-wccom-connect.

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.
  • 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.

Jetpack Connection

Using Jetpack & WooCommerce Shipping & Tax allows us to offer additional features to new WooCommerce users as well as simplify parts of the setup process. For example, we can do automated tax calculations for certain countries, significantly simplifying the tax task. To make this work, the user needs to be connected to a WordPress.com account. This also means development and testing of these features needs to be done on a Jetpack connected site. Search the MGS & the Feld Guide for additional resources on testing Jetpack with local setups.

We have a special Jetpack connection flow designed specifically for WooCommerce onboarding, so that the user feels that they are connecting as part of a cohesive experience. To access this flow, we have a custom Jetpack connection endpoint /wc-admin/plugins/connect-jetpack.

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.

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.

To disconnect from Jetpack, go to Jetpack > Dashboard > Connections > Site connection > Manage site connection > Disconnect.

Calypso

calypso_env

Both the WooCommerce.com & Jetpack connection processes (outlined below) send the user to 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.

To change the value of calypso_env, set WOOCOMMERCE_CALYPSO_ENVIRONMENT to one of the following values in your wp-config.php:

  • production which will send you to https://wordpress.com
  • development which will send you to http://calypso.localhost:3000/
  • wpcalypso which will send you to http://wpcalypso.wordpress.com/
  • horizon which will send you to https://horizon.wordpress.com
  • stage which will send you to https://wordpress.com (you must be proxied)

Feature Flags

Logic for the Calypso flows are gated behind two separate Calypso feature flags. Since Calypso's login, sign-up, and Jetpack authentication code is spread throughout a few different files, searching for these feature flags is the best way to locate parts of the flow for development.

Testing

If you are running the development version of WooCommerce Admin, and have WP_DEBUG set to true, two Calypso connection buttons are displayed under the WooCommerce > Settings > Help > Setup Wizard menu, making it easier to access and test the flows.

Building the onboarding feature plugin

The onboarding feature flag is enabled in the main WooCommerce Admin plugin build. That means the published version of the plugin on WordPress.org contains the onboarding feature, but it is visually off by default. See the "enable onboarding" section above.

Sometimes, it may be necessary to generate a separate build of the plugin between public releases for internal testing or debugging. This can be done using the building custom plugin builds feature of our build system.

  • Switch to the latest main branch and pull down any changes
  • Run npm run build:release -- --slug onboarding --features '{"onboarding":true}'
  • A special woocommerce-admin-onboarding.zip release will be generated, containing the latest onboarding code
  • Make sure to follow the directions in the "enabling onboarding" section above to properly use the build