Getting started with web pixel extensions

In this tutorial, you’ll learn how to do the following tasks:

• Create a web pixel extension.
• Configure your web pixel extension to subscribe to all events emitted by Shopify.
• Activate and test your web pixel extension.
• Deploy your web pixel extension to Shopify.

• You've created a Partner account and a development store.
• You've created an app that uses Shopify CLI 3.50 or higher. If you previously installed Shopify CLI, then make sure you're using the latest version.
• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the write_pixels and read_customer_events access scopes. Learn how to configure your access scopes using Shopify CLI.

To create a web pixel extension, you can use Shopify CLI to generate a starter extension.

1. Navigate to your app directory:

2. Run the following command to create a new web pixel extension:

3. Choose the language that you want to use:

   After the generation 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 extension.

Your web pixel needs to be configured for each store so it can properly track and associate data. The settings 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 that 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 defined, you can now set up subscriptions to events that are emitted.

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

You can add an event subscription to your app using the extensions/<your_extension_name>/src/index.js file. When you run the generate extension 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. For example, you can add the following 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.

Before you can activate a web pixel extension, you must request the following access scopes to invoke web pixel mutations in the GraphQL Admin API:

• write_pixels: Used to write the web pixel merchant settings
• read_customer_events: Used to gain access to customer events

1. In shopify.app.toml in the root of your app, add the write_pixels and read_customer_events access scopes:

2. Deploy your updated configuration to Shopify:

3. Start your app by running the dev command to connect the extension to a development store:

4. With the server running, press p to open your app's preview URL in a browser.

5. Click Update app to accept the new access scope permissions in your store.

6. In your development store, go to Settings > Customer events.

   The name of your app appears in the App pixels list with the Disconnected status. You'll connect your app and activate the web pixel extension in the next step.

To activate a web pixel extension, you must create a web pixel record on the store where you installed your app. You can do this using the webPixelCreate mutation. When this mutation is called, Shopify validates against the settings definition that you defined in shopify.extension.toml. If the settings input field doesn't match the schema that you defined, then the mutation will fail.

1. Execute the following mutation from within your app:

2. In your development store, go to Settings > Customer events.

   The name of your app should appear in the App pixels list with the Connected status.

3. Optional. If you need to update your extension code, such as change the settings of settings.fields.[name] in shopify.extension.toml, and want to see your changes reflected in development, then you need to run the webPixelUpdate mutation:

You can test that the web pixel is configured and subscribed to all events emitted on the development store by completing the following steps:

1. With the server running, open your development store.
2. Right-click anywhere on the page and select Inspect.

3. Click Console.

   The accountID is logged in the console:

   

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

1. Navigate to your app directory.

2. Run the following command.

   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.