@uxf/analytics 11.52.2 → 11.53.0

package/README.md

@@ -59,12 +59,21 @@ const isSet = isCookieConsentSet(
 
 This reads the consent from cookie and initializes the GTM dataLayer.
 
+```tsx
+import { GtmScript } from "@uxf/analytics/gtm";
+
+// in your head component (not directly in _app)
+<GtmScript gtmId="GTM-YOURID" />
+```
+
+#### or with hook
+
 ```tsx
 import { useGtmScript } from "@uxf/analytics/gtm";
 
 const gtmScript = useGtmScript("GTM-YOURID");
 
-// in your head component
+// in your head component (not directly in _app)
 <script dangerouslySetInnerHTML={{ __html: gtmScript }} />
 ```
 
@@ -84,4 +93,85 @@ updateGtmConsent(
     },
     1
 );
-```
+```
+
+## AB testing
+
+A set of components and helpers prepared to implement AB testing to React & NextJS applications.
+
+### How to start
+
+#### 1. Define your experiments
+
+```ts
+import type { ExperimentConfig } from "@uxf/analytics/ab-testing";
+
+const experiments = [
+    {
+        id: "1",
+        traffic: 1,
+        variants: [
+            { name: "Control", traffic: 0.5 },
+            { name: "B", traffic: 0.5 },
+        ],
+    },
+    {
+        id: "2",
+        traffic: 0.5,
+        variants: [
+            { name: "Control", traffic: 0.25 },
+            { name: "B", traffic: 0.75 },
+        ],
+    },
+] as const satisfies ExperimentConfig[];
+```
+
+#### 2. Use the `ABTestingProvider` component
+
+```tsx
+import { ABTestingProvider, AB_TESTING_VARIANT_PROP_NAME } from "@uxf/analytics/ab-testing";
+
+export default function App({ Component, pageProps }) {
+    return (
+        <ABTestingProvider experiments={props.pageProps[AB_TESTING_VARIANT_PROP_NAME]}>
+            <Component {...pageProps} />
+        </ABTestingProvider>
+    );
+}
+```
+
+#### 3. Handle AB testing in `middleware.ts`
+
+```ts
+import { handleABTesting } from "@uxf/analytics/ab-testing";
+
+export async function middleware(request: NextRequest) {
+    const nextResponse = NextResponse.next();
+
+    handleABTesting(request, nextResponse, experiments);
+
+    return nextResponse;
+}
+```
+
+#### 4. Implement SSR support in page with AB testing
+
+```tsx
+import { addExperimentsSSR } from "@uxf/analytics/ab-testing";
+
+export const getServerSideProps: GetServerSideProps = async (ctx) => {
+    return addExperimentsSSR(ctx, {
+        props: {},
+    });
+};
+```
+
+#### 5. Use the `useABTestingVariant` hook in your component
+
+```tsx
+import { useABTestingVariant } from "@uxf/analytics/ab-testing";
+
+const abTestingVariant = useABTestingVariant<typeof experiments>("1");
+
+console.log(abTestingVariant); // "Control", "B", etc.
+```

package/ab-testing/index.d.ts

@@ -0,0 +1,4 @@
+export * from "../src/ab-testing/ab-testing";
+export * from "../src/ab-testing/ab-testing-context";
+export * from "../src/ab-testing/constants";
+export type * from "../src/ab-testing/types";

package/ab-testing/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../src/ab-testing/ab-testing"), exports);
+__exportStar(require("../src/ab-testing/ab-testing-context"), exports);
+__exportStar(require("../src/ab-testing/constants"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/analytics",
-    "version": "11.52.2",
+    "version": "11.53.0",
     "description": "",
     "scripts": {
         "build": "tsc -P tsconfig.json",
@@ -15,7 +15,7 @@
     "author": "",
     "license": "ISC",
     "dependencies": {
-        "@uxf/core": "11.52.2"
+        "@uxf/core": "11.53.0"
     },
     "peerDependencies": {
         "react": ">=18.0.2"

package/src/ab-testing/ab-testing-context.d.ts

@@ -0,0 +1,10 @@
+import React, { type ReactNode } from "react";
+import type { ExperimentConfig } from "./types";
+interface Props {
+    experiments: [string, string][];
+    children: ReactNode;
+}
+export declare function ABTestingProvider(props: Props): React.JSX.Element;
+export declare function useABTesting(): [string, string][];
+export declare function useABTestingVariant<Config extends ExperimentConfig[]>(experimentId: Config[number]["id"]): Config[number]["variants"][number]["name"] | null;
+export {};

package/src/ab-testing/ab-testing-context.js

@@ -0,0 +1,48 @@
+"use strict";
+"use client";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ABTestingProvider = ABTestingProvider;
+exports.useABTesting = useABTesting;
+exports.useABTestingVariant = useABTestingVariant;
+const use_on_mount_1 = require("@uxf/core-react/hooks/use-on-mount");
+const react_1 = __importStar(require("react"));
+const ab_testing_1 = require("./ab-testing");
+const ABTestingContext = (0, react_1.createContext)([]);
+function ABTestingProvider(props) {
+    (0, use_on_mount_1.useOnMount)(() => {
+        (0, ab_testing_1.sendABTestingEvent)();
+    });
+    return react_1.default.createElement(ABTestingContext.Provider, { value: props.experiments }, props.children);
+}
+function useABTesting() {
+    return (0, react_1.useContext)(ABTestingContext);
+}
+function useABTestingVariant(experimentId) {
+    var _a;
+    const experiments = useABTesting();
+    const experiment = experiments.find(([name]) => name === experimentId);
+    return ((_a = experiment === null || experiment === void 0 ? void 0 : experiment.at(1)) !== null && _a !== void 0 ? _a : null);
+}

package/src/ab-testing/ab-testing.d.ts

@@ -0,0 +1,36 @@
+import type { ExperimentConfig, ExperimentVariant } from "./types";
+type NextRequest = {
+    cookies: {
+        get: (cookieName: string) => {
+            name: string;
+            value: string;
+        } | undefined;
+    };
+};
+type NextResponse = {
+    cookies: {
+        set: (cookie: {
+            name: string;
+            value: string;
+            maxAge: number;
+        }) => void;
+    };
+};
+type GetServerSidePropsContext = {
+    req: {
+        cookies: Partial<{
+            [key: string]: string;
+        }>;
+    };
+};
+type GetServerSidePropsResult<P> = {
+    props: P;
+};
+export declare function getExperimentVariant(config: ExperimentConfig, randomNumberForTesting?: number | null): ExperimentVariant | null;
+export declare function handleABTesting(request: NextRequest, response: NextResponse, experiments: ExperimentConfig[]): void;
+export declare function getExperimentsFromContext(cookies: Partial<{
+    [p: string]: string;
+}>): [string, string][];
+export declare function addExperimentsSSR<P>(ctx: GetServerSidePropsContext, pageProps: GetServerSidePropsResult<P>): GetServerSidePropsResult<P>;
+export declare function sendABTestingEvent(): void;
+export {};

package/src/ab-testing/ab-testing.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getExperimentVariant = getExperimentVariant;
+exports.handleABTesting = handleABTesting;
+exports.getExperimentsFromContext = getExperimentsFromContext;
+exports.addExperimentsSSR = addExperimentsSSR;
+exports.sendABTestingEvent = sendABTestingEvent;
+const is_not_nil_1 = require("@uxf/core/utils/is-not-nil");
+const gtm_event_1 = require("../gtm/gtm-event");
+const constants_1 = require("./constants");
+function getExperimentVariant(config, randomNumberForTesting = null) {
+    const randomNumber = randomNumberForTesting !== null && randomNumberForTesting !== void 0 ? randomNumberForTesting : Math.random();
+    const trafficWithoutABTesting = Math.fround(1 - config.traffic);
+    if (randomNumber <= trafficWithoutABTesting) {
+        return null;
+    }
+    let sumTraffic = trafficWithoutABTesting;
+    for (const variant of config.variants) {
+        sumTraffic += variant.traffic * config.traffic;
+        if (randomNumber <= sumTraffic) {
+            return variant;
+        }
+    }
+    return null;
+}
+function getCookieName(experimentId) {
+    return `${constants_1.EXPERIMENT_COOKIE_PREFIX}${experimentId}`;
+}
+function handleExperimentCookie(request, response, experimentConfig) {
+    var _a;
+    const cookieValue = request.cookies.get(getCookieName(experimentConfig.id));
+    if (cookieValue) {
+        return;
+    }
+    const experimentVariant = getExperimentVariant(experimentConfig);
+    response.cookies.set({
+        name: getCookieName(experimentConfig.id),
+        value: (_a = experimentVariant === null || experimentVariant === void 0 ? void 0 : experimentVariant.name) !== null && _a !== void 0 ? _a : "not-participate",
+        maxAge: 60 * 60 * 24 * 365, // 365 days
+    });
+}
+function handleABTesting(request, response, experiments) {
+    experiments.forEach((experimentConfig) => handleExperimentCookie(request, response, experimentConfig));
+}
+function getExperimentsFromContext(cookies) {
+    return Object.entries(cookies)
+        .filter(([cookieName]) => cookieName.startsWith(constants_1.EXPERIMENT_COOKIE_PREFIX))
+        .filter(([, cookieValue]) => (0, is_not_nil_1.isNotNil)(cookieValue))
+        .map(([cookieName, cookieValue]) => [cookieName.replace(constants_1.EXPERIMENT_COOKIE_PREFIX, ""), cookieValue]);
+}
+function addExperimentsSSR(ctx, pageProps) {
+    if (pageProps.props !== undefined) {
+        pageProps.props[constants_1.AB_TESTING_VARIANT_PROP_NAME] = getExperimentsFromContext(ctx.req.cookies);
+    }
+    return pageProps;
+}
+function sendABTestingEvent() {
+    if (typeof document === "undefined") {
+        // eslint-disable-next-line no-console
+        console.error("Document is undefined. This method can be called only on client.");
+        return;
+    }
+    if (typeof window.dataLayer === "undefined") {
+        // eslint-disable-next-line no-console
+        console.error("DataLayer is undefined. GTM must be implemented.");
+        return;
+    }
+    decodeURIComponent(document.cookie)
+        .split(";")
+        .map((cookie) => cookie.trim().split("="))
+        .map(([cookieName, cookieValue]) => ({ name: cookieName, value: cookieValue }))
+        .forEach((cookie) => {
+        if (cookie.name.startsWith(constants_1.EXPERIMENT_COOKIE_PREFIX) && typeof window !== "undefined") {
+            (0, gtm_event_1.gtmEvent)({
+                event: "experience_impression",
+                exp_variant_string: `${cookie.name}-${cookie.value}`,
+            });
+        }
+    });
+}

package/src/ab-testing/ab-testing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/src/ab-testing/ab-testing.test.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ab_testing_1 = require("./ab-testing");
+const A = { name: "A", traffic: 0.1 };
+const B = { name: "B", traffic: 0.3 };
+const C = { name: "C", traffic: 0.6 };
+const config = {
+    id: "experiment-1",
+    traffic: 0.8,
+    variants: [A, B, C],
+};
+/**
+ * 100% --- 20%                              | 0.20
+ *      \-- 80% --- 10% (0.8 * 0.1 = 0.08)   | 0.28
+ *              \-- 30% (0.8 * 0.3 = 0.24)   | 0.52
+ *               \- 60% (0.8 * 0.6 = 0.48)   | 0.100
+ */
+test("getExperimentVariant", () => {
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0)).toBe(null);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0.1)).toBe(null);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0.2)).toBe(null);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0.21)).toBe(A);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0.28)).toBe(A);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0.29)).toBe(B);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0.52)).toBe(B);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0.53)).toBe(C);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 0.99)).toBe(C);
+    expect((0, ab_testing_1.getExperimentVariant)(config, 1)).toBe(C);
+    // tohle by nemělo nastat
+    expect((0, ab_testing_1.getExperimentVariant)(config, 1.1)).toBe(null);
+});

package/src/ab-testing/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const EXPERIMENT_COOKIE_PREFIX = "uxf-experiment-";
+export declare const AB_TESTING_VARIANT_PROP_NAME = "__AB_TESTING_VARIANT__";

package/src/ab-testing/constants.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AB_TESTING_VARIANT_PROP_NAME = exports.EXPERIMENT_COOKIE_PREFIX = void 0;
+exports.EXPERIMENT_COOKIE_PREFIX = "uxf-experiment-";
+exports.AB_TESTING_VARIANT_PROP_NAME = "__AB_TESTING_VARIANT__";

package/src/ab-testing/types.d.ts

@@ -0,0 +1,10 @@
+export interface ExperimentVariant {
+    name: string;
+    traffic: number;
+    label?: string;
+}
+export interface ExperimentConfig {
+    id: string;
+    traffic: number;
+    variants: Array<ExperimentVariant>;
+}

package/src/ab-testing/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/gtm/gtm-event.d.ts

@@ -0,0 +1 @@
+export declare function gtmEvent(gtmEventData: any): void;

package/src/gtm/gtm-event.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gtmEvent = gtmEvent;
+function gtmEvent(gtmEventData) {
+    if (typeof window.dataLayer === "undefined") {
+        window.dataLayer = [];
+    }
+    window.dataLayer.push(gtmEventData);
+}

package/src/gtm/gtm-script.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+interface Props {
+    gtmId: string;
+}
+export declare function GtmScript(props: Props): React.JSX.Element;
+export {};

package/src/gtm/gtm-script.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GtmScript = GtmScript;
+const is_server_1 = require("@uxf/core/utils/is-server");
+const react_1 = __importDefault(require("react"));
+const use_gtm_script_1 = require("./use-gtm-script");
+function GtmScript(props) {
+    const gtmScript = (0, use_gtm_script_1.useGtmScript)(props.gtmId);
+    return react_1.default.createElement(react_1.default.Fragment, null, !is_server_1.isServer && react_1.default.createElement("script", { dangerouslySetInnerHTML: { __html: gtmScript } }));
+}