Event System

The Glood SDK’s event system automatically transforms Shopify Analytics events into Glood event data and transmits them to the versioned headless events API with full privacy compliance.

Events are routed by the client’s configured version off the recommendations app’s main endpoint — they are no longer sent to a separate events.glood.ai host. See Event Destination below.

Architecture Overview

The event system follows this flow:

Components

Event Subscription - Automatically subscribes to Shopify Analytics events
Event Distribution - Routes events to interested apps
Data Transformation - Converts Shopify data to Glood pixel format
Consent Checking - Verifies customer privacy permissions
Pixel Queue - Manages immediate transmission with retry logic
Error Handling - Comprehensive error handling and logging

Event Types

The SDK tracks these Shopify Analytics events:

Core Events

Event Type	Description	Triggered When
`page_viewed`	Page navigation	User visits any page
`product_viewed`	Product page view	User views product details
`collection_viewed`	Collection page view	User browses product collections
`cart_viewed`	Shopping cart view	User opens shopping cart

Commerce Events

Event Type	Description	Triggered When
`product_added_to_cart`	Add to cart	User adds product to cart
`product_removed_from_cart`	Remove from cart	User removes product from cart
`custom_promotion_viewed`	Promotion view	User sees promotional content

Attribution Events (Custom)

Unlike the standard events above (which are fully automatic), attribution events are sent by calling the track helpers when a visitor interacts with a recommendation section. They use event.type: 'custom' and carry the interaction details in event.customData.track:

Event Type	Description	Sent By
`glood:section:render`	Section rendered in the DOM	`trackRender(track)`
`glood:section:view`	Section scrolled into viewport	`trackView(track)`
`glood:section:click`	Recommended product clicked	`trackClick(track)`
`glood:section:add_to_cart`	Recommended product added to cart	`trackAddToCart(track)`

Attribution events flow through the same versioned events API as standard events (see Event Destination) — on a v3 client they POST to /api/storefront/v3/headless/events with event.type: 'custom'. See the Recommendations API for the SectionTrack payload shape.

Event Transformation

The SDK transforms Shopify Analytics events into Glood pixel format using sophisticated data transformation:

Shopify → Glood Transformation

// Shopify Analytics Event
{
  eventType: 'product_viewed',
  products: [{
    id: 'gid://shopify/Product/123',
    title: 'Cool T-Shirt',
    price: '29.99',
    variantId: 'gid://shopify/ProductVariant/456',
    // ... other Shopify data
  }],
  shop: { currency: 'USD' },
  // ... other event data
}

// Transformed to Glood Pixel
{
  event: {
    id: 'evt_abc123',
    name: 'product_viewed',
    type: 'standard',
    timestamp: '2024-03-15T10:30:00.000Z',
    clientId: 'client_xyz789',
    context: {
      page: { url: '/products/cool-t-shirt', title: 'Cool T-Shirt' },
      userAgent: 'Mozilla/5.0...',
      screen: { width: 1920, height: 1080 }
    },
    data: {
      productVariant: {
        id: '456',
        title: 'Cool T-Shirt',
        price: { amount: 29.99, currencyCode: 'USD' },
        product: {
          id: '123',
          title: 'Cool T-Shirt',
          url: '/products/cool-t-shirt'
        }
      }
    }
  },
  rkUid: 'rk_user_id',
  data: {
    customer: null,
    cart: null,
    shop: {
      name: 'My Store',
      myshopifyDomain: 'my-store.myshopify.com',
      paymentSettings: { currencyCode: 'USD' }
    }
  },
  customerPrivacy: {
    analyticsProcessingAllowed: true,
    marketingAllowed: true,
    preferencesProcessingAllowed: true,
    saleOfDataAllowed: false
  },
  sessionId: 'session_def456',
  experience: '27647', // A/B experience id from localStorage `gai_s_e`
  cartIdentifier: null
}

The experience field carries the A/B experience id assigned by the recommendations API. The SDK persists it to localStorage (key gai_s_e) after every sections fetch, and every event includes it automatically — this is how analytics segment by experience. It is null until the first sections fetch.

Event-Specific Transformations

Product Viewed

// Extracted product data
data: {
  productVariant: {
    id: '456',
    title: 'Cool T-Shirt - Blue',
    price: { amount: 29.99, currencyCode: 'USD' },
    product: {
      id: '123',
      title: 'Cool T-Shirt',
      vendor: 'Fashion Brand',
      url: '/products/cool-t-shirt',
      type: 'Apparel'
    },
    sku: 'TSH-BLUE-M',
    image: { src: 'https://example.com/image.jpg' }
  }
}

Cart Viewed

// Complete cart contents
data: {
  cart: {
    id: 'cart_123',
    cost: {
      totalAmount: { amount: 89.97, currencyCode: 'USD' }
    },
    lines: [
      {
        cost: { totalAmount: { amount: 29.99, currencyCode: 'USD' } },
        merchandise: {
          id: '456',
          title: 'Cool T-Shirt - Blue',
          price: { amount: 29.99, currencyCode: 'USD' },
          product: {
            id: '123',
            title: 'Cool T-Shirt',
            url: '/products/cool-t-shirt'
          }
        },
        quantity: 1
      }
      // ... more cart lines
    ],
    totalQuantity: 3
  }
}

Event Destination

Events (both the automatic standard events and the custom attribution events) are routed by the client’s configured version off the recommendations app’s main endpoint (default https://storefront.glood.ai). There is no separate events host.

v3 (default)
v2 (legacy)

POST {endpoint}/api/storefront/v3/headless/events

Headers

Content-Type: application/json
Authorization: Bearer <apiKey>
x-shop: your-store.myshopify.com

Payload — the headless events schema:

{
  event: {
    id: 'evt_abc123',
    name: 'product_viewed',      // or 'glood:section:click', etc.
    type: 'standard',            // 'custom' for attribution events
    timestamp: '2024-03-15T10:30:00.000Z',
    data: { /* event-specific data */ },
    customData: { track }        // present on custom/attribution events
  },
  channel: 'hydrogen',
  session_id: 'session_def456',
  client_id: 'client_xyz789',
  user_id: 'user_...',
  experience: '27647',
  customer_privacy: { /* consent flags */ },
  cart: null,
  customer: null,
  page_url: '/products/cool-t-shirt'
}

POST {endpoint}/api/storefront/event

Headers

Content-Type: application/json
x-shop-myshopify-domain: your-store.myshopify.com

v2 sends the legacy event payload (no bearer token; authenticated by shop header alone).

Need to send a v3 event manually (outside the automatic analytics flow)? Use sendHeadlessEvent(options, params) or the recommendations app’s sendEvent(params) — both POST to /api/storefront/v3/headless/events.

Event Transmission

Immediate Transmission

The SDK uses immediate transmission with retry logic:

class PixelQueue {
  add(item: PixelEvent): void {
    // Build headers from item.headers, falling back to the shop-domain header
    const headers = item.headers ?? {
      'Content-Type': 'application/json',
      'x-shop-myshopify-domain': item.shopDomain ?? '',
    };

    // Send event immediately with retry logic
    this.sendEventWithRetry(item.endpoint, headers, item.data, 0);
  }

  private async sendEventWithRetry(
    endpoint: string,
    headers: Record<string, string>,
    event: Record<string, any>,
    retryCount: number
  ): Promise<void> {
    try {
      const response = await fetch(endpoint, {
        method: 'POST',
        headers,
        body: JSON.stringify(event),
        keepalive: true,
      });

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }
    } catch (error) {
      // Retry with exponential backoff
      if (retryCount < this.retryDelays.length) {
        setTimeout(() => {
          this.sendEventWithRetry(endpoint, headers, event, retryCount + 1);
        }, this.retryDelays[retryCount]);
      }
    }
  }
}

Retry Strategy

Retry Delays: [1000, 2000, 4000, 8000] milliseconds
Max Retries: 4 attempts total (initial + 3 retries)
Backoff: Exponential backoff strategy
Error Logging: Comprehensive error logging with debug details

Network Resilience

// Automatic retry on network failures
const retryDelays = [1000, 2000, 4000, 8000]; // 1s, 2s, 4s, 8s

// Error scenarios handled:
// - Network timeouts
// - HTTP 5xx server errors
// - HTTP 4xx client errors (logged but not retried)
// - JSON serialization errors
// - CORS issues

The SDK automatically checks customer consent before sending pixels:

function checkConsent(
  requiredConsents: ConsentType[],
  canTrack: any,
  analytics: any
): boolean {
  if (!requiredConsents || requiredConsents.length === 0) {
    return true; // No consent required
  }

  return requiredConsents.every(consentType => {
    switch (consentType) {
      case 'analytics':
        return analytics.customerPrivacy?.analyticsProcessingAllowed();
      case 'marketing':
        return analytics.customerPrivacy?.marketingAllowed();
      case 'preferences':
        return analytics.customerPrivacy?.preferencesProcessingAllowed();
      case 'sale_of_data':
        return analytics.customerPrivacy?.saleOfDataAllowed();
      default:
        return false;
    }
  });
}

App	Default Consent Requirements	Description
Recommendations	`['analytics', 'marketing']`	Analytics for tracking + marketing for personalization

Privacy Scenarios

// Example consent scenarios
const consentScenarios = {
  noConsent: {
    analyticsProcessingAllowed: false,
    marketingAllowed: false,
    preferencesProcessingAllowed: false,
    saleOfDataAllowed: false,
  },
  analyticsOnly: {
    analyticsProcessingAllowed: true,
    marketingAllowed: false,
    preferencesProcessingAllowed: false,
    saleOfDataAllowed: false,
  },
  fullConsent: {
    analyticsProcessingAllowed: true,
    marketingAllowed: true,
    preferencesProcessingAllowed: true,
    saleOfDataAllowed: true,
  },
};

// Results for recommendations:
// Recommendations: noConsent ❌, analyticsOnly ❌, fullConsent ✅

Session & Identity Management

Identity is stored in cookies (CookieStorage). The cookie key names are:

Cookie	Purpose	Lifetime
`_glood_client_id`	Persistent client id	1 year
`_shopify_s`	Session id	30 minutes
`rk_uid`	Analytics user id (RK UID)	1 year with full consent, session-only otherwise
`_glood_user_id`	Server-issued visitor id from `/v3/headless/init`	1 year
`_glood_visit_id`	Server-issued per-visit id from `/v3/headless/init`	30 minutes

Client ID Generation

class CookieStorage {
  static getOrGenerateClientId(): string {
    const existingId = this.getCookie('_glood_client_id');
    if (existingId) return existingId;

    const newId = generateClientId();
    this.setCookie('_glood_client_id', newId); // default max-age 1 year
    return newId;
  }
}

Session Management

// Session ID (30-minute cookie, not sessionStorage)
static getOrGenerateSessionId(): string {
  const existingId = this.getCookie('_shopify_s');
  if (existingId) return existingId;

  const newId = generateSessionId();
  this.setCookie('_shopify_s', newId, 30 * 60); // 30 minutes
  return newId;
}

Debug Logging

Debug Mode Events

Enable debug mode to see detailed event flow:

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  debug: true, // Enable debug logging
});

Debug Log Examples

[Glood Debug] Setting up event subscriptions for apps: ['recommendations']
[Glood Debug] App recommendations subscribes to events: ['page_viewed', 'product_viewed', ...]
[Glood Debug] All unique event types: ['page_viewed', 'product_viewed', ...]
[Glood Debug] Setting up centralized subscription for product_viewed
[Glood Debug] Received product_viewed event, distributing to interested apps
[Glood Debug] Apps interested in product_viewed: ['recommendations']
[Glood Debug] Processing product_viewed event for recommendations: { products: [...] }
[Glood Debug] Consent granted for recommendations, processing event
[Glood Debug] recommendations app sending event: { event: { ... } }
[Glood Debug] Sending event immediately: { endpoint: 'https://storefront.glood.ai/api/storefront/v3/headless/events', data: {...} }
[Glood Debug] Sending event to https://storefront.glood.ai/api/storefront/v3/headless/events (attempt 1): { event: {...} }
[Glood Debug] Successfully sent event to https://storefront.glood.ai/api/storefront/v3/headless/events

Error Debug Logs

[Glood Debug] Consent not granted for recommendations, skipping event
[Glood Debug] Retrying event in 2000ms (attempt 2)
[Glood Debug] Failed event: { event: {...} }
[Glood] Failed to send pixel event after all retries: NetworkError

Performance Considerations

Event Deduplication

Events are subscribed to only once per event type:

// Single subscription per event type, distributed to multiple apps
allEventTypes.forEach((eventType: EventType) => {
  subscribe(eventType, (eventData: any) => {
    // Find all interested apps
    const interestedApps = enabledAppsWithPixel.filter(app =>
      app.subscribedEvents.includes(eventType)
    );

    // Distribute to all interested apps
    interestedApps.forEach(app => {
      app.handleEvent(eventType, eventData, client);
    });
  });
});

Immediate Transmission

No batching delays - events are sent immediately:

// No queuing delays
pixelQueue.add({
  endpoint: `${base}/api/storefront/v3/headless/events`,
  data: transformedEventData,
}); // Sends immediately

Memory Management

No accumulation - Events are not stored in memory
Immediate processing - Events are transformed and sent immediately
Cleanup - Event handlers are properly cleaned up on unmount

Error Handling

Network Errors

// Automatic retry with exponential backoff
catch (error) {
  if (retryCount < this.retryDelays.length) {
    const delay = this.retryDelays[retryCount];
    setTimeout(() => {
      this.sendEventWithRetry(endpoint, headers, event, retryCount + 1);
    }, delay);
  } else {
    console.error('[Glood] Failed to send pixel event after all retries:', error);
  }
}

// Graceful handling when consent is denied
if (!checkConsent(app.pixel.consent, canTrack, analytics)) {
  if (debug) {
    console.log(`[Glood Debug] Consent not granted for ${app.name}, skipping event`);
  }
  return; // Skip event processing
}

Transformation Errors

// Safe transformation with fallbacks
try {
  const pixelData = this.transformEventData(eventType, eventData, client);
  this.sendPixel(pixelData, client);
} catch (error) {
  console.error(`[Glood] Error transforming ${eventType} event:`, error);
  if (client.debug) {
    console.error('[Glood Debug] Original event data:', eventData);
  }
}

Custom Event Handling

Accessing Raw Events

import { useGloodAnalytics } from '@glood/hydrogen';

function CustomAnalytics() {
  const glood = useGloodAnalytics();

  useEffect(() => {
    if (!glood) return;

    const recommendationsApp = glood.getApp('recommendations');
    if (!recommendationsApp) return;

    // Custom event handling
    const originalHandler = recommendationsApp.handleEvent.bind(recommendationsApp);
    recommendationsApp.handleEvent = (eventType, eventData, client) => {
      // Custom processing
      console.log('Custom event processing:', { eventType, eventData });

      // Call original handler
      originalHandler(eventType, eventData, client);
    };
  }, [glood]);

  return null;
}

Custom Data Enrichment

// Extend event data before transformation
function enrichEventData(eventData: any): any {
  return {
    ...eventData,
    customField: 'custom value',
    timestamp: new Date().toISOString(),
    sessionData: getSessionData(),
  };
}

Best Practices

1. Debug Mode in Development

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.SHOPIFY_DOMAIN!,
  debug: process.env.NODE_ENV === 'development',
});

2. Monitor Network Errors

// Add global error handler for pixel transmission issues
window.addEventListener('unhandledrejection', (event) => {
  if (event.reason?.message?.includes('Glood')) {
    console.error('Glood pixel transmission error:', event.reason);
    // Report to error tracking service
  }
});

// Ensure appropriate consent for recommendations
const glood = createGlood({
  apps: {
    recommendations: {
      pixel: {
        consent: ['analytics', 'marketing'], // Appropriate for personalization
      },
    },
  },
});

4. Test Event Flow

// Verify events are flowing correctly
const glood = createGlood({
  debug: true, // Enable to see event flow
});

// Check browser console for:
// - Event subscriptions setup
// - Event reception and distribution
// - Consent checking results
// - Pixel transmission success/failure

​Event System

​Architecture Overview

​Components

​Event Types

​Core Events

​Commerce Events

​Attribution Events (Custom)

​Event Transformation

​Shopify → Glood Transformation

​Event-Specific Transformations

​Product Viewed

​Cart Viewed

​Event Destination

​Event Transmission

​Immediate Transmission

​Retry Strategy

​Network Resilience

​Consent Management

​Automatic Consent Checking

​Consent Requirements by App

​Privacy Scenarios

​Session & Identity Management

​Client ID Generation

​Session Management

​Debug Logging

​Debug Mode Events

​Debug Log Examples

​Error Debug Logs

​Performance Considerations

​Event Deduplication

​Immediate Transmission

​Memory Management

​Error Handling

​Network Errors

​Consent Errors

​Transformation Errors

​Custom Event Handling

​Accessing Raw Events

​Custom Data Enrichment

​Best Practices

​1. Debug Mode in Development

​2. Monitor Network Errors

​3. Validate Consent Configuration

​4. Test Event Flow

​See Also

Event System

Architecture Overview

Components

Event Types

Core Events

Commerce Events

Attribution Events (Custom)

Event Transformation

Shopify → Glood Transformation

Event-Specific Transformations

Product Viewed

Cart Viewed

Event Destination

Event Transmission

Immediate Transmission

Retry Strategy

Network Resilience

Consent Management

Automatic Consent Checking

Consent Requirements by App

Privacy Scenarios

Session & Identity Management

Client ID Generation

Session Management

Debug Logging

Debug Mode Events

Debug Log Examples

Error Debug Logs

Performance Considerations

Event Deduplication

Immediate Transmission

Memory Management

Error Handling

Network Errors

Consent Errors

Transformation Errors

Custom Event Handling

Accessing Raw Events

Custom Data Enrichment

Best Practices

1. Debug Mode in Development

2. Monitor Network Errors

3. Validate Consent Configuration

4. Test Event Flow

See Also