Set up onboarding foundations
You have a page for your channel app in Shopify admin. You're ready to start building up this page with the onboarding experience.
In this tutorial you'll set up the foundations you need to build a fully-featured onboarding flow for a channel app.
What you'll learn
After finishing this tutorial, you'll know how to do the following:
Store the merchant's onboarding state in your shop data model
Prepare your internal GraphQL API to support the channel app
Set up your channel app to handle multiple pages
- You've completed the Cart and checkout tutorials
Step 1: Update shop model
To support the new features being built into the channel app, you need to update your shop data model to store additional information about the merchant’s onboarding journey. The app should store fields to track whether the merchant has read the marketplace info, accepted the marketplace terms, completed the onboarding process, and whether they meet the marketplace requirements.
In your app, add the following Boolean fields with a default of
false to the Shop data model.
Step 2: Update internal GraphQL API
To build the onboarding flow and settings page, you need to make new shop fields available through the internal API. You'll provide mutations that allow your channel app frontend to update the shop data model. Since you're surfacing the marketplace requirements as part of the onboarding flow, you also need to expose whether a shop meets each of the requirements.
AdminShoptype to return the fields that you added to the model.
Shopify recommends that the field names match your shop model’s attribute names, so that Apollo Server can automatically resolves the fields to the values from the object.
Mutationtype with fields that update the new shop fields you added.
server/graphql/resolvers.jsto include resolvers for the shop model fields on the
Since the database model attribute names match the field names, returning the database shop automatically resolves the fields to the values from the object.
Include resolvers for the mutation fields to update the shop in the database and return the updated shop.
The new fields should now be accessible in your GraphQL playground, available in your app at the
Step 3: Filter shops on marketplace
Onboarding serves as an important gating mechanism for your marketplace, and merchants should not be shown on the marketplace until they have completed the onboarding flow. Merchants may also make changes to their shop after onboarding which result in them no longer meeting your marketplace terms. Therefore, we should filter the shops to be displayed on our marketplace, ensuring they meet the requirements and have completed onboarding.
server/graphql/resolvers.js update the
shops fields to fetch only those shops where
meetsRequirements are set to
Step 4: Handle channel routing
In the subsequent sections, you'll be introducing multiple pages to your channel app and you'll need to support routing between them. Since your app is rendered in an iframe in the Shopify admin, you need to update the admin app provider to propagate route changes in the embedded app to the browser URL. You also need to make sure that the links that are being rendered by Polaris components use the
next/link component, to support client-side navigation.
RoutePropagatorcomponent, which will handle propagating internal route changes in the app to the browser URL using App Bridge.
The component will also push redirects initiated by App Bridge to your app’s
next/router. The component can be rendered as part of the admin app.
Linkcomponent that will wrap a
next/linkcomponent around non-external link elements.
Passing it into the
ExtendedAppProviderprovides Polaris with a custom component to use for all links.
- Learn how to communicate the eligibility requirements for shops to sell products on a marketplace.