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 engagements
• 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.

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.

   The draft opens automatically after you create the extension.

6. 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 changes to users, you can create and release an app version. An app version is a snapshot of your app configuration and all extensions.

1. From the Partner Dashboard, go to Apps.

2. Select your app from the list.

3. Click Versions.

4. From the Versions page, click Create version.

5. Optional: enter a name and message for the version.

6. Click Release. If you don't want to release right away, then you can click Create version.

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

After you release your new app version, you can view the version details in the Partner Dashboard, or by running the versions list command in Shopify CLI.

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