Add onboarding to a channel app homepage

Your channel app has pages for shop requirements, onboarding, and settings. You want to make this content merchant-facing on the channel app homepage that you created, which displays in the Shopify admin.

In this tutorial, you'll use the Channels UI library to add IntroductionPage and OverviewPage components to the merchant-facing channel app homepage.

If the merchant has just installed the channel or hasn’t completed onboarding, then they'll see an introduction page that explains your marketplace’s features with a link to the onboarding page that you created. If the merchant has already completed onboarding, the homepage should instead provide merchants with an overview of their status on your marketplace and the products that they’re selling.

What you'll learn

After finishing this tutorial, you'll know how to do the following:

  • Create a Channels UI IntroductionPage component

  • Create a Channels UI OverviewPage component

  • Update the channel homepage to surface content based on the merchant's state in your channel

Requirements

You've completed the Create a settings page tutorial.

Step 1: Add the Introduction page component

  1. In pages/admin/index.js, add an Introduction component that returns an IntroductionPage component containing a FeatureCard that redirects to the onboarding page.

    In the component, you'll add some visual elements to the feature card to give merchants an understanding of what you marketplace does. For example, you can surface mockups of what your marketplace looks like on desktop and mobile to give merchants better understanding of your platform.

    It should accept a property to indicate whether the merchant has started onboarding.

  2. In the Introduction component, pass an empty set of items to the App Bridge ChannelMenu action.

    So that merchants don't see channel menu items on the introduction page, you'll pass an empty set of items to the ChannelMenu action.

Step 2: Add the Overview page component

In this step, you'll create an Overview page component that returns a Channels UI OverviewPage containing a ProductStatusSection and FeatureListCard.

ProductStatusSection should be the same as the one that you created in the getting started guide. The FeatureListCard should provide basic information about the marketplace feature, as well as a link to the merchant’s shop page on the marketplace.

  1. In pages/admin/index.js add an Overview component that accepts the shop id, domain, publicationId, availableProductCount, and appHandle as properties.

  2. Update the Overview component to handle the case where the shop no longer meets the marketplace requirements.

    An error banner should be displayed at the top of the page, and the FeatureListCard should indicate that the merchant’s shop is not available on the marketplace. The component should also accept a property to indicate whether the shop meets the requirements.

  3. Update the Overview component to create a channel menu with overview and settings items.

    On the overview page, merchants should be able to see the channel menu so they can navigate to the settings page.

Step 4: Update the homepage component

In this step, you'll update the default index component to leverage the Introduction and Overview components that you created. You can determine what component to render based on the shop's state.

  1. In pages/admin/index.js update the admin shop query to fetch additional fields about the shop’s onboarding status and whether requirements are met.

  2. Add LoadingState component that resembles the structure of the Overview page.

    Resemblance is required because, after onboarding, this is what merchants will see each time they open the channel.

  3. Update the default Index component to return the loading state while the query is loading, and pass relevant data to the Overview and Introduction components.

    After the data is returned, the Overview component will be returned for merchants who have completed onboarding, and the Introduction component will be returned otherwise.

If the merchant has not started onboarding, the channel homepage should look something like the following:

An image of the channel app introduction page

If the merchant has started onboarding but has not completed it, the channel homepage should look something like the following:

An image of the channel app introduction page, where the merchant has started onboarding

If the merchant has completed onboarding, the channel homepage should look something like the following:

An image of the channel app overview page

If the merchant has completed onboarding and subsequently failed the marketplace requirements, the channel homepage should look something like the following:

An image of the channel app overview page in an error state

Next steps

  • Learn about creating post-checkout functionality for your marketplace, including storing order details in your database and billing merchants a fee for sales on the marketplace.