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 learn
Anchor 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 store to collect customer events
Requirements
Anchor 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.
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_pixels
andread_customer_events
access scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
Step 1: Create a web pixel app extension
Anchor link to section titled "Step 1: 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
write_pixels
andread_customer_events
permissions, add the following code toshopify.app.toml
: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 2: Define your web pixel settings definition
Anchor link to section titled "Step 2: 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 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:
Property | Required | Description |
---|---|---|
type |
Yes | The type of extension. For web pixel app extensions, this value is always web_pixel_extension |
name |
Yes | The name of the web pixel app extension |
runtime_context |
Yes | The context that the web pixel app extension is running in. This value must be set to strict . |
settings |
Yes | Denotes the data type of the settings definition. A type property with the value object must be provided for this section. |
settings.fields |
Yes | Denotes the acceptable metafields for your settings definition. Requires a name and type field. An optional description and validations field can also be provided. |
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.
Step 3: Subscribe to events in web pixel
Anchor link to section titled "Step 3: Subscribe to events in web pixel"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.
Step 4: Connect the extension to a development store
Anchor link to section titled "Step 4: Connect the extension to a development store"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.
Navigate to your app directory.
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.
Step 5: Create a web pixel setting for the store
Anchor link to section titled "Step 5: Create a web pixel setting for the 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.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.
Step 6: Deploy your extension
Anchor link to section titled "Step 6: Deploy your extension"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.
- Navigate to your app directory.
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.