Skip to main content

PUI Analytics Scripting Object

Welcome to the PUI Analytics Scripting Object - an analytics solution designed for tracking business events and performance metrics from Microapps.

What is PUI Analytics SO?​

The PUI Analytics Scripting Object (@elliemae/pui-analytics-so) is a TypeScript library that provides a unified interface for collecting, processing, and forwarding analytics data to multiple destinations including Google Tag Manager (GTM) and LogRocket. Built with performance and reliability in mind, it seamlessly integrates into micro-frontend architectures and supports sophisticated event sampling strategies.

Key Features​

🎯 Comprehensive Event Tracking​

  • Business analytics events with rich contextual data
  • Automatic enrichment with environment, app, and user information

⚡ Performance Monitoring​

  • High-precision timing measurements using the Performance API
  • Automatic performance observation for measure entries
  • Start/end timing methods for custom measurements

🔄 Smart Sampling & Filtering​

  • Configurable per-event sampling ratios to control timing data volume
  • Head sampling (deterministic, not random) for consistent data quality
  • Automatic filtering of third-party GTM/GA4 performance measures
  • Sampling applies uniformly to all three destinations (Splunk, GTM, LogRocket)
  • BA events (sendBAEvent) are not sampled — always forwarded to GTM and LogRocket

🔗 Multi-Platform Integration​

  • Google Tag Manager: Automatic event forwarding to GTM data layer
  • LogRocket: Seamless integration for session replay correlation
  • PUI Diagnostics: Compatible with PUI Logger or console
  • Micro-frontend support: Works across iframe boundaries with parent window detection

🛡️ Enterprise-Ready​

  • TypeScript support with comprehensive type definitions
  • Robust error handling with try-catch patterns
  • Memory-efficient with automatic performance mark cleanup
  • Configurable sampling ratios for high-traffic scenarios

Use Cases​

Business Analytics Events (sendBAEvent)​

Track user interactions, page views, feature usage, and errors. Every call reaches GTM (full enriched context) and LogRocket (caller-supplied fields only). No sampling — subject only to LogRocket's sliding-window throttle.

Manual Performance Timing (startTiming / endTiming)​

Bracket a unit of work (API calls, component renders, long-running operations) to measure its wall-clock duration. The resulting measure is automatically captured by the PerformanceObserver pipeline.

Automatic Performance Observation​

A page-wide PerformanceObserver captures all performance.measure() entries — including those from endTiming and any other code on the page. Third-party measures from GTM/GA4 are automatically filtered out. Sampled entries (default 25%) fan out to Splunk and GTM.

Sampling Ratio Management​

Runtime CRUD for per-event sampling ratios via setTimingEventSamplingRatio, getTimingEventSamplingRatio, deleteTimingEventSamplingRatio, and getAllTimingEventSamplingRatios. Sampling applies uniformly to both timing destinations (Splunk and GTM).

Session Replay Integration​

Correlate events with LogRocket sessions for comprehensive debugging and user journey analysis. LogRocket receives only BA events (caller-supplied fields) — timing events are not sent to LogRocket — to conserve the 2,000 total-property session budget.

Shared LogRocket Throttle (lrTrackGuarded)​

The throttled logRocket.track() wrapper used internally is exported so consumers (e.g. pui-app-sdk) can send custom events to LogRocket with the same sliding-window throttle and property-count guards — no need to duplicate throttle logic across packages.

Architecture Overview​

┌──────────────────┐     ┌──────────────────────────────┐     ┌──────────────────┐
│    Your App      │     │   PUI Analytics SO           │     │   Destinations   │
│                  │     │                              │     │                  │
│ ┌──────────────┐ │     │                              │     │ ┌──────────────┐ │
│ │ sendBAEvent()│─┼────▶│  GTM: full enriched payload  │────▶│ │   GTM        │ │
│ │ (BA events)  │ │     │  LR:  caller fields only     │────▶│ │  Data Layer  │ │
│ └──────────────┘ │     │  (no sampling, LR throttled)  │     │ └──────────────┘ │
│                  │     │                              │     │                  │
│ ┌──────────────┐ │     │  ┌────────────────────────┐  │     │ ┌──────────────┐ │
│ │startTiming() │ │     │  │  PerformanceObserver   │  │     │ │  LogRocket   │ │
│ │ endTiming()  │─┼────▶│  │  (all page measures)   │  │     │ │  (BA only)   │ │
│ └──────────────┘ │     │  └──────────┬─────────────┘  │     │ └──────────────┘ │
│                  │     │             │                 │     │                  │
│ ┌──────────────┐ │     │  ┌──────────▼─────────────┐  │     │ ┌──────────────┐ │
│ │ Other code's │ │     │  │ Filter GTM/GA4 names   │  │     │ │   Splunk     │ │
│ │ .measure()   │─┼────▶│  │ Head Sampling (25%)    │  │     │ │  (Logger)    │ │
│ └──────────────┘ │     │  └──────────┬─────────────┘  │     │ └──────────────┘ │
│                  │     │             │                 │     │                  │
│                  │     │  Splunk: full timing payload  │────▶│                  │
│                  │     │  GTM: enriched + timing data  │────▶│                  │
└──────────────────┘     └──────────────────────────────┘     └──────────────────┘

Getting Started​

Ready to integrate powerful analytics into your application? Choose your path:

🚀 Quick Start Guide​

Get up and running in minutes with our streamlined setup process.

📖 Complete Usage Guide​

Comprehensive documentation covering all features, best practices, and real-world examples.

🔧 API Reference​

Detailed technical documentation for all classes, methods, and interfaces.

💡 Examples & Patterns​

Ready-to-use code examples for common integration scenarios.

Installation​

# Using npm
npm install @elliemae/pui-analytics-so

# Using pnpm (recommended)
pnpm add @elliemae/pui-analytics-so

Quick Example​

import { Analytics, updateBAEventParameters } from '@elliemae/pui-analytics-so';

// Configure global parameters (applied to all events)
updateBAEventParameters({
  envName: 'production',
  appId: 'my-awesome-app',
  userId: 'user-123',
  instanceId: 'instance-456',
});

// Initialize analytics with optional sampling
const analytics = new Analytics({
  logger: console, // or PUI Diagnostics Logger
  timingEventSamplingRatios: {
    'user-interaction': 0.1, // Sample 10% of user-interaction timing events
    'api-call': 1.0, // Sample 100% of api-call timing events
  },
});

// Track business events
await analytics.sendBAEvent({
  event: 'user-login',
  method: 'oauth',
  timestamp: new Date().toISOString(),
});

// Measure performance
const timing = await analytics.startTiming('api-call', {
  appId: 'my-app',
  appUrl: window.location.href,
});

// ... perform operation ...

await analytics.endTiming(timing, {
  appId: 'my-app',
  appUrl: window.location.href,
});

Start with our Usage Guide or jump straight to the Quick Start section.