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

Requirements

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.

  • onboardingInfoCompleted

  • termsAccepted

  • onboardingCompleted

  • meetsRequirements

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.

  1. In server/graphql/schema.js update the AdminShop type 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.

  2. Add a Mutation type with fields that update the new shop fields you added.

  3. Update server/graphql/resolvers.js to include resolvers for the shop model fields on the adminShop.

    Since the database model attribute names match the field names, returning the database shop automatically resolves the fields to the values from the object.

  4. 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 /graphql path.

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.

In server/graphql/resolvers.js update the shop and shops fields to fetch only those shops where onboardingCompleted and meetsRequirements are set to true.

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.

  1. In pages/_app.js create a RoutePropagator component, 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.

  2. Add a Link component that will wrap a next/link component around non-external link elements.

    Passing it into the ExtendedAppProvider provides Polaris with a custom component to use for all links.

Next steps