@streamscloud/streams-analytics-collector 1.0.10 → 1.0.12

package/dist/analytics/ViewportVisibilityTracker.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ViewportVisibilityTracker
+ *
+ * Utility for tracking when DOM elements (e.g., stream tiles) become visible in the viewport.
+ * Fires impression events only once per unique element (by streamId) per session/visit.
+ * Uses IntersectionObserver for efficient observation, with a fallback to manual visibility checks.
+ *
+ * Usage:
+ *   ViewportVisibilityTracker.registerTile(element, streamId, callback?);
+ *
+ * - The element must have a unique streamId (e.g., from data-stream-id attribute).
+ * - The impression event is fired only once per streamId per session.
+ * - Handles rapid scrolling, re-renders, and element replacement.
+ * - You can provide a custom callback to be called when the element becomes visible.
+ */
+export declare class ViewportVisibilityTracker {
+    private static trackedStreamIds;
+    private static observedElements;
+    private static callbacks;
+    private static observer;
+    /**
+     * Register a tile element for visibility tracking.
+     * @param el The DOM element to observe
+     * @param streamId The unique stream ID for this tile
+     * @param callback Optional callback to call when the element becomes visible (defaults to AppEventsTracker.trackStreamTileImpression)
+     */
+    static registerTile(el: HTMLElement, streamId: string, callback?: (streamId: string) => void): void;
+    /**
+     * Internal: Get or create the IntersectionObserver instance
+     */
+    private static getObserver;
+    /**
+     * Internal: IntersectionObserver callback
+     */
+    private static handleIntersections;
+    /**
+     * Fallback: Check if an element is in the viewport (at least 50% visible)
+     * @param el The DOM element
+     * @returns true if at least 50% of the element is visible
+     */
+    static isElementInViewport(el: HTMLElement): boolean;
+    /**
+     * Reset tracked state (for testing or new session)
+     */
+    static reset(): void;
+}

package/dist/analytics/ViewportVisibilityTracker.js

@@ -0,0 +1,117 @@
+import { AppEventsTracker } from './app-events-tracker.js';
+
+/**
+ * ViewportVisibilityTracker
+ *
+ * Utility for tracking when DOM elements (e.g., stream tiles) become visible in the viewport.
+ * Fires impression events only once per unique element (by streamId) per session/visit.
+ * Uses IntersectionObserver for efficient observation, with a fallback to manual visibility checks.
+ *
+ * Usage:
+ *   ViewportVisibilityTracker.registerTile(element, streamId, callback?);
+ *
+ * - The element must have a unique streamId (e.g., from data-stream-id attribute).
+ * - The impression event is fired only once per streamId per session.
+ * - Handles rapid scrolling, re-renders, and element replacement.
+ * - You can provide a custom callback to be called when the element becomes visible.
+ */
+class ViewportVisibilityTracker {
+    // Set of streamIds that have already been tracked for impression
+    static trackedStreamIds = new Set();
+    // Map from streamId to the currently observed element
+    static observedElements = new Map();
+    // Map from streamId to the callback to call when visible
+    static callbacks = new Map();
+    // Singleton IntersectionObserver instance
+    static observer = null;
+    /**
+     * Register a tile element for visibility tracking.
+     * @param el The DOM element to observe
+     * @param streamId The unique stream ID for this tile
+     * @param callback Optional callback to call when the element becomes visible (defaults to AppEventsTracker.trackStreamTileImpression)
+     */
+    static registerTile(el, streamId, callback = AppEventsTracker.trackStreamTileImpression.bind(AppEventsTracker)) {
+        if (!el || !streamId)
+            return;
+        // If already tracked, do nothing
+        if (this.trackedStreamIds.has(streamId))
+            return;
+        // If an element for this streamId is already being observed, unobserve it (handles re-renders)
+        const prevEl = this.observedElements.get(streamId);
+        if (prevEl && prevEl !== el) {
+            this.getObserver().unobserve(prevEl);
+        }
+        this.observedElements.set(streamId, el);
+        this.callbacks.set(streamId, callback);
+        this.getObserver().observe(el);
+    }
+    /**
+     * Internal: Get or create the IntersectionObserver instance
+     */
+    static getObserver() {
+        if (!this.observer) {
+            this.observer = new window.IntersectionObserver(this.handleIntersections.bind(this), {
+                threshold: 0.5, // At least 50% of the element must be visible
+            });
+        }
+        return this.observer;
+    }
+    /**
+     * Internal: IntersectionObserver callback
+     */
+    static handleIntersections(entries) {
+        for (const entry of entries) {
+            const el = entry.target;
+            // Try to get streamId from map or from data attribute
+            let streamId = Array.from(this.observedElements.entries()).find(([, v]) => v === el)?.[0];
+            if (!streamId) {
+                streamId = el.getAttribute('data-stream-id') || undefined;
+            }
+            if (!streamId)
+                continue;
+            if (entry.isIntersecting && entry.intersectionRatio >= 0.5) {
+                // Only fire once per streamId per session
+                if (!this.trackedStreamIds.has(streamId)) {
+                    this.trackedStreamIds.add(streamId);
+                    const callback = this.callbacks.get(streamId);
+                    if (callback) {
+                        callback(streamId);
+                    }
+                }
+                // Once tracked, stop observing this element
+                this.getObserver().unobserve(el);
+                this.observedElements.delete(streamId);
+                this.callbacks.delete(streamId);
+            }
+        }
+    }
+    /**
+     * Fallback: Check if an element is in the viewport (at least 50% visible)
+     * @param el The DOM element
+     * @returns true if at least 50% of the element is visible
+     */
+    static isElementInViewport(el) {
+        if (!el)
+            return false;
+        const rect = el.getBoundingClientRect();
+        const windowHeight = (window.innerHeight || document.documentElement.clientHeight);
+        const windowWidth = (window.innerWidth || document.documentElement.clientWidth);
+        const vertInView = (rect.top <= windowHeight * 0.5) && ((rect.top + rect.height * 0.5) >= 0);
+        const horInView = (rect.left <= windowWidth * 0.5) && ((rect.left + rect.width * 0.5) >= 0);
+        return vertInView && horInView;
+    }
+    /**
+     * Reset tracked state (for testing or new session)
+     */
+    static reset() {
+        this.trackedStreamIds.clear();
+        this.observedElements.clear();
+        this.callbacks.clear();
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = null;
+        }
+    }
+}
+
+export { ViewportVisibilityTracker };

package/dist/analytics/app-events-tracker.d.ts

@@ -66,10 +66,19 @@ export declare class AppEventsTracker {
      */
     static trackCommunityMessageOpened(messageId: string, status: string): void;
     /**
-     * Track when a stream tile is shown to the user
+     * Track when a stream tile is shown to the user (basic, immediate call).
      * @param streamId - The ID of the stream
      */
     static trackStreamTileImpression(streamId: string): void;
+    /**
+     * Track when a stream tile is shown to the user, using viewport visibility tracking.
+     * The impression event will only be fired if the element becomes visible (at least 50% in viewport).
+     * The event is only fired once per streamId per session/visit.
+     *
+     * @param el - The DOM element to observe (e.g., the stream tile)
+     * @param streamId - The unique stream ID for this tile
+     */
+    static trackStreamTileImpressionWithVisibility(el: HTMLElement, streamId: string): void;
     /**
      * Track when a stream tile is clicked
      * @param streamId - The ID of the stream
@@ -111,6 +120,25 @@ export declare class AppEventsTracker {
      * @deprecated Consider using trackShortVideoProgress and reportPageVideoViews for better tracking of multiple videos
      */
     static trackClosed(postId: string, streamId: string): void;
+    /**
+     * Track when an ad is shown to the user
+     * @param adId - The ID of the ad
+     */
+    static trackAdImpression(adId: string): void;
+    /**
+     * Track when an ad is clicked by the user
+     * @param adId - The ID of the ad
+     */
+    static trackAdClick(adId: string): void;
+    /**
+     * Track when an ad is shown to the user, using viewport visibility tracking.
+     * The impression event will only be fired if the element becomes visible (at least 50% in viewport).
+     * The event is only fired once per adId per session/visit.
+     *
+     * @param el - The DOM element to observe (e.g., the ad element)
+     * @param adId - The unique ad ID for this element
+     */
+    static trackAdImpressionWithVisibility(el: HTMLElement, adId: string): void;
     /**
      * Report an app event to the API
      * @private

package/dist/analytics/app-events-tracker.js

@@ -1,5 +1,6 @@
 import { AppEventType, CommunityMessageStatus } from './types.js';
 import AnalyticsQuery from '../analytics.graphql.js';
+import { ViewportVisibilityTracker } from './ViewportVisibilityTracker.js';
 
 /**
  * AppEventsTracker is a utility class for tracking various user events in StreamsCloud applications
@@ -114,12 +115,28 @@ class AppEventsTracker {
         }
     }
     /**
-     * Track when a stream tile is shown to the user
+     * Track when a stream tile is shown to the user (basic, immediate call).
      * @param streamId - The ID of the stream
      */
     static trackStreamTileImpression(streamId) {
         this.reportAppEvent(streamId, AppEventType.StreamTileImpression);
     }
+    /**
+     * Track when a stream tile is shown to the user, using viewport visibility tracking.
+     * The impression event will only be fired if the element becomes visible (at least 50% in viewport).
+     * The event is only fired once per streamId per session/visit.
+     *
+     * @param el - The DOM element to observe (e.g., the stream tile)
+     * @param streamId - The unique stream ID for this tile
+     */
+    static trackStreamTileImpressionWithVisibility(el, streamId) {
+        if (!el || !streamId)
+            return;
+        ViewportVisibilityTracker.registerTile(el, streamId, (sid) => {
+            this.reportAppEvent(sid, AppEventType.StreamTileImpression);
+        });
+        // The ViewportVisibilityTracker will call the callback when visible
+    }
     /**
      * Track when a stream tile is clicked
      * @param streamId - The ID of the stream
@@ -186,6 +203,36 @@ class AppEventsTracker {
             this.reported.splice(postIndex, 1);
         }
     }
+    /**
+     * Track when an ad is shown to the user
+     * @param adId - The ID of the ad
+     */
+    static trackAdImpression(adId) {
+        this.reportAppEvent(adId, AppEventType.AdImpression);
+    }
+    /**
+     * Track when an ad is clicked by the user
+     * @param adId - The ID of the ad
+     */
+    static trackAdClick(adId) {
+        this.reportAppEvent(adId, AppEventType.AdClick);
+    }
+    /**
+     * Track when an ad is shown to the user, using viewport visibility tracking.
+     * The impression event will only be fired if the element becomes visible (at least 50% in viewport).
+     * The event is only fired once per adId per session/visit.
+     *
+     * @param el - The DOM element to observe (e.g., the ad element)
+     * @param adId - The unique ad ID for this element
+     */
+    static trackAdImpressionWithVisibility(el, adId) {
+        if (!el || !adId)
+            return;
+        ViewportVisibilityTracker.registerTile(el, adId, (aid) => {
+            this.reportAppEvent(aid, AppEventType.AdImpression);
+        });
+        // The ViewportVisibilityTracker will call the callback when visible
+    }
     /**
      * Report an app event to the API
      * @private

package/dist/analytics/index.d.ts

@@ -1,2 +1,3 @@
 export { AppEventsTracker } from './app-events-tracker';
 export { AppEventType, CommunityMessageStatus, type TrackAppEventInput } from './types';
+export * from './ViewportVisibilityTracker';

package/dist/analytics/index.js

@@ -1,2 +1,3 @@
 export { AppEventsTracker } from './app-events-tracker.js';
 export { AppEventType, CommunityMessageStatus } from './types.js';
+export { ViewportVisibilityTracker } from './ViewportVisibilityTracker.js';

package/dist/analytics/types.d.ts

@@ -8,7 +8,9 @@ export declare enum AppEventType {
     StreamEngagementTime = "STREAM_ENGAGEMENT_TIME",
     StreamScrollDepth = "STREAM_SCROLL_DEPTH",
     StreamPageView = "STREAM_PAGE_VIEW",
-    StreamProductClick = "STREAM_PRODUCT_CLICK"
+    StreamProductClick = "STREAM_PRODUCT_CLICK",
+    AdImpression = "AD_IMPRESSION",
+    AdClick = "AD_CLICK"
 }
 export declare enum CommunityMessageStatus {
     Sent = "SENT",

package/dist/analytics/types.js

@@ -10,6 +10,8 @@ var AppEventType;
     AppEventType["StreamScrollDepth"] = "STREAM_SCROLL_DEPTH";
     AppEventType["StreamPageView"] = "STREAM_PAGE_VIEW";
     AppEventType["StreamProductClick"] = "STREAM_PRODUCT_CLICK";
+    AppEventType["AdImpression"] = "AD_IMPRESSION";
+    AppEventType["AdClick"] = "AD_CLICK";
 })(AppEventType || (AppEventType = {}));
 var CommunityMessageStatus;
 (function (CommunityMessageStatus) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamscloud/streams-analytics-collector",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",