Getting started with marketing activities app extensions

After you've finished this tutorial, you'll have accomplished the following:

• Added a marketing activities app extension to your app
• Hosted the required REST endpoints on your app's domain
• Provided a preview to enable merchants to see changes in real-time before publishing
• Created enagements
• Created and publish a version of your marketing activities app extension

• You've created a Partner account and a development store.

  You can use the development store for testing while you are working on your marketing activity extension.

• You understand how apps fit into Shopify and the different ways of distributing your app.

• You've created an app that uses Shopify CLI 3.0 or higher, or you've migrated your existing app so that it's compatible with Shopify CLI 3.0 or higher.

1. From your Partner Dashboard, click Apps.
2. Click the name of the app that you want to change.
3. Click Extensions, and click +Create.
4. Select the Shopify admin tab, and click the Marketing activities card.
5. Provide a name for your extension, and click Save.

6. Click Open Draft, and provide the following extension information:

   • For Base API path, enter the URL where your app's endpoints are hosted.

   • Specify the Marketing tactic.

     The marketing tactic determines settings for Marketing platform and Ad format. The selection of the marketing tactic also determines which default fields are included in the marketing activity.

   • Specify if the activity is a marketing automation.

     Automations are ongoing activities that are triggered by an event or customer action. Marketing activities that are marked as automations appear under the Automations page of the Marketing section in the Shopify admin. Otherwise, marketing activities appear under the Campaigns page.

     For more information, refer to Creating marketing campaigns.

7. Add the configuration fields.

8. Click Save draft.

Configuration fields define the marketing activity form that is displayed to merchants in Shopify admin. You can use the steps below to create configuration fields.

1. Click Create field.
2. On the Add components dialog, select the component that you want to add to your form, and click Add. Each component has different requirements. To learn more about how to configure a component, see the Marketing activities components reference.
3. Enter the required information.

You can add a divider to group your app's configuration fields into sections. It's best practice to group fields into sections for longer app forms.

1. In the Configuration fields section hover over any blank space in-between the configuration field cards.
2. Click on Add title for divider.
3. Provide a title for the section.
4. Click anywhere outside the title to save the new section. After the section is saved, a blue box appears around the section so you can easily see which fields are grouped. The section title and grouped fields are visible to the merchant.

You need to build REST endpoints on your app's domain. Shopify uses REST calls and structured JSON to communicate with your app. These endpoints need to respond to various actions the merchant can perform with the activity.

If you've used Shopify webhooks before, then the implementation requirements are nearly identical from both a security and response time standpoint. Make sure to verify that the request came from Shopify.

An important REST endpoint to set up is the preload endpoint, which allows you to set form defaults as well as provide the corresponding data from previously created activities. Shopify doesn't store the form data, so you are responsible for associating the activity ID with your data models.

You can use your app's preload endpoint to render what your app's marketing extension will look like on desktop, mobile, or another device:

You need to provide a preview endpoint for your marketing activities. The preview endpoint is recommended for the best experience of your app, as it allows merchants to see changes in real-time before publishing.

The preview can either be an image or a URL, and you can define it with the other REST endpoints.

After you've created marketing events, you can use the marketingEngagementCreate mutation to create a periodic job that sends incremental engagement data about active marketing activities. Engagement data can be sent using any of the previously provided unique identifiers, including the marketingActivityId or remoteId fields, or UTM parameters.

Engagements are currently tracked on a daily resolution. You need to supply the date the engagements occurred, and the daily totals for each value. These can be sent incrementally multiple times per day. The most recent value overwrites previously sent values.

For each marketing activity, the value of the cumulative field (true or false) should remain the same across all of its engagement data. The cumulative boolean indicates whether each engagement sent is a lifetime value of all metrics or just a daily total for that day.

• If the value is true, then each engagement is a lifetime value for all metrics up to that occurredOn date.
• If the value is false, then each engagement is the total metrics for only that occurredOn date.

For a full list of metrics that you can send in an engagement, refer to the MarketingEngagementInput input object in the GraphQL Admin API.

The following example shows how to use the marketingEngagementCreate mutation to send engagement data for a marketing activity:

When you're ready to release your extension to merchants, you can create a version.

1. Click Create version.
2. In the modal, select either Minor or Major version depending on the nature of your code changes.
   • Minor versions introduce changes that are backwards compatible.
   • Major version changes aren't backwards compatible and might affect users who are currently using your extension.

When you're ready to release your extension to merchants, you can publish it. Publishing an extension version replaces the current Live version served to shops that have your app installed.

1. Open the extension versioning page in your Partner Dashboard.
2. Click Publish beside the version that you want to publish.

The new version is now served to all shops with your app installed.

• Learn how to manage marketing activities.
• Consult the reference documentation for marketing activities app extensions.