Getting started with web pixel app extensions

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

• Created a web pixel app extension
• Configured your web pixel app extension for each store to collect customer events

• You've created a Partner account and a development store.
• 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.
• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the write_pixels and read_customer_events access scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.

There are two permissions required to work with web pixel app extensions. The first is write_pixels, which is the permission used to write the web pixel merchant settings. The second is read_customer_events, which is the permission to gain access to customer events.

1. To add the write_pixels and read_customer_events permissions, add the following code to shopify.app.toml:

2. To add a web pixel into the project, open your command line inside of your project directory. In the command line, run the command below to create a new extension for the app:

When prompted for the type of extension, select web pixel. Follow the instructions to generate your web pixel app extension.

After the generate process has completed, a new folder is created in your app directory named extensions. This folder contains all of the code for your web pixel app extension.

Your web pixel needs to be configured for each shop so it can properly track and associate data. The settings definition for your web pixel can be found at extensions/<your_extension_name>/shopify.extension.toml.

Inside of shopify.extension.toml, you can define fields that can be used by your web pixel. The following example shows the shopify.extension.toml file with a description of each property:

By default, your shopify.extension.toml file is generated with a field named accountID, as shown in the following example:

Each of the fields you define has a name, description, and type. The only type that is supported for web pixel is single_line_text_field. Validations can be provided as an optional parameter and can be used to define any constraints on a field's value. In the above example, there is a single validation to ensure that the value provided is at minimum length of 1. Further information on validation options can be found on the metafields validation page.

With the settings definition defined, you can now set up subscriptions to events that are emitted.

Event subscription allows your application to listen for events that are emitted by Shopify and other developers. You can specify a specific event to subscribe to or you can subscribe to all events using analytics.subscribe.

You can add an event subscription to your application using the extensions/<your_extension_name>/src/index.js. When you run the generate command to create the extension, a set of basic sample code is created in this file. You can add code to enable subscription to any target events. As an example, let's add code that subscribes to all events:

With this code added, the web pixel is now set to listen to all events that are emitted. Refer to the Web pixel extension API for additional APIs to support other functions or to subscribe to individual events.

You can connect your extension to a development store by running the dev command, which starts a local development server that supports hot reloading.

Connecting the extension to the store is the first step in testing your web pixel app extension, but the pixel isn't created and configured in the development store, and isn't subscribed to customer events, until you run a mutation to create the web pixel.

1. Navigate to your app directory.

2. Run one of the following commands:

   
   

   dev enables development store preview for your app until you quit.

   To learn about the processes that are executed when you run dev, refer to the Shopify CLI command reference.

The name of your app appears in the App pixels list on the Settings > Customer events page.

To activate a web pixel app extension, run the webPixelCreate mutation using GraphQL. When this mutation is called, Shopify does validation against the settings definition you defined in shopify.extension.toml. If the call doesn't match the schema you defined, then the mutation will fail.

The mutation below creates a web pixel, setting the accountID declared in shopify.extension.toml to the value 234.

Run the following GraphQL code on the development store using the Admin API:

The web pixel is now configured and subscribed to all events emitted on the development store.

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 all of your app extensions.

For more information about extension deployment and versioning, refer to Deploy app extensions.

1. Navigate to your app directory.

2. Run one of the following commands.

   Optionally, you can provide a name or message for the version using the --version and --message flags.

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.

• Consult the customer events reference to learn about the ways of tracking and sending events with web pixels.
• Explore the web pixel extension API to learn about the sandboxing modes for web pixels, and the API references that are available for the sandbox.