@formo/analytics 1.11.5-alpha.4 → 1.11.6-alpha.0

package/README.md

@@ -4,17 +4,16 @@
 
 ---
 
-Add the following to your `index.html`:
+Add the following to your page:
 
 ```html
 <script>
   const script = document.createElement('script');
   const apiKey = 'YOUR_API_KEY';
-  const projectId = 'YOUR_PROJECT_ID';
 
   script.src = 'https://unpkg.com/@formo/analytics';
   script.onload = function () {
-    FormoAnalytics.init(apiKey, projectId)
+    FormoAnalytics.init(apiKey)
       .then((sdkInstance) => {
         window.formo = sdkInstance;
 
@@ -33,21 +32,96 @@ Add the following to your `index.html`:
 
 ---
 
-### 1. Install the npm package:
+### React Application
 
-Install @formo/analytics via yarn or npm:
+**1. Install the SDK**
+Install the Formo Analytics SDK using Yarn or NPM:
 
-```
+```jsx
 yarn add @formo/analytics
 ```
 
 or
 
+```jsx
+npm install @formo/analytics --save
+```
+
+**2. Set up FormoAnalyticsProvider in Your Application**
+
+Wrap your entire React application in the `FormoAnalyticsProvider` provided by the SDK.
+
+```jsx 
+//App.tsx (or App.js)
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { FormoAnalyticsProvider } from '@formo/analytics';
+import App from './App';
+
+const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
+
+root.render(
+  <React.StrictMode>
+    <FormoAnalyticsProvider apiKey="YOUR_API_KEY">
+      <App />
+    </FormoAnalyticsProvider>
+  </React.StrictMode>
+);
 ```
+
+**3. Tracking Events**
+
+You can use the `useFormoAnalytics` hook from the SDK to track user interactions.
+
+Example: Tracking a Custom Event
+
+```jsx
+import React, { useEffect } from 'react';
+import { useFormoAnalytics } from '@formo/analytics';
+
+const HomePage = () => {
+  const analytics = useFormoAnalytics();
+
+  useEffect(() => {
+    // Track a custom event
+    analytics.track('custom_event', { key: 'value' });
+  }, [analytics]);
+
+  return <div>Welcome to the Home Page!</div>;
+};
+
+export default HomePage;
+```
+
+**4. Folder Structure Example**
+
+```
+/src
+ ├── /components
+ │    └── HomePage.tsx
+ ├── /App.tsx
+ └── /index.tsx (or index.js)
+```
+
+---
+
+### Next.js Application
+
+**1. Install the npm package:**
+
+Install `@formo/analytics` via yarn or npm:
+
+```jsx
+yarn add @formo/analytics
+```
+
+or
+
+```jsx
 npm install @formo/analytics --save
 ```
 
-### 2. Set up the `FormoAnalyticsProvider` in your application:
+**2. Set up the `FormoAnalyticsProvider` in your application:**
 
 ```jsx
 // AnalyticsProvider.tsx
@@ -59,44 +133,16 @@ import React, { FC, useEffect } from 'react';
 
 type FormoAnalyticsProviderProps = {
   apiKey: string,
-  projectId: string,
   children: React.ReactNode,
 };
 
 // The provider component
 export const AnalyticsProvider: FC<FormoAnalyticsProviderProps> = ({
   apiKey,
-  projectId,
   children,
 }) => {
-  // Initialize the FormoAnalytics SDK inside useEffect
-  const [isInitialized, setIsInitialized] = useState(false);
-
-  useEffect(() => {
-    const initialize = async () => {
-      try {
-        await FormoAnalytics.init(apiKey, projectId);
-        console.log('FormoAnalytics SDK initialized');
-        setIsInitialized(true);
-      } catch (error) {
-        console.error('Failed to initialize FormoAnalytics SDK', error);
-      }
-    };
-
-    initialize();
-  }, [apiKey, projectId]);
-
-  // To prevent app crashes, render a loading state during initialization
-  if (!isInitialized) {
-    return (
-      <FormoAnalyticsProvider apiKey={apiKey} projectId={projectId}>
-        Loading Content
-      </FormoAnalyticsProvider>
-    );
-  }
-
   return (
-    <FormoAnalyticsProvider apiKey={apiKey} projectId={projectId}>
+    <FormoAnalyticsProvider apiKey={apiKey}>
       {children}
     </FormoAnalyticsProvider>
   );
@@ -105,7 +151,7 @@ export const AnalyticsProvider: FC<FormoAnalyticsProviderProps> = ({
 export default AnalyticsProvider;
 ```
 
-### 3. Integrating the Provider in Your Root Layout
+**3. Integrating the Provider in Your Root Layout**
 
 Wrap your application with the newly created `AnalyticsProvider` in your main layout file:
 
@@ -120,7 +166,7 @@ export default function RootLayout({
   return (
     <html lang='en'>
       <body>
-        <AnalyticsProvider apiKey='YOUR_API_KEY' projectId='YOUR_PROJECT_ID'>
+        <AnalyticsProvider apiKey='YOUR_API_KEY'>
           Your Page Content
         </AnalyticsProvider>
       </body>
@@ -129,7 +175,7 @@ export default function RootLayout({
 }
 ```
 
-### 4. Using the SDK
+**4. Using the SDK**
 
 Once the SDK is initialized, you can use its methods to track events and user interactions. Here’s how to do that:
 
@@ -143,11 +189,9 @@ const YourComponent = () => {
   useEffect(() => {
     const track = async () => {
       try {
-        console.log('Tracking page hit...');
-        analytics.page(); // Track the page view
         analytics.track('custom_event', { key: 'value' }); // Track a custom event
       } catch (error) {
-        console.error('Failed to track page hit', error);
+        console.error('Failed to track event', error);
       }
     };
 
@@ -158,10 +202,54 @@ const YourComponent = () => {
 };
 ```
 
-# Development notes
+# Development Notes
+
+If you want to contribute or run a local version of the Formo Analytics SDK, follow these steps:
+
+1. Build the SDK Locally
+
+Run the following command to build both CommonJS and ESM versions of the SDK:
+
+```jsx
+yarn build-cjs && yarn build-esm && yarn webpack --mode=production
+```
+
+or if you're using NPM:
+
+```jsx
+npm run build
+```
+
+2. Authenticate with NPM
+
+To publish a new version of the package, log in to your NPM account:
+
+```jsx
+npm login
+```
+
+or:
+
+```jsx
+npm adduser
+```
+
+3. Publish the Package
+
+Run the following command to publish the package to NPM:
+
+```jsx
+yarn publish
+```
+
+or:
+
+```jsx
+npm run publish
+```
 
-To run a local version of the script:
+# Troubleshooting
 
-1. Run `yarn build-cjs && yarn build-esm && yarn webpack --mode=production` or `npm run build` at the root level to build the script.
-2. To authorize device, login into npmjs using `npm login` or `npm adduser`
-3. Run `yarn publish` or `npm run publish` to publish new versions of the package.
+**API Key Not Provided:** Ensure you pass a valid apiKey when initializing the SDK.
+**SDK Not Initialized:** If you encounter issues with initialization, check the console logs for errors and ensure the project ID and API key are correct.
+**Network Errors:** Verify that the analytics service URL is accessible from your network.

package/dist/cjs/src/FormoAnalytics.d.ts

@@ -1,28 +1,91 @@
+import { ChainID, EIP1193Provider, Options } from './types';
 interface IFormoAnalytics {
-    init(apiKey: string, projectId: string): Promise<FormoAnalytics>;
-    identify(userData: any): void;
+    /**
+     * Initializes the FormoAnalytics instance with the provided API key and project ID.
+     */
+    init(apiKey: string, options: Options): Promise<FormoAnalytics>;
+    /**
+     * Tracks page visit events.
+     */
     page(): void;
-    track(eventName: string, eventData: any): void;
+    /**
+     * Connects to a wallet with the specified chain ID and address.
+     */
+    connect(params: {
+        chainId: ChainID;
+        address: string;
+    }): Promise<void>;
+    /**
+     * Disconnects the current wallet and clears the session information.
+     */
+    disconnect(params?: {
+        chainId?: ChainID;
+        address?: string;
+    }): void;
+    /**
+     * Switches the blockchain chain context and optionally logs additional params.
+     */
+    chain(params: {
+        chainId: ChainID;
+        address?: string;
+    }): void;
+    /**
+     * Tracks a specific event with a name and associated data.
+     */
+    track(eventName: string, eventData: Record<string, any>): void;
 }
 export declare class FormoAnalytics implements IFormoAnalytics {
     readonly apiKey: string;
-    projectId: string;
+    options: Options;
+    private _provider?;
+    private _registeredProviderListeners;
+    private walletAddressSessionKey;
     private config;
     private sessionIdKey;
     private timezoneToCountry;
+    currentChainId?: string | null;
+    currentConnectedAddress?: string;
     private constructor();
-    static init(apiKey: string, projectId: string): Promise<FormoAnalytics>;
-    private identifyUser;
+    static init(apiKey: string, options: Options): Promise<FormoAnalytics>;
+    get provider(): EIP1193Provider | undefined;
     private getSessionId;
+    private getOrigin;
     private setSessionCookie;
     private generateSessionId;
     private getCookieValue;
     private trackEvent;
-    private maskSensitiveData;
     private trackPageHit;
-    private buildApiUrl;
-    init(apiKey: string, projectId: string): Promise<FormoAnalytics>;
-    identify(userData: any): void;
+    private trackProvider;
+    private getCurrentWallet;
+    private getCurrentChainId;
+    private registerAddressChangedListener;
+    private registerChainChangedListener;
+    private onAddressChanged;
+    private onAddressConnected;
+    private onAddressDisconnected;
+    private onChainChanged;
+    /**
+     * Stores the wallet address in session storage when connected.
+     * @param address - The wallet address to store.
+     */
+    private storeWalletAddress;
+    /**
+     * Clears the wallet address from session storage when disconnected.
+     */
+    private clearWalletAddress;
+    init(apiKey: string, options: Options): Promise<FormoAnalytics>;
+    connect({ chainId, address }: {
+        chainId: ChainID;
+        address: string;
+    }): Promise<void>;
+    disconnect(params?: {
+        chainId?: ChainID;
+        address?: string;
+    }): Promise<void> | undefined;
+    chain({ chainId, address }: {
+        chainId: ChainID;
+        address?: string;
+    }): Promise<void>;
     page(): void;
     track(eventName: string, eventData: any): void;
 }

package/dist/cjs/src/FormoAnalytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FormoAnalytics.d.ts","sourceRoot":"","sources":["../../../src/FormoAnalytics.ts"],"names":[],"mappings":"AAKA,UAAU,eAAe;IACvB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,QAAQ,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAC;IAC9B,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC;CAChD;AACD,qBAAa,cAAe,YAAW,eAAe;aAMlC,MAAM,EAAE,MAAM;IACvB,SAAS,EAAE,MAAM;IAN1B,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,iBAAiB,CAAwC;IAEjE,OAAO;WASM,IAAI,CACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC;IAU1B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,cAAc;YAUR,UAAU;IAyDxB,OAAO,CAAC,iBAAiB;IAkEzB,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,WAAW;IAiBnB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAMhE,QAAQ,CAAC,QAAQ,EAAE,GAAG;IAItB,IAAI;IAIJ,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG;CAGxC"}
+{"version":3,"file":"FormoAnalytics.d.ts","sourceRoot":"","sources":["../../../src/FormoAnalytics.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAE5D,UAAU,eAAe;IACvB;;OAEG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEhE;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtE;;OAEG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAEnE;;OAEG;IACH,KAAK,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAE5D;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;CAChE;AAID,qBAAa,cAAe,YAAW,eAAe;aAgBlC,MAAM,EAAE,MAAM;IACvB,OAAO,EAAE,OAAO;IAhBzB,OAAO,CAAC,SAAS,CAAC,CAAkB;IACpC,OAAO,CAAC,4BAA4B,CAG7B;IAEP,OAAO,CAAC,uBAAuB,CAAmB;IAClD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,iBAAiB,CAAwC;IAEjE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC,OAAO;WAeM,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAU5E,IAAI,QAAQ,IAAI,eAAe,GAAG,SAAS,CAE1C;IAED,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,cAAc;YAUR,UAAU;IA+DxB,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,aAAa;YA0BP,gBAAgB;YAwBhB,iBAAiB;IAiB/B,OAAO,CAAC,8BAA8B;IAYtC,OAAO,CAAC,4BAA4B;YAOtB,gBAAgB;YAWhB,kBAAkB;IAchC,OAAO,CAAC,qBAAqB;YAgBf,cAAc;IA4C5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAI1B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAK/D,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAiBnE,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAkB3D,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAuBlE,IAAI;IAIJ,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG;CAGxC"}