Build a custom configuration page
To give users a more seamless action configuration experience, and to allow them to manage resources that are external to Shopify marketing automations, you can embed a page from your app in the Shopify marketing automations editor.
In your Shopify marketing automations action configuration, users see a preview with an image and text that's fetched from your custom configuration page preview URL. Users can click the button to access the custom configuration page.
Your custom configuration page is then displayed in a frame in the Shopify admin.
In this tutorial, you'll learn how to render a custom configuration page in Shopify marketing automations, customize the page frame, and access data relevant to your action in the custom configuration page context.
Requirements
Anchor link to section titled "Requirements"- You've created a Partner account.
- You understand how apps fit into Shopify.
- You've created an app.
To implement this feature, you'll use the following:
- Shopify App Bridge
- App Bridge components, including TitleBar and Button
- App Bridge actions specific to the custom configuration page context, including
APP::APP_FRAME::PROPERTIES_EVENT,APP::APP_FRAME::REQUEST_PROPERTIES, andAPP::APP_FRAME::NAVIGATE_BACK
Implementing a custom configuration page
Anchor link to section titled "Implementing a custom configuration page"To build a custom configuration page, you'll use Shopify App Bridge to render a page from your app page in Shopify marketing automations.
From the context of the custom configuration page, you can then access step and property information that you can use to display the appropriate information.
You can also add additional buttons to the App Bridge title bar, or trigger a redirect to the previous page.
Use Shopify App Bridge to render your app page
Anchor link to section titled "Use Shopify App Bridge to render your app page"To render your custom configuration page, you need to integrate Shopify App Bridge on the route that you want to render. To learn about setting up Shopify App Bridge, refer to one of the following pages:
Access action information
Anchor link to section titled "Access action information"In the context of the custom configuration page, Shopify marketing automations makes the following action information available:
- A
step_referencesearch parameter:step_referenceis a unique ID for the step within a workflow, and can be used to identify the resource that the merchant is requesting. Property data: Properties contains the extension fields data that make up your action payload schema. The properties are passed as an object containing the properties as key-value pairs:
Request property data
Anchor link to section titled "Request property data"To access property data, you need to subscribe to APP::APP_FRAME::PROPERTIES_EVENT, and then request the properties by triggering the APP::APP_FRAME::REQUEST_PROPERTIES event. The following example code subscribes to the properties event and requests the action properties in React:
Add buttons to the App Bridge title bar
Anchor link to section titled "Add buttons to the App Bridge title bar"You can add more actions to the App Bridge title bar in one of two ways:
- Using
@shopify/app-bridge: Use theButton.createinitializer to create the buttons, then pass them to theTitlebar.createinitializer to set the buttons. You need to keep a reference to the Titlebar instance if you wish to do additional updates after the initialization. - Using
@shopify/app-bridge-react: Pass the primary and secondary actions to theTitleBarReact component.
Only primary and secondary actions on the TitleBar are supported. Other App Bridge actions are ignored.
Return to the previous page
Anchor link to section titled "Return to the previous page"By default, the title bar of the custom configuration page includes an Exit button that the user can use to return to the previous page. This might be the Shopify marketing automations editor. However, you can choose to trigger a redirect to the previous page using APP::APP_FRAME::NAVIGATE_BACK:
Add custom configuration page preview URL and custom validation endpoints to your app.
Add your custom configuration page preview URL, custom configuration page URL, and custom validation URL to your Shopify marketing automations action configuration.