@streamscloud/streams-analytics-collector 1.0.0 → 1.0.1

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

@@ -0,0 +1,94 @@
+/**
+ * AppEventsTracker is a utility class for tracking various user events in StreamsCloud applications
+ * such as post views, community message views, stream interactions, etc.
+ */
+export declare class AppEventsTracker {
+    private static reported;
+    private static gqlEndpoint;
+    /**
+     * Set the GraphQL endpoint for making API calls
+     * @param endpoint - The GraphQL endpoint URL
+     */
+    static setEndpoint(endpoint: string): void;
+    /**
+     * Track when a post is opened
+     * @param postId - The ID of the post
+     * @param ownerId - The ID of the owner
+     */
+    static trackPostOpened(postId: string, ownerId: string): void;
+    /**
+     * Track when a post is being played
+     * @param postId - The ID of the post
+     * @param playedPercents - The percentage of the post that has been played
+     */
+    static trackPostPlaying(postId: string, playedPercents: number): void;
+    /**
+     * Track when a community message is opened
+     * @param messageId - The ID of the message
+     * @param status - The status of the message
+     */
+    static trackCommunityMessageOpened(messageId: string, status: string): void;
+    /**
+     * Track when a stream tile is shown to the user
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamTileImpression(streamId: string): void;
+    /**
+     * Track when a stream tile is clicked
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamTileClick(streamId: string): void;
+    /**
+     * Track when a stream is viewed
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamView(streamId: string): void;
+    /**
+     * Track the amount of time a user engages with a stream
+     * @param streamId - The ID of the stream
+     * @param engagementTimeSeconds - The engagement time in seconds
+     */
+    static trackStreamEngagementTime(streamId: string, engagementTimeSeconds: number): void;
+    /**
+     * Track how deep a user scrolls in a stream
+     * @param streamId - The ID of the stream
+     * @param scrollDepth - The scroll depth (typically a percentage)
+     */
+    static trackStreamScrollDepth(streamId: string, scrollDepth: number): void;
+    /**
+     * Track when a stream page is viewed
+     * @param pageId - The ID of the page
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamPageView(pageId: string, streamId: string): void;
+    /**
+     * Track when a product in a stream is clicked
+     * @param productId - The ID of the product
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamProductClicked(productId: string, streamId: string): void;
+    /**
+     * Track when a post is closed
+     * @param postId - The ID of the post
+     */
+    static trackClosed(postId: string): void;
+    /**
+     * Report an app event to the API
+     * @private
+     * @param targetId - The ID of the target object
+     * @param eventType - The type of event
+     * @param ownerId - The ID of the owner (optional)
+     * @param value - Additional value for the event (optional)
+     */
+    private static reportAppEvent;
+    /**
+     * Save an app event to the API
+     * @private
+     * @param targetId - The ID of the target object
+     * @param eventType - The type of event
+     * @param ownerId - The ID of the owner (optional)
+     * @param value - Additional value for the event (optional)
+     */
+    private static saveAppEvent;
+    private static queryGql;
+}

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

@@ -0,0 +1,167 @@
+import { AppEventType, CommunityMessageStatus } from './types.js';
+
+/**
+ * AppEventsTracker is a utility class for tracking various user events in StreamsCloud applications
+ * such as post views, community message views, stream interactions, etc.
+ */
+class AppEventsTracker {
+    static reported = [];
+    static gqlEndpoint = '';
+    /**
+     * Set the GraphQL endpoint for making API calls
+     * @param endpoint - The GraphQL endpoint URL
+     */
+    static setEndpoint(endpoint) {
+        this.gqlEndpoint = endpoint;
+    }
+    /**
+     * Track when a post is opened
+     * @param postId - The ID of the post
+     * @param ownerId - The ID of the owner
+     */
+    static trackPostOpened(postId, ownerId) {
+        this.reportAppEvent(postId, AppEventType.PostView, ownerId);
+    }
+    /**
+     * Track when a post is being played
+     * @param postId - The ID of the post
+     * @param playedPercents - The percentage of the post that has been played
+     */
+    static trackPostPlaying(postId, playedPercents) {
+        if (playedPercents > 0.2 && this.reported.indexOf(postId) === -1) {
+            this.reportAppEvent(postId, AppEventType.PostView);
+        }
+    }
+    /**
+     * Track when a community message is opened
+     * @param messageId - The ID of the message
+     * @param status - The status of the message
+     */
+    static trackCommunityMessageOpened(messageId, status) {
+        if (status === CommunityMessageStatus.Sent) {
+            this.reportAppEvent(messageId, AppEventType.CommunityMessageView);
+        }
+    }
+    /**
+     * Track when a stream tile is shown to the user
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamTileImpression(streamId) {
+        this.reportAppEvent(streamId, AppEventType.StreamTileImpression);
+    }
+    /**
+     * Track when a stream tile is clicked
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamTileClick(streamId) {
+        this.reportAppEvent(streamId, AppEventType.StreamTileClick);
+    }
+    /**
+     * Track when a stream is viewed
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamView(streamId) {
+        this.reportAppEvent(streamId, AppEventType.StreamView);
+    }
+    /**
+     * Track the amount of time a user engages with a stream
+     * @param streamId - The ID of the stream
+     * @param engagementTimeSeconds - The engagement time in seconds
+     */
+    static trackStreamEngagementTime(streamId, engagementTimeSeconds) {
+        this.reportAppEvent(streamId, AppEventType.StreamEngagementTime, undefined, engagementTimeSeconds);
+    }
+    /**
+     * Track how deep a user scrolls in a stream
+     * @param streamId - The ID of the stream
+     * @param scrollDepth - The scroll depth (typically a percentage)
+     */
+    static trackStreamScrollDepth(streamId, scrollDepth) {
+        this.reportAppEvent(streamId, AppEventType.StreamScrollDepth, undefined, scrollDepth);
+    }
+    /**
+     * Track when a stream page is viewed
+     * @param pageId - The ID of the page
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamPageView(pageId, streamId) {
+        this.reportAppEvent(pageId, AppEventType.StreamPageView, streamId);
+    }
+    /**
+     * Track when a product in a stream is clicked
+     * @param productId - The ID of the product
+     * @param streamId - The ID of the stream
+     */
+    static trackStreamProductClicked(productId, streamId) {
+        this.reportAppEvent(productId, AppEventType.StreamProductClick, streamId);
+    }
+    /**
+     * Track when a post is closed
+     * @param postId - The ID of the post
+     */
+    static trackClosed(postId) {
+        const postIndex = this.reported.indexOf(postId);
+        if (postIndex >= 0) {
+            this.reported.splice(postIndex, 1);
+        }
+    }
+    /**
+     * Report an app event to the API
+     * @private
+     * @param targetId - The ID of the target object
+     * @param eventType - The type of event
+     * @param ownerId - The ID of the owner (optional)
+     * @param value - Additional value for the event (optional)
+     */
+    static async reportAppEvent(targetId, eventType, ownerId, value) {
+        await this.saveAppEvent(targetId, eventType, ownerId, value);
+    }
+    /**
+     * Save an app event to the API
+     * @private
+     * @param targetId - The ID of the target object
+     * @param eventType - The type of event
+     * @param ownerId - The ID of the owner (optional)
+     * @param value - Additional value for the event (optional)
+     */
+    static async saveAppEvent(targetId, eventType, ownerId, value) {
+        if (!this.gqlEndpoint) {
+            console.warn('An attempt to save app event without initializing GraphQL endpoint detected');
+            return;
+        }
+        const query = `
+      mutation TrackAppEvent($input: TrackAppEventInput!) {
+        trackAppEvent(input: $input) {
+          void
+        }
+      }
+    `;
+        await this.queryGql(query, {
+            input: {
+                eventType,
+                targetId,
+                ownerId,
+                value
+            }
+        });
+    }
+    static queryGql = async (query, variables) => {
+        const response = await fetch(this.gqlEndpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                query,
+                variables
+            })
+        });
+        const gql = await response.json();
+        if (!gql.data) {
+            throw new Error(JSON.stringify(gql.errors));
+        }
+        return gql.data;
+    };
+}
+
+export { AppEventsTracker };

package/dist/analytics/index.d.ts

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

package/dist/analytics/types.d.ts

@@ -0,0 +1,23 @@
+export declare enum AppEventType {
+    PostView = "POST_VIEW",
+    CommunityMessageView = "COMMUNITY_MESSAGE_VIEW",
+    StreamTileImpression = "STREAM_TILE_IMPRESSION",
+    StreamTileClick = "STREAM_TILE_CLICK",
+    StreamView = "STREAM_VIEW",
+    StreamEngagementTime = "STREAM_ENGAGEMENT_TIME",
+    StreamScrollDepth = "STREAM_SCROLL_DEPTH",
+    StreamPageView = "STREAM_PAGE_VIEW",
+    StreamProductClick = "STREAM_PRODUCT_CLICK"
+}
+export declare enum CommunityMessageStatus {
+    Sent = "SENT",
+    Delivered = "DELIVERED",
+    Read = "READ",
+    Failed = "FAILED"
+}
+export type TrackAppEventInput = {
+    eventType: AppEventType;
+    targetId: string;
+    ownerId?: string;
+    value?: number;
+};

package/dist/analytics/types.js

@@ -0,0 +1,21 @@
+var AppEventType;
+(function (AppEventType) {
+    AppEventType["PostView"] = "POST_VIEW";
+    AppEventType["CommunityMessageView"] = "COMMUNITY_MESSAGE_VIEW";
+    AppEventType["StreamTileImpression"] = "STREAM_TILE_IMPRESSION";
+    AppEventType["StreamTileClick"] = "STREAM_TILE_CLICK";
+    AppEventType["StreamView"] = "STREAM_VIEW";
+    AppEventType["StreamEngagementTime"] = "STREAM_ENGAGEMENT_TIME";
+    AppEventType["StreamScrollDepth"] = "STREAM_SCROLL_DEPTH";
+    AppEventType["StreamPageView"] = "STREAM_PAGE_VIEW";
+    AppEventType["StreamProductClick"] = "STREAM_PRODUCT_CLICK";
+})(AppEventType || (AppEventType = {}));
+var CommunityMessageStatus;
+(function (CommunityMessageStatus) {
+    CommunityMessageStatus["Sent"] = "SENT";
+    CommunityMessageStatus["Delivered"] = "DELIVERED";
+    CommunityMessageStatus["Read"] = "READ";
+    CommunityMessageStatus["Failed"] = "FAILED";
+})(CommunityMessageStatus || (CommunityMessageStatus = {}));
+
+export { AppEventType, CommunityMessageStatus };

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export { StreamsContentApiClient } from './streams-content-api-client';
 export { type StreamsApiClientModel } from './streams-api-client-model';
 export * as Types from './types';
 export { SiteAdCampaignsOrderBy, SiteContentListsOrderBy, SitePostsOrderBy } from './types';
+export { AppEventsTracker, AppEventType, CommunityMessageStatus } from './analytics';

package/dist/index.js

@@ -2,3 +2,5 @@ export { StreamsContentApiClient } from './streams-content-api-client.js';
 import * as types from './types.js';
 export { types as Types };
 export { SiteAdCampaignsOrderBy, SiteContentListsOrderBy, SitePostsOrderBy } from './types.js';
+export { AppEventsTracker } from './analytics/app-events-tracker.js';
+export { AppEventType, CommunityMessageStatus } from './analytics/types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamscloud/streams-analytics-collector",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -11,6 +11,10 @@
       "types": "./dist/index.d.ts",
       "svelte": "./dist/index.js"
     },
+    "./analytics": {
+      "import": "./dist/analytics/index.js",
+      "types": "./dist/analytics/index.d.ts"
+    },
     "./data-loaders": {
       "import": "./dist/data-loaders/index.js",
       "types": "./dist/data-loaders/index.d.ts"