Merge pull request #6 from hyperse-io/feat/track

Feat/track

CONTRIBUTING.md

@@ -22,7 +22,7 @@ If you would like to contribute a bugfix, please first create an issue detailing
 
 Again, please create a feature request detailing the functionality you intend to add, and state that you would like to implement it. When creating commits, please follow the commit message format below. New feature pull requests should be made against the `minor` branch.
 
-When adding new public APIs to support your new feature, add a `@since 1.2.0` tag (where "1.2.0" corresponds to what will be the next minor version) to the doc block. This will let readers of the documentation know the version in which the API was introduced. See the [docs readme](./docs/README.md) for more details on the valid docs tags.
+When adding new public APIs to support your new feature, add a `@since 1.2.0` tag (where "1.2.0" corresponds to what will be the next minor version) to the doc block. This will let readers of the documentation know the version in which the API was introduced. See the [docs readme](./README.md) for more details on the valid docs tags.
 
 ```TypeScript
 /**

README.md

@@ -13,7 +13,7 @@
   <a aria-label="Top language" href="https://github.com/hyperse-io/track/search?l=typescript">
     <img alt="GitHub top language" src="https://img.shields.io/github/languages/top/hyperse-io/track?style=flat-square&labelColor=000&color=blue">
   </a>
-  <a aria-label="Licence" href="https://github.com/hyperse-io/track/blob/main/LICENSE">
+  <a aria-label="Licence" href="https://github.com/hyperse-io/track/blob/main/LICENSE.md">
     <img alt="Licence" src="https://img.shields.io/github/license/hyperse-io/track?style=flat-quare&labelColor=000000" />
   </a>
   <a aria-label="Discord" href="https://www.hyperse.net/community">
@@ -52,18 +52,72 @@ yarn add @hyperse/track
 ## Development
 
 > [!IMPORTANT]
-> The following instructions are for those who want to develop the hyperse related framework or plugins (e.g. if you intend to make a pull request). For instructions on how to build a project _using_ Hyperse, please see the [Getting Started guide](https://hyperse-io.github.io/track/docs/intro/installation).
+> The following instructions are for those who want to develop the hyperse related framework or plugins (e.g. if you intend to make a pull request). For instructions on how to build a project _using_ Hyperse, please see the [Getting Started guide](https://hyperse-io.github.io/track/docs/community/contributing).
+
+### 1. Clone project to the local directory
+
+```bash
+git clone https://github.com/hyperse-io/track.git
+```
+
+### 2. Install dependencies in the root directory
+
+```bash
+yarn install
+```
+
+or
+
+```bash
+npm install
+```
+
+The root directory has a `package.json` which contains build-related dependencies for tasks including:
+
+- Building & deploying the docs
+- Project for online presentation
+- Linting, formatting & testing tasks to run on git commit & push
+
+### 3. Testing
+
+Make sure to thoroughly test your changes before submitting them. This includes running unit tests, integration tests, and any other relevant testing methods to ensure code quality and functionality.
+
+The core and several other packages have unit tests which are can be run all together by running `npm run test` from the root directory, or individually by running it from the package directory.
+
+Unit tests are co-located with the files which they test, and have the suffix `.spec.ts`.
+
+### 4. Improve documentation
+
+Documentation is a critical part of any software project. To improve or update the documentation:
+
+1. Update Documentation Files: If your changes introduce new features, modify existing functionality, or fix bugs, update the relevant documentation files located in the /website directory.
+
+2. Build and Preview: Ensure that your documentation builds correctly and looks good by running:
+
+```bash
+cd website
+
+npm run start
+```
+
+3. Commit Documentation Changes: Make sure all updates to documentation are committed alongside your code changes.
+
+### 5. Release Process
+
+To make a release:
+
+1. Commit the Changes: Push your updated files to your branch.
+
+2. Create a Pull Request: [Open a pull request (PR)](https://github.com/hyperse-io/track/compare) with your changes. Make sure to include a clear description of what has been updated and why.
+
+3. GitHub Actions: Once the PR is merged into the main branch, the release process will be automatically handled by GitHub Actions. This includes tasks such as publishing to npm and updating documentation.
 
 ## Documentation
 
 You can find the Track documentation [on the website](https://hyperse-io.github.io/track/).
 
 Check out the [Sample Example](https://hyperse-io.github.io/track/docs/intro/sample-example) page for a quick start.
 
-## Contributing
-
-Contributions are welcome! If you encounter any issues or have ideas for improvements, feel free to open an issue or submit a pull request.
-
 ## License
 
-Code released under [Track LICENSE](https://github.com/hyperse-io/track/blob/main/LICENSE)
+See [LICENSE](https://github.com/hyperse-io/track/blob/main/LICENSE.md)

examples/next-example/app/globals.css

@@ -24,4 +24,50 @@ body {
       rgb(var(--background-end-rgb))
     )
     rgb(var(--background-start-rgb));
+  margin: unset;
+}
+
+#modal{
+  z-index: 999;
+  height: 50%;
+  width: 100vw;
+  background-color: white;
+  position: fixed;
+  bottom: 0px;
+  padding: 12px;
+  color:black;
+  font-size: 16px;
+  padding: 10px;
+}
+
+#pre{
+  overflow-y: auto;
+  height: 100%;
+  padding-bottom: 10px;
+  padding: 0 24px;
+}
+
+#head{
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 10px;
+  border-bottom: 1px solid #ccc;
+}
+
+#title{
+  font-size: 20px;
+  width: 100%;
+  text-align: center;
+}
+
+#close{
+  width: 24px;
+  height: 24px;
+  cursor: pointer;
+  border-radius: 2px;
+  background-color: #ccc;
+  text-align: center;
+  position: absolute;
+  right: 24px;
 }

examples/next-example/app/page.tsx

@@ -1,28 +1,63 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { fetchGoodsList, GoodsRecord } from './service';
+import mockjs from 'mockjs';
+import { reportTrack } from '@/track/track';
+import { GoodsRecord } from '@/track/types';
+import { fetchGoodsList } from './service';
 
 export default function Home() {
   const [mounted, setMounted] = useState(false);
+  const [text, setText] = useState<string>();
+  const [data] = useState<GoodsRecord[]>(fetchGoodsList());
 
   useEffect(() => {
     setMounted(true);
   }, []);
+
+  useEffect(() => {
+    const listener = (event: MessageEvent) => {
+      const { data } = event;
+      if (data && data.type === 'report') {
+        setText(`${JSON.stringify(data.data, null, 2)}`);
+      }
+    };
+
+    window.addEventListener('message', listener);
+    return () => {
+      window.removeEventListener('message', listener);
+    };
+  }, [mounted]);
+
+  useEffect(() => {
+    if (!mounted) {
+      return;
+    }
+    reportTrack()
+      .select('reportAdapter')
+      .track(
+        'pv',
+        mockjs.mock({
+          timeStamp: Date.now(),
+          url: '@url()',
+          userName: '@name()',
+          userId: '@id(12)',
+        })
+      );
+  }, [mounted]);
+
   const onAddToCart = (item: GoodsRecord) => {
-    console.log('onAddToCart', JSON.stringify(item));
-    // await reportTrack().select('reportAdapter').track('addCart', {
-    //   price: 25.99,
-    //   goodsId: '23432252',
-    //   goodsName: 'Long Chair',
-    //   count: 1,
-    // });
+    reportTrack()
+      .select('reportAdapter')
+      .track('addCart', {
+        ...item,
+      });
   };
 
   return (
     <main className="flex min-h-screen flex-col items-center justify-between gap-4">
       {mounted &&
-        fetchGoodsList().map((item, index: number) => {
+        data.map((item, index: number) => {
           return (
             <div
               key={index}
@@ -49,6 +84,20 @@ export default function Home() {
             </div>
           );
         })}
+
+      <div id="modal" style={{ display: text ? 'block' : 'none' }}>
+        <div id="head">
+          <div id="title">Report Data</div>
+          <div id="close" onClick={() => setText(undefined)}>
+            x
+          </div>
+        </div>
+        <div id="pre">
+          <pre>
+            <code>{text}</code>
+          </pre>
+        </div>
+      </div>
     </main>
   );
 }

examples/next-example/app/service.ts

@@ -1,16 +1,11 @@
 import Mock from 'mockjs';
-
-export interface GoodsRecord {
-  goodsName: string;
-  goodsId: string;
-  price: number;
-}
+import { GoodsRecord } from '@/track/types';
 
 export const fetchGoodsList = (): GoodsRecord[] => {
   const data = Mock.mock({
     'list|10-20': [
       {
-        goodsName: '@cword(3,5)',
+        goodsName: '@word(3,5)',
         goodsId: '@id()',
         price: '@float(10, 100, 2, 2)',
       },

examples/next-example/package.json

@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@hyperse/track": "latest",
+    "@hyperse/track": "1.0.2",
     "@types/node": "20.6.2",
     "@types/react": "18.2.22",
     "@types/react-dom": "18.2.7",

examples/next-example/track/report-adapter.ts

@@ -0,0 +1,37 @@
+import { AdapterReportData, BaseAdapter, TrackContext } from '@hyperse/track';
+import {
+  ReportAdapterOptions,
+  ReportEventData,
+  ReportTrackData,
+} from './types';
+
+export class ReportAdapter extends BaseAdapter<
+  TrackContext<ReportTrackData>,
+  ReportEventData,
+  ReportAdapterOptions<TrackContext<ReportTrackData>, ReportEventData>
+> {
+  isTrackable<EventType extends keyof ReportEventData>(
+    ctx: TrackContext<ReportTrackData>,
+    eventType: EventType,
+    eventData: ReportEventData[EventType]
+  ): boolean | Promise<boolean> {
+    return true;
+  }
+
+  protected report(
+    ctx: TrackContext<ReportTrackData>,
+    reportData: AdapterReportData,
+    setupData?:
+      | { name: 'setup' | 'setup2' | 'setup3'; timeStamp: number }
+      | undefined
+  ): void | Promise<void> {
+    window.postMessage({
+      type: 'report',
+      data: {
+        ctx,
+        reportData,
+        setupData,
+      },
+    });
+  }
+}

examples/next-example/track/track.ts

@@ -1 +1,77 @@
-export const reportTrack = () => {};
+import {
+  createAdapterBuilder,
+  createTrackBuilder,
+  TrackContext,
+} from '@hyperse/track';
+import { ReportAdapter } from './report-adapter';
+import {
+  ReportAdapterOptions,
+  ReportEventData,
+  ReportTrackData,
+} from './types';
+
+export const reportTrack = () => {
+  const reportAdapter = new ReportAdapter();
+
+  const adapterBuilder = createAdapterBuilder<
+    TrackContext<ReportTrackData>,
+    ReportEventData,
+    ReportAdapterOptions<TrackContext<ReportTrackData>, ReportEventData>
+  >(reportAdapter);
+
+  const adapter = adapterBuilder
+    .setup(() => {
+      return Promise.resolve({
+        name: 'setup',
+        timeStamp: Date.now(),
+      });
+    })
+    .before((ctx, eventType, eventData) => {
+      console.log('before', ctx, eventType, eventData);
+    })
+    .transform('addCart', (ctx, eventType, eventData) => {
+      return {
+        eventType,
+        goodName: 'ac_' + eventData?.goodsName,
+        goodsId: 'ac_' + eventData?.goodsId,
+        price: eventData?.price,
+      };
+    })
+    .transform('pv', (ctx, eventType, eventData) => {
+      return {
+        eventType,
+        url: eventData?.url,
+        timeStamp: 'pv_' + eventData?.timeStamp,
+        userName: 'pv_' + eventData?.userName,
+        userId: 'pv_' + eventData?.userId,
+      };
+    })
+    .after((ctx, eventType, reportData) => {
+      console.log('after', ctx, eventType, reportData);
+    })
+    .build();
+
+  const trackBuilder = createTrackBuilder<
+    TrackContext<ReportTrackData>,
+    ReportEventData
+  >({
+    createData: {
+      env: 'prod',
+      platform: 'ios',
+      ip: '0.0.0.0',
+    },
+  });
+
+  return trackBuilder
+    .init(() => {
+      return {
+        reportAdapter: adapter,
+      };
+    })
+    .before((ctx) => {
+      console.log('before track', ctx);
+    })
+    .after((ctx) => {
+      console.log('after track', ctx);
+    });
+};