Fix config for callbacks (close #1275)

Author: greg-el

api-docs/docs/browser-tracker/browser-tracker.api.md

@@ -215,6 +215,9 @@ export interface EnableAnonymousTrackingConfiguration {
     stateStorageStrategy?: StateStorageStrategy;
 }
 
+// @public
+export type EventBatch = GetBatch | PostBatch;
+
 // @public (undocumented)
 export type EventMethod = "post" | "get" | "beacon";
 
@@ -234,6 +237,9 @@ export interface FlushBufferConfiguration {
     newBufferSize?: number;
 }
 
+// @public
+export type GetBatch = string[];
+
 // @public
 export function newSession(trackers?: Array<string>): void;
 
@@ -252,12 +258,23 @@ export interface PageViewEvent {
 // @public (undocumented)
 export type Platform = "web" | "mob" | "pc" | "srv" | "app" | "tv" | "cnsl" | "iot";
 
+// @public
+export type PostBatch = Record<string, unknown>[];
+
 // @public
 export function preservePageViewId(trackers?: Array<string>): void;
 
 // @public
 export function removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>, trackers?: Array<string>): void;
 
+// @public
+export type RequestFailure = {
+    events: EventBatch;
+    status?: number;
+    message?: string;
+    willRetry: boolean;
+};
+
 // @public
 export interface RuleSet {
     // (undocumented)
@@ -370,6 +387,8 @@ export type TrackerConfiguration = {
     onSessionUpdateCallback?: (updatedSession: ClientSession) => void;
     idService?: string;
     retryFailedRequests?: boolean;
+    onRequestSuccess?: (data: EventBatch) => void;
+    onRequestFailure?: (data: RequestFailure) => void;
 };
 
 // @public

common/changes/@snowplow/browser-tracker-core/issue-1275-fix-config-for-callbacks_2023-12-13-13-14.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker-core",
+      "comment": "Fix config for callbacks",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker-core"
+}

common/changes/@snowplow/browser-tracker/issue-1275-fix-config-for-callbacks_2023-12-13-14-30.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker",
+      "comment": "Update API docs for callbacks",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker"
+}

libraries/browser-tracker-core/src/tracker/index.ts

@@ -304,7 +304,9 @@ export function Tracker(
         trackerConfiguration.retryStatusCodes ?? [],
         (trackerConfiguration.dontRetryStatusCodes ?? []).concat([400, 401, 403, 410, 422]),
         trackerConfiguration.idService,
-        trackerConfiguration.retryFailedRequests
+        trackerConfiguration.retryFailedRequests,
+        trackerConfiguration.onRequestSuccess,
+        trackerConfiguration.onRequestFailure
       ),
       // Whether pageViewId should be regenerated after each trackPageView. Affect web_page context
       preservePageViewId = false,

libraries/browser-tracker-core/src/tracker/types.ts

@@ -232,6 +232,21 @@ export type TrackerConfiguration = {
    * @defaultValue true
    */
   retryFailedRequests?: boolean;
+  /**
+   * a callback function to be executed whenever a request is successfully sent to the collector.
+   * In practice this means any request which returns a 2xx status code will trigger this callback.
+   *
+   * @param data - The event batch that was successfully sent
+   */
+  onRequestSuccess?: (data: EventBatch) => void;
+
+  /**
+   * a callback function to be executed whenever a request fails to be sent to the collector.
+   * This is the inverse of the onRequestSuccess callback, so any non 2xx status code will trigger this callback.
+   *
+   * @param data - The data associated with the event(s) that failed to send
+   */
+  onRequestFailure?: (data: RequestFailure) => void;
 };
 
 /**

trackers/browser-tracker/src/index.ts

@@ -38,6 +38,10 @@ import {
   EventMethod,
   StateStorageStrategy,
   ClientSession,
+  RequestFailure,
+  EventBatch,
+  GetBatch,
+  PostBatch,
 } from '@snowplow/browser-tracker-core';
 import { version } from '@snowplow/tracker-core';
 
@@ -81,6 +85,10 @@ export {
   EventMethod,
   StateStorageStrategy,
   ClientSession,
+  RequestFailure,
+  EventBatch,
+  GetBatch,
+  PostBatch,
 };
 export { version };
 export * from './api';