Getting started with web pixel app extensions
In this tutorial, you'll learn how to create a simple web pixel using an app extension. The pixel that you'll create will be able to subscribe to all events emitted by Shopify.
What you'll learnAnchor link to section titled "What you'll learn"
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
RequirementsAnchor link to section titled "Requirements"
- 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
read_customer_eventsaccess scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
Step 1: Create an appAnchor link to section titled "Step 1: Create an app"
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.
Step 2: Create a web pixel app extensionAnchor link to section titled "Step 2: Create a web pixel app extension"
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.
To add the
read_customer_eventspermissions, add the following code to
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.
Step 3: Define your web pixel settings definitionAnchor link to section titled "Step 3: Define your web pixel settings definition"
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
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:
||Yes||The type of extension. For web pixel app extensions, this value is always
||Yes||The name of the web pixel app extension|
||Yes||The context that the web pixel app extension is running in. This value must be set to
||Yes||Denotes the data type of the settings definition. A
||Yes||Denotes the acceptable metafields for your settings definition. Requires a
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.
Step 4: Subscribe to events in web pixelAnchor link to section titled "Step 4: Subscribe to events in web pixel"
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
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.
Step 5: Deploy and publish your extensionAnchor link to section titled "Step 5: Deploy and publish your extension"
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:
From your Partner Dashboard, click Apps.
Click the name of your app.
Click on the name of your web pixel app extension.
Click on Create version and select your desired web pixel version.
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.
Step 6: Create a web pixel merchant setting for a shopAnchor link to section titled "Step 6: Create a web pixel merchant setting for a shop"
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
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.