Analytics

YesPlz Analytics collects user interaction data to power your business insights and improve product discovery.

Why integrate YesPlz Analytics?

Data Insights Dashboard — Visualize user behavior, conversion funnels, and product performance
Smarter Recommendations — User interactions train our AI to deliver more relevant "You May Also Like", "Complete The Look", and personalized recommendations
Better Search Results — Click and purchase signals continuously improve search ranking and relevance

The more interaction data collected, the more accurate your recommendations and search results become.

Installation

<script src="https://code-b.yesplz.ai/<RETAILER>/sdk/latest/yesplz-sdk.min.js"></script>
<script>
  const analytics = window.yesplz.analytics;
  const { EventType, ItemListId } = analytics;

  analytics.init({
    debug: true,                    // Enable console logs
    trackDataAttributes: true,      // Enable automatic tracking via data-yp-track-*
    // userId: 'user_12345',        // Set if user is logged in
  });
</script>

Production: https://code-b.yesplz.ai/<RETAILER>/sdk/latest/yesplz-sdk.min.js
Staging: https://code-b.yesplz.ai/<RETAILER>/sdk/staging/yesplz-sdk.min.js

Tracking Methods

YesPlz Analytics provides two tracking methods:

Method	Description	Recommended For
Data Attributes	Automatic tracking via HTML attributes	Product lists, search results, recommendation carousels
API Calls	Direct JavaScript calls	Cart, checkout, purchase, page views

1. Data Attributes (Automatic Tracking)

Recommended for product lists, search results, and recommendation carousels. Simply add HTML attributes and impressions (ViewItemList) and clicks (SelectItem) are tracked automatically.

Setup

analytics.init({
  trackDataAttributes: true, // Enable automatic tracking
});

Examples

Basic Usage

<!-- Change list-id based on context: Search, YMAL, CTL, PLP, etc. -->
<div class="product-list" data-yp-track-list-id="YMAL">
  <div data-yp-track-item-id="SKU001" data-yp-track-index="0">Product 1</div>
  <div data-yp-track-item-id="SKU002" data-yp-track-index="1">Product 2</div>
  <div data-yp-track-item-id="SKU003" data-yp-track-index="2">Product 3</div>
</div>

With Rich Data (Recommended)

Adding more attributes enables deeper analytics insights. Attribute names follow the GA4 item parameters standard:

Attribute	Example
`data-yp-track-item-name`	`"White T-Shirt"`
`data-yp-track-price`	`"29.99"`
`data-yp-track-item-category`	`"Tops"`
`data-yp-track-item-brand`	`"Nike"`
`data-yp-track-discount`	`"5.00"`
`data-yp-track-item-variant`	`"VAR_12345"` or `"White / M"`

<!-- ⚠️ Minimal - limited insights -->
<div data-yp-track-item-id="SKU001">...</div>

<!-- ✅ Recommended - enables full analytics -->
<div
  data-yp-track-item-id="SKU001"
  data-yp-track-index="0"
  data-yp-track-item-name="White T-Shirt"
  data-yp-track-price="29.99"
  data-yp-track-item-brand="Nike"
  data-yp-track-item-category="Tops"
  data-yp-track-item-variant="VAR001"
>
  ...
</div>

This generates:

{
  "item_id": "SKU001",
  "index": "0",
  "item_name": "White T-Shirt",
  "price": "29.99",
  "item_brand": "Nike",
  "item_category": "Tops",
  "item_variant": "VAR001"
}

React Example

function ProductList({ products, listId }) {
  return (
    <div data-yp-track-list-id={listId}>
      {products.map((product, index) => (
        <div
          key={product.id}
          data-yp-track-item-id={product.id}
          data-yp-track-index={index}
          data-yp-track-item-name={product.name}
          data-yp-track-price={product.price}
          data-yp-track-item-category={product.category}
          data-yp-track-item-brand={product.brand}
        >
          <img src={product.image} alt={product.name} />
          <span>{product.name}</span>
        </div>
      ))}
    </div>
  );
}

Attributes

Attribute	Required	Description
`data-yp-track-list-id`	✓	List identifier (e.g., `Search`, `YMAL`, `PLP`)
`data-yp-track-item-id`	✓	Product ID
`data-yp-track-index`		Position in list (starts from 0)
`data-yp-track-*`		Additional attributes (automatically included in events)

Supported List IDs

Use any of these values for data-yp-track-list-id (case-sensitive):

Name	ID	Shorthand
Search Results	`search-results`	`Search`
Product List	`product-list`	`PLP`
You May Also Like	`you-may-also-like`	`YMAL`
Complete The Look	`complete-the-look`	`CTL`
Collaborative Filtering	`collaborative-filtering`	`CF`, `frequently-bought-together`
More From Brand	`more-from-brand`	`Brand`
Style With	`style-with`	`STW`
Shopping Cart	`shopping-cart`	`CART`
Item For You	`item-for-you`
Brand For You	`brand-for-you`

Using ItemListId Constants (API Calls)

When tracking manually, use ItemListId constants or custom IDs:

const analytics = window.yesplz.analytics;
const { EventType, ItemListId } = analytics;

// For YesPlz Recommendation API results, use predefined constants
analytics.track(EventType.ViewItemList, {
  item_list_id: ItemListId.YOU_MAY_ALSO_LIKE,
  items: [
    { item_id: 'SKU001', index: 0 },
    { item_id: 'SKU002', index: 1 },
  ]
});

// For custom lists
analytics.track(EventType.ViewItemList, {
  item_list_id: 'homepage_banner',
  items: [{ item_id: 'SKU001', index: 0 }]
});

Auto-tracked Events

ViewItemList: List impression
SelectItem: Item click

Required Wrapper

Items must be inside a data-yp-track-list-id container for both impression and click tracking to work.

<!-- ✅ Correct -->
<div data-yp-track-list-id="YMAL">
  <div data-yp-track-item-id="SKU001">...</div>
</div>

<!-- ❌ Won't track -->
<div data-yp-track-item-id="SKU001">...</div>

Excluding Elements from Tracking

Buttons inside a product card that don't navigate to the product page (e.g., Add to Cart, Wishlist) should use data-yp-track-ignore to prevent SelectItem tracking:

<div data-yp-track-list-id="YMAL">
  <div data-yp-track-item-id="SKU001" data-yp-track-index="0">
    <a href="/product/SKU001">
      <img src="product.jpg" />           <!-- ✅ SelectItem tracked -->
      <span>Product Name</span>           <!-- ✅ SelectItem tracked -->
    </a>
    <button data-yp-track-ignore>Add to Cart</button>   <!-- ❌ Ignored -->
    <button data-yp-track-ignore>♡</button>             <!-- ❌ Ignored -->
  </div>
</div>

For these buttons, track via API:

// Add to Cart
analytics.track(EventType.AddToCart, {
  currency: 'USD',
  value: 29.99,
  items: [{ item_id: 'SKU001', item_name: 'Product Name', price: 29.99, quantity: 1 }]
});

// Wishlist
analytics.track(EventType.AddToWishlist, {
  items: [{ item_id: 'SKU001', item_name: 'Product Name', price: 29.99 }]
});

2. API Calls (Direct Tracking)

Recommended for cart, checkout, and page views where precise timing is needed.

View Item

Track when a user views a product detail page:

// On product detail page load
analytics.track(EventType.ViewItem, {
  currency: 'USD',
  items: [
    {
      item_id: 'SKU001',
      item_name: 'White Cotton T-Shirt',
      price: 29.00,
      item_brand: 'Nike',
      item_category: 'Tops',
    }
  ]
});

Add to Cart

Track when a user adds an item to their cart.

Required parameters: currency, value, items

function handleAddToCart(product, variant, quantity) {
  addToCart(product, quantity);

  analytics.track(EventType.AddToCart, {
    currency: 'USD',
    value: product.price * quantity,
    items: [
      {
        item_id: product.id,
        item_name: product.name,
        price: product.price,
        quantity: quantity,
        item_variant: variant.id || variant.name,  // ID preferred, or "White / M"
      }
    ]
  });
}

Remove from Cart

analytics.track(EventType.RemoveFromCart, {
  currency: 'USD',
  value: 29.00,
  items: [
    {
      item_id: 'SKU001',
      item_name: 'White Cotton T-Shirt',
      price: 29.00,
      quantity: 1,
    }
  ]
});

Begin Checkout

Track when a user starts the checkout process.

Required parameters: currency, value, items

analytics.track(EventType.BeginCheckout, {
  currency: 'USD',
  value: 78.00,
  coupon: 'SUMMER10',
  items: [
    {
      item_id: 'SKU001',
      item_name: 'White Cotton T-Shirt',
      price: 29.00,
      quantity: 2,
      item_variant: 'VAR001',
    },
    {
      item_id: 'SKU002',
      item_name: 'Black Slim Jeans',
      price: 49.00,
      quantity: 1,
      item_variant: 'VAR002',
    }
  ]
});

Purchase

Track when a user completes a purchase.

Required parameters:

Parameter	Description
`transaction_id`	Unique order ID
`currency`	Currency code (e.g., `USD`, `KRW`)
`value`	Total order value
`items`	Array of purchased items

Optional parameters: shipping, tax, coupon

analytics.track(EventType.Purchase, {
  transaction_id: 'ORD-2024-001234',  // Required
  currency: 'USD',                     // Required
  value: 87.00,                        // Required
  shipping: 5.00,
  tax: 8.00,
  coupon: 'SUMMER10',
  items: [                             // Required
    {
      item_id: 'SKU001',
      item_name: 'White Cotton T-Shirt',
      price: 29.00,
      quantity: 2,
      item_variant: 'VAR001',
    },
    {
      item_id: 'SKU002',
      item_name: 'Black Slim Jeans',
      price: 49.00,
      quantity: 1,
      item_variant: 'VAR002',
    }
  ]
});

Wishlist

// Add to wishlist
analytics.track(EventType.AddToWishlist, {
  currency: 'USD',
  value: 29.00,
  items: [{ item_id: 'SKU001', item_name: 'White Cotton T-Shirt', price: 29.00 }]
});

// Remove from wishlist
analytics.track(EventType.RemoveFromWishlist, {
  currency: 'USD',
  value: 29.00,
  items: [{ item_id: 'SKU001' }]
});

Custom Events

Custom events are sent to GA only (not included in YesPlz dashboard).

analytics.track('filter_applied', { filter_type: 'color', filter_value: 'blue' });

Event Types

Note: Event names and parameters follow the GA4 E-commerce standard. If you're familiar with GA4 e-commerce tracking, the same naming conventions apply.

List Events

Constant	Description
`EventType.ViewItemList`	Product list impression
`EventType.SelectItem`	Product click (from list)

Product Events

Constant	Description
`EventType.ViewItem`	Product detail page view
`EventType.AddToCart`	Add to cart
`EventType.RemoveFromCart`	Remove from cart
`EventType.BeginCheckout`	Begin checkout
`EventType.Purchase`	Purchase complete
`EventType.AddToWishlist`	Add to wishlist
`EventType.RemoveFromWishlist`	Remove from wishlist

Complete User Journey Example

A typical e-commerce tracking flow:

Init → ViewItemList → SelectItem → ViewItem → AddToCart → BeginCheckout → Purchase

const analytics = window.yesplz.analytics;
const { EventType, ItemListId } = analytics;

// 1️⃣ Initialize (on page load)
analytics.init({
  debug: true,
  trackDataAttributes: true,
  userId: 'user_12345',           // Optional: if user is logged in
});

// 2️⃣ ViewItemList
// Option A: Automatic via data attributes
// <div data-yp-track-list-id="YMAL">
//   <div data-yp-track-item-id="SKU001" data-yp-track-index="0">...</div>
// </div>

// Option B: Manual API call
analytics.track(EventType.ViewItemList, {
  item_list_id: ItemListId.YOU_MAY_ALSO_LIKE,
  items: [
    { item_id: 'SKU001', item_name: 'White Cotton T-Shirt', price: 29.00, index: 0 },
    { item_id: 'SKU002', item_name: 'Black Slim Jeans', price: 49.00, index: 1 },
  ]
});

// 3️⃣ SelectItem (when user clicks item in list)
// Option A: Automatic via data attributes
// Option B: Manual API call
analytics.track(EventType.SelectItem, {
  item_list_id: ItemListId.YOU_MAY_ALSO_LIKE,
  items: [{
    item_id: 'SKU001',
    item_name: 'White Cotton T-Shirt',
    price: 29.00,
    index: 0,
  }]
});

// 4️⃣ ViewItem (on product detail page)
analytics.track(EventType.ViewItem, {
  currency: 'USD',
  value: 29.00,
  items: [{
    item_id: 'SKU001',
    item_name: 'White Cotton T-Shirt',
    price: 29.00,
    item_brand: 'Nike',
  }]
});

// 5️⃣ AddToCart (when user clicks "Add to Cart")
analytics.track(EventType.AddToCart, {
  currency: 'USD',
  value: 29.00,
  items: [{
    item_id: 'SKU001',
    item_name: 'White Cotton T-Shirt',
    price: 29.00,
    quantity: 1,
    item_variant: 'White / M',
  }]
});

// 6️⃣ BeginCheckout (when user starts checkout)
analytics.track(EventType.BeginCheckout, {
  currency: 'USD',
  value: 29.00,
  items: [{
    item_id: 'SKU001',
    item_name: 'White Cotton T-Shirt',
    price: 29.00,
    quantity: 1,
  }]
});

// 7️⃣ Purchase (after successful payment)
analytics.track(EventType.Purchase, {
  transaction_id: 'ORD-2024-001234',
  currency: 'USD',
  value: 29.00,
  shipping: 3.00,
  tax: 2.90,
  items: [{
    item_id: 'SKU001',
    item_name: 'White Cotton T-Shirt',
    price: 29.00,
    quantity: 1,
    item_variant: 'White / M',
  }]
});

Event Parameters

GA4 E-commerce Standard

Our event tracking follows the Google Analytics 4 E-commerce events standard for consistent data collection and reporting.

👉 GA4 E-commerce Events Reference

Common Parameters

Parameter	Type	Required	Example	Description
`currency`	string	Yes*	`"USD"`	ISO 4217 currency code. *Required if `value` is set
`value`	number	Yes*	`29.99`	Total monetary value. *Sum of (price × quantity) for all items
`transaction_id`	string	Yes**	`"ORD_12345"`	Unique order ID. **Required for `Purchase` only
`items`	array	Yes	See below	Array of item objects

Item Object Schema

Parameter	Type	Required	Example	Description
`item_id`	string	Yes*	`"SKU_12345"`	Product ID. *One of `item_id` or `item_name` required
`item_name`	string	Yes*	`"White T-Shirt"`	Product name
`price`	number	Recommended	`29.99`	Unit price (discounted if applicable)
`quantity`	number	Recommended	`2`	Quantity (default: 1)
`item_variant`	string	Recommended	`"VAR_001"` or `"White / M"`	Variant ID or description. ID preferred if available
`item_brand`	string	Recommended	`"Nike"`	Brand name
`item_category`	string	Recommended	`"Apparel"`	Primary category
`item_category2`	string	No	`"Tops"`	Secondary category
`item_category3`	string	No	`"T-Shirts"`	Tertiary category
`index`	number	No	`0`	Position in list (0-based)
`discount`	number	No	`5.00`	Discount amount per unit
`coupon`	string	No	`"SAVE20"`	Applied coupon code
`item_list_id`	string	Auto	`"you-may-also-like"`	Auto-filled from `data-yp-track-list-id`
`item_list_name`	string	No	`"You May Also Like"`	List name

User Identification

Track logged-in users for personalized analytics and recommendations. If you're using personalized recommendations (e.g., "Item For You"), user identification is required.

// Set during initialization
analytics.init({ userId: 'user_12345' });

// Or set after login
analytics.setUser('user_12345');

// On logout
analytics.setUser(null);

Debugging

With debug: true, events are logged to the console:

[YesPlz Analytics] Initialized
[YesPlz Analytics] Track: view_item_list { items: 5 }
[YesPlz Analytics] Track: select_item { items: 1 }
[YesPlz Analytics] Sync: 3 events sent

You're ready to start using Analytics! For questions, contact hello@yesplz.ai.

Installation​

Tracking Methods​

1. Data Attributes (Automatic Tracking)​

Setup​

Examples​

Attributes​

Supported List IDs​

Auto-tracked Events​

Excluding Elements from Tracking​

2. API Calls (Direct Tracking)​

View Item​

Add to Cart​

Remove from Cart​

Begin Checkout​

Purchase​

Wishlist​

Custom Events​

Event Types​

Complete User Journey Example​

Event Parameters​

Common Parameters​

Item Object Schema​

User Identification​

Debugging​