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 shop 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, or you've migrated your existing app so that it's compatible with 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.

Run one of the following commands to create a new app.

You're prompted for an app name. For this entry, you can input any name that you would like for your application. After the name is inputted, you're prompted to select a template to use for the project. Select the node option. The result of this command is a new app project created locally on your computer.

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.ui.extension.toml.

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

By default, your shopify.ui.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 are able to 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.

1. Build and deploy your application to the Partner Dashboard.

   After the app is deployed, you need to add the web pixel app extension to it through the Partner Dashboard:

2. From your Partner Dashboard, click Apps.

3. Click the name of your app.

4. Click Extensions.

5. Click on the name of your web pixel app extension.

6. Click on Create version and select your desired web pixel version.

7. In Version history, click on Publish to publish the current web pixel version.

Once your extension is created and published, it can be added to a development store.

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.ui.extension.toml. If the call does not match the schema you defined, then the mutation will fail.

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

Run the following GraphQL code on the merchant store using the Admin API

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

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