# What Is the intersectionObserver Module in Web-Tracing? Element Exposure Tracking Explained

> Discover the intersectionObserver module in web-tracing for precise DOM element exposure tracking. Monitor viewport entry and exit with detailed timing data for better web performance insights.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: deep-dive
- Published: 2026-03-06

---

**The `intersectionObserver` module is the core visibility tracking component that monitors when DOM elements enter or leave the viewport and emits detailed exposure events with precise timing data.**

The `intersectionObserver` module in the web-tracing SDK provides a framework-agnostic solution for tracking element exposure metrics. Located in the core package at [`packages/core/src/lib/intersectionObserver.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/intersectionObserver.ts), this module leverages the native Intersection Observer API to capture precise visibility timestamps and user-defined parameters. It enables detailed analytics on how users interact with specific page elements across Vue 2, Vue 3, and React applications.

## Core Functionality of the intersectionObserver Module

The module serves as the SDK's engine for recording element visibility events, implementing several specialized responsibilities to ensure accurate tracking.

### Threshold-Based Observer Management

The module creates separate `IntersectionObserver` instances for each configured **visibility threshold**. This architectural decision prevents the same DOM node from being observed by multiple observers simultaneously, which could cause conflicting callbacks. The `Intersection` class defined in [`packages/core/src/lib/intersectionObserver.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/intersectionObserver.ts) manages these instances, mapping each threshold value to its own dedicated observer to ensure clean separation of concerns.

### Exposure Timing Capture

When a tracked element becomes visible (`isIntersecting` returns true), the module immediately records the `showTime` timestamp. Upon the element leaving the viewport, it captures `showEndTime` and triggers event emission through `sendData.emit`. This millisecond-precision timing allows analytics systems to calculate exact exposure duration, distinguishing between brief scroll-past views and meaningful engagement.

### Custom Data Aggregation

The module accepts a `params` object from developers, attaching this custom metadata directly to the event payload. This extensibility allows teams to correlate exposure events with specific business context—such as campaign identifiers, A/B test variants, or element categories—without modifying the core SDK code.

## Source Code Architecture and File Locations

The implementation spans several key files within the `m-cheng-web/web-tracing` repository, each serving distinct architectural purposes:

- **[`packages/core/src/lib/intersectionObserver.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/intersectionObserver.ts)**: Contains the `Intersection` class definition, observer creation logic, threshold management, and public API methods (`initIntersection`, `destroyIntersection`).
- **[`packages/core/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/index.ts)**: Integrates the observer into the SDK lifecycle by invoking `initIntersection()` during initialization and registering `destroyIntersection()` for teardown (lines 38-41).
- **[`docs/guide/functions/intersection.md`](https://github.com/m-cheng-web/web-tracing/blob/main/docs/guide/functions/intersection.md)**: Provides user-facing documentation explaining the event payload structure, configuration options, and usage patterns.
- **Framework wrappers**: Each framework-specific package ([`packages/vue2/src/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/vue2/src/index.ts), [`packages/vue3/src/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/vue3/src/index.ts), [`packages/react/src/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/react/src/index.ts)) exports convenience functions that proxy calls to the core implementation.

## Implementing Element Exposure Tracking

The module exposes a consistent API across all supported frameworks, enabling developers to track element visibility with minimal configuration.

### Basic Usage Across Frameworks

Import the tracking functions from your specific framework package and invoke `intersectionObserver()` with a target element and configuration options:

```javascript
import {
  intersectionObserver,
  intersectionUnobserve,
  intersectionDisconnect
} from '@web-tracing/vue3'  // or @web-tracing/vue2, @web-tracing/react

const target = document.querySelector('#hero-banner');

// Start tracking visibility when 50% of element is visible
intersectionObserver({
  target,
  threshold: 0.5,
  params: { campaignId: 'summer-sale', elementType: 'banner' }
});

// Stop tracking specific element
intersectionUnobserve(target);

// Cleanup all observers on component unmount or page unload
intersectionDisconnect();

```

These framework wrappers implement thin proxies to the core SDK methods:

```typescript
// Framework wrapper implementation pattern
export function intersectionObserver(gather) {
  _support.intersection?.observe(gather)
}
export function intersectionUnobserve(target) {
  _support.intersection?.unobserve(target)
}
export function intersectionDisconnect() {
  _support.intersection?.disconnect()
}

```

### Event Payload Structure

When visibility changes occur, the module emits a structured data object containing temporal and contextual information:

```json
{
  "eventType": "intersection",
  "threshold": 0.5,
  "observeTime": 1689734412090,
  "showTime": 1689734412098,
  "showEndTime": 1689734414097,
  "params": { "campaignId": "summer-sale", "elementType": "banner" },
  "triggerPageUrl": "http://localhost:6656/#/intersection"
}

```

The `observeTime` marks when tracking began, `showTime` records when the element entered the viewport, and `showEndTime` captures when it exited. This schema enables downstream analytics to calculate total exposure duration and correlate visibility with conversion events.

## Summary

- The `intersectionObserver` module provides the core functionality for tracking DOM element visibility using the native Intersection Observer API.
- It creates dedicated observer instances per threshold to prevent observation conflicts and ensure accurate, independent timing data for each visibility ratio.
- The module captures millisecond-precision timestamps (`showTime`, `showEndTime`) and emits structured events through `sendData.emit` when elements enter and leave the viewport.
- Framework-agnostic wrapper functions—`intersectionObserver`, `intersectionUnobserve`, and `intersectionDisconnect`—are exposed through Vue 2, Vue 3, and React packages for consistent developer experience.
- Lifecycle management is handled through `initIntersection()` during SDK startup and `destroyIntersection()` during teardown, as implemented in [`packages/core/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/index.ts), preventing memory leaks in single-page applications.

## Frequently Asked Questions

### What does the intersectionObserver module track?

The module tracks **element exposure events**, recording precisely when DOM elements enter and leave the viewport based on configured visibility thresholds. It captures timestamps for observation initialization (`observeTime`), visibility start (`showTime`), and visibility end (`showEndTime`), along with arbitrary user-defined parameters and the threshold value that triggered the event.

### How do I stop observing a specific element?

Call the `intersectionUnobserve(target)` function with the DOM element as the sole argument. This removes the specific target from the internal observation list without affecting other tracked elements on the page. To completely terminate all active observations and free resources, invoke `intersectionDisconnect()`, which is typically called during component unmounting or page navigation.

### Where is the observer initialized in the SDK lifecycle?

The observer initializes automatically during SDK startup within [`packages/core/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/index.ts), specifically at lines 38-41 where `initIntersection()` is invoked as part of the main initialization sequence. The module also registers `destroyIntersection()` for cleanup when the SDK instance is destroyed, ensuring proper resource disposal and preventing memory leaks in long-running single-page applications.

### What data is included in the intersection event payload?

The emitted event payload contains: `eventType` (always set to "intersection"), `threshold` (the visibility ratio that triggered the event), `observeTime` (SDK timestamp when observation began), `showTime` and `showEndTime` (defining the visibility window), `params` (custom metadata provided by the developer), and `triggerPageUrl` (the current page URL at event time). This comprehensive schema enables detailed analysis of element exposure duration and business context.