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 shop 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, 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
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 an app
Anchor 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 extension
Anchor 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
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 3: Define your web pixel settings definition
Anchor 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 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:
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.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 pixel
Anchor 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 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 5: Deploy and publish your extension
Anchor 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 Extensions.
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 shop
Anchor 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 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.