Build a custom configuration page

To give merchants 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, merchants see a preview with an image and text that's fetched from your custom configuration page preview URL. Merchants can click the button to access the custom configuration page.

A custom configuration page preview with an

Your custom configuration page is then displayed in a frame in the Shopify admin.

The custom configuration page is rendered with an App Bridge title bar.

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.

Anchor to RequirementsRequirements

You've created a Partner account.
You've created an app.

Anchor to ResourcesResources

To implement this feature, you'll use the following:

Shopify App Bridge
App Bridge components
App Bridge actions specific to the custom configuration page

Anchor to Implementing a custom configuration pageImplementing 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.

Anchor to Use Shopify App Bridge to render your app pageUse Shopify App Bridge to render your app page

Note

The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version.

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:

Anchor to Access action informationAccess action information

In the context of the custom configuration page, Shopify marketing automations makes the following action information available:

A step_reference search parameter: step_reference is 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:

{

<property-name>: <property-value>

}

Anchor to Shopify App Bridge integration for versions 4.X.X and upShopify App Bridge integration for versions 4.X.X and up

Anchor to Register to the Custom Configuration Page's intentRegister to the Custom Configuration Page's intent

To access property data with Shopify App Bridge version 4.X.X and up, you will need to use the shopify.intents API. The following example code allows you to register to the Custom Configuration Page's intent:

Example

import { useAppBridge } from '@shopify/app-bridge-react'

const Application = () => {

const shopify = useAppBridge()

const [intent, setIntent] = useState({})

useEffect(() => {

const cleanup = shopify.intents.register((intent) => {

setIntent(intent)

})

return () => cleanup()

}, []);

return <>...

}

The intent object will contain the following data:

Field	Data Type	Description
action	`string`	The action that has been registered for. In the case of the Custom Configuration Page, it will always be set to `configure`.
type	`string`	A GID with the following structure: `gid://flow/stepReference/<step-reference>`.
data	`object`	An object that contains the `properties` data.
finish	`method`	A function that allows you to navigate to the previous page.

The register method also returns a cleanup function, which you can use to unregister from the intent when your component is unmounting.

Anchor to Return to the previous pageReturn 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. You can choose to trigger a redirect to the previous page using the intent.finish() method:

Example

<Button

primary

onClick={() => {

intent.finish()

}}

Go back to Flow

</Button>

Anchor to Add buttons to the App Bridge title barAdd buttons to the App Bridge title bar

You can add more actions to the navigation bar by using the ui-title-bar element. Only primary and secondary actions are supported.

Example

function Page() {

return <ui-title-bar>

<button variant="primary" onClick={() => console.log('Primary action')}>

Primary action

</button>

<button onClick={() => console.log('Secondary action')}>

Secondary action

</button>

</ui-title-bar>

}

Anchor to Shopify App Bridge integration for versions 3.X.X and downShopify App Bridge integration for versions 3.X.X and down

Anchor to Request property dataRequest 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:

Example

import { useAppBridge } from '@shopify/app-bridge-react'

const Application = () => {

const app = useAppBridge()

const [propertiesData, setPropertiesData] = useState({})

useEffect(() => {

const unsubscribeToPropertiesEvent = app.subscribe(

'APP::APP_FRAME::PROPERTIES_EVENT',

payload => {

setPropertiesData(payload['properties'])

)

return unsubscribeToPropertiesEvent

}, [app])

useEffect(() => {

app.dispatch({

type: 'APP::APP_FRAME::REQUEST_PROPERTIES',

group: 'AppFrame',

})

}, [])

return (...)

}

Anchor to Return to the previous pageReturn 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:

Example

app.dispatch({

type: 'APP::APP_FRAME::NAVIGATE_BACK',

group: 'AppFrame',

})

Anchor to Add buttons to the App Bridge title barAdd 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 the Button.create initializer to create the buttons, then pass them to the Titlebar.create initializer 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 the TitleBar React component.

Only primary and secondary actions on the TitleBar are supported. Other App Bridge actions are ignored.

Example

import { TitleBar, Button } from '@shopify/app-bridge/actions'

// create the buttons

const primaryBtn = Button.create(app, {

label: 'Button 1',

})

const secondaryBtn = Button.create(app, {

label: 'Button 2',

})

// add click handlers

primaryBtn.subscribe(Button.Action.CLICK, () => {

console.log('button 1 clicked')

})

secondaryBtn.subscribe(Button.Action.CLICK, () => {

console.log('button 2 clicked')

})

const titleBar = TitleBar.create(app, {

title: '',

buttons: {

primary: primaryBtn,

secondary: [secondaryBtn],

})

// update buttons after initialization

const newPrimary = Button.create(app, {

label: 'New button',

})

newPrimary.subscribe(Button.Action.CLICK, () => {

console.log('new primary button clicked')

})

titleBar.set({

buttons: {

primary: newPrimary,

secondary: [secondaryBtn],

})

import { TitleBar } from '@shopify/app-bridge-react'

function Page() {

const buttons = {

primaryAction: {

content: 'Button 1',

onAction: () => {

console.log('button 1 clicked')

secondaryActions: [

{

content: 'Button 2',

onAction: () => {

console.log('button 2 clicked')

}

return <TitleBar title="" {...buttons} />

}

import { TitleBar, Button } from '@shopify/app-bridge/actions'

// create the buttons
const primaryBtn = Button.create(app, {
  label: 'Button 1',
})
const secondaryBtn = Button.create(app, {
  label: 'Button 2',
})

// add click handlers
primaryBtn.subscribe(Button.Action.CLICK, () => {
  console.log('button 1 clicked')
})
secondaryBtn.subscribe(Button.Action.CLICK, () => {
  console.log('button 2 clicked')
})

const titleBar = TitleBar.create(app, {
  title: '',
  buttons: {
    primary: primaryBtn,
    secondary: [secondaryBtn],
  },
})

// update buttons after initialization
const newPrimary = Button.create(app, {
  label: 'New button',
})
newPrimary.subscribe(Button.Action.CLICK, () => {
  console.log('new primary button clicked')
})

titleBar.set({
  buttons: {
    primary: newPrimary,
    secondary: [secondaryBtn],
  },
})

import { TitleBar } from '@shopify/app-bridge-react'

function Page() {
  const buttons = {
    primaryAction: {
      content: 'Button 1',
      onAction: () => {
        console.log('button 1 clicked')
      },
    },
    secondaryActions: [
      {
        content: 'Button 2',
        onAction: () => {
          console.log('button 2 clicked')
        },
      },
    ],
  }

  return <TitleBar title="" {...buttons} />
}

Anchor to Next stepsNext steps

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.

Note

To add a custom configuration page to your action, you also need to add a custom validation endpoint.

Was this page helpful?