A personal community project under @kyletaylored, MIT licensed.Not provided or supported by Datadog.

Shopify

Checkout events, order value and customer identity from Shopify Web Pixels. Composes with the official @datadog/browser-rum-shopify plugin rather than replacing it.

Maintainercommercev0.1.0schema 1.0.0

Install

import { datadogRum } from '@datadog/browser-rum'
import { shopifyPlugin } from '@kyletaylored/datadog-rum-plugin-shopify'

datadogRum.init({
  applicationId, clientToken, site, service, env, version,
  plugins: [shopifyPlugin()],
})

<script src="https://www.datadoghq-browser-agent.com/<site>/v6/datadog-rum.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@kyletaylored/[email protected]/dist/plugin.js"
        integrity="sha384-REPLACE_WITH_THE_HASH_FROM_THE_RELEASE" crossorigin="anonymous"></script>
<script>
  DD_RUM.init({ /* ... */, plugins: [DD_RUM_PLUGINS['shopify']()] })
</script>

The CDN URL is pinned to an exact version and needs the integrity hash from that release; there is no auto-updating latest URL. Platform path: Shopify custom pixel.

Events this plugin sends

Generated from this adapter's fixture run, not written by hand, so it describes what the code actually does. Attribute types are the schema's.

`commerce.add_payment_info`

Attribute	Type
`currency`	string
`payment_type`	string
`value`	number

Example from the fixtures

{
  "value": 100.6,
  "currency": "USD",
  "payment_type": "paypal"
}

`commerce.add_shipping_info`

Attribute	Type
`currency`	string
`shipping_tier`	string
`value`	number

Example from the fixtures

{
  "value": 95.65,
  "currency": "USD",
  "shipping_tier": "Ground"
}

`commerce.add_to_cart`

Attribute	Type
`currency`	string
`item_count`	integer
`items`	array
`unique_items`	integer
`value`	number

Example from the fixtures

{
  "value": 56,
  "currency": "USD",
  "items": [
    {
      "item_id": "TEE-RED-M",
      "item_name": "Classic Tee",
      "price": 28,
      "quantity": 2,
      "item_variant": "Red / M",
      "item_category": "Shirts"
    }
  ],
  "item_count": 2,
  "unique_items": 1
}

`commerce.begin_checkout`

Attribute	Type
`coupon`	string
`currency`	string
`item_count`	integer
`items`	array
`unique_items`	integer
`value`	number

Example from the fixtures

{
  "value": 95.65,
  "currency": "USD",
  "coupon": "WELCOME10",
  "items": [
    {
      "item_id": "TEE-RED-M",
      "item_name": "Classic Tee",
      "price": 28,
      "quantity": 2,
      "item_variant": "Red / M",
      "item_category": "Shirts"
    },
    {
      "item_id": "CAP-BLK",
      "item_name": "Logo Cap",
      "price": 28.5,
      "quantity": 1,
      "item_category": "Hats"
    }
  ],
  "item_count": 3,
  "unique_items": 2
}

`commerce.purchase`

Attribute	Type
`coupon`	string
`currency`	string
`item_count`	integer
`items`	array
`payment_type`	string
`shipping`	number
`shipping_tier`	string
`tax`	number
`transaction_id`	string
`unique_items`	integer
`value`	number

Example from the fixtures

{
  "transaction_id": "5512345678901",
  "value": 100.6,
  "currency": "USD",
  "tax": 6.2,
  "shipping": 4.95,
  "coupon": "WELCOME10",
  "payment_type": "paypal",
  "shipping_tier": "Ground",
  "items": [
    {
      "item_id": "TEE-RED-M",
      "item_name": "Classic Tee",
      "price": 28,
      "quantity": 2,
      "item_variant": "Red / M",
      "item_category": "Shirts"
    },
    {
      "item_id": "CAP-BLK",
      "item_name": "Logo Cap",
      "price": 28.5,
      "quantity": 1,
      "item_category": "Hats"
    }
  ],
  "item_count": 3,
  "unique_items": 2
}

`commerce.remove_from_cart`

Attribute	Type
`currency`	string
`item_count`	integer
`items`	array
`unique_items`	integer
`value`	number

Example from the fixtures

{
  "value": 28.5,
  "currency": "USD",
  "items": [
    {
      "item_id": "CAP-BLK",
      "item_name": "Logo Cap",
      "price": 28.5,
      "quantity": 1,
      "item_category": "Hats"
    }
  ],
  "item_count": 1,
  "unique_items": 1
}

`commerce.search`

Attribute	Type
`search_term_length`	integer

Example from the fixtures

{
  "search_term_length": 14
}

`commerce.view_cart`

Attribute	Type
`cart_id`	string
`currency`	string
`item_count`	integer
`items`	array
`value`	number

Example from the fixtures

{
  "value": 84.5,
  "currency": "USD",
  "cart_id": "gid://shopify/Cart/c1-8f2a",
  "item_count": 3,
  "items": [
    {
      "item_id": "TEE-RED-M",
      "item_name": "Classic Tee",
      "price": 28,
      "quantity": 2,
      "item_variant": "Red / M",
      "item_category": "Shirts"
    },
    {
      "item_id": "CAP-BLK",
      "item_name": "Logo Cap",
      "price": 28.5,
      "quantity": 1,
      "item_category": "Hats"
    }
  ]
}

`commerce.view_item`

Attribute	Type
`currency`	string
`items`	array
`value`	number

Example from the fixtures

{
  "value": 28,
  "currency": "USD",
  "items": [
    {
      "item_id": "TEE-RED-M",
      "item_name": "Classic Tee",
      "price": 28,
      "quantity": 1,
      "item_variant": "Red / M",
      "item_category": "Shirts"
    }
  ]
}

`commerce.view_item_list`

Attribute	Type
`item_list_name`	string
`items`	array

Example from the fixtures

{
  "item_list_name": "Summer sale",
  "items": [
    {
      "item_id": "TEE-RED-M",
      "item_name": "Classic Tee",
      "price": 28,
      "quantity": 1,
      "item_variant": "Red / M",
      "item_category": "Shirts"
    },
    {
      "item_id": "CAP-BLK",
      "item_name": "Logo Cap",
      "price": 28.5,
      "quantity": 1,
      "item_category": "Hats"
    },
    {
      "item_id": "SOCK-WHT-L",
      "item_name": "Crew Socks",
      "price": 12,
      "quantity": 1,
      "item_variant": "White / L",
      "item_category": "Socks"
    }
  ]
}

Session context it sets

Property	Example value
`commerce.platform`	`"shopify"`
`commerce.plugin_version`	`"0.1.0"`
`commerce.schema_version`	`"1.0.0"`

What it touches

Platform globals read	`analytics (Web Pixel sandbox)`, `window.Shopify`
Platform events subscribed	`collection_viewed`, `product_viewed`, `product_added_to_cart`, `product_removed_from_cart`, `cart_viewed`, `checkout_started`, `checkout_shipping_info_submitted`, `payment_info_submitted`, `checkout_completed`, `search_submitted`
Storage keys written	`dd_rum_commerce_seen`
RUM APIs called	`addAction`, `setGlobalContextProperty`, `setUser`, `setTrackingConsent`
Consent source	`Shopify Customer Privacy API (window.Shopify.customerPrivacy)`

Declared by the plugin and checked against its fixture run: the conformance suite fails if the adapter calls a RUM API this list does not mention. Also printed to the console in debug mode.

Options

Option	Default	Effect
`analytics`	`none`	The sandbox analytics global, the same object the official plugin takes as shopifyAnalytics.
`events`	`none`	Allow-list of commerce actions. Every action in the schema by default.
`identifyUsers`	`true`	Call setUser with the Shopify customer ID from checkout_completed.
`includeEmail`	`false`	Add the checkout email to setUser.
`includeName`	`false`	Add the customer name to setUser.
`includeItems`	`false`	Attach items[], capped at 20 entries.
`actionPrefix`	`"commerce."`	Rename the action prefix if the store has its own convention.
`consent`	`"auto"`	auto reads the Shopify Customer Privacy API, ignore defers to the host page.
`beforeTrack`	`none`	Edit or drop an event before it is sent.
`debug`	`false`	Log every mapped event to the console.

Compatibility and maintainer

RUM SDK	`@datadog/browser-rum@>=7.0.0 <8.0.0`
Schema	`1.0.0` · reference
Platforms	Shopify Custom pixel under Settings > Customer events. Requires the official shopifyPlugin alongside it for the sandbox fixes, views and clicks.
Maintainer	Kyle Taylor (@kyletaylored)
Source	packages/plugin-shopify

Verify the install

Pass debug: true and reload. Every mapped event prints to the console, along with the plugin's declared footprint.
```
plugins: [shopifyPlugin({ debug: true })]
```
Query the RUM Explorer for the first action. It should appear within a minute of the first matching interaction on the site.
```
@type:action @action.name:commerce.add_payment_info
```
Reconcile against the platform's own report before trusting the numbers. These are browser-measured and will undercount; the accuracy bar is within 5% of the platform admin over 7 days.