diff --git a/.github/workflows/deploy-playground.yml b/.github/workflows/deploy-playground.yml new file mode 100644 index 0000000..554475d --- /dev/null +++ b/.github/workflows/deploy-playground.yml @@ -0,0 +1,61 @@ +name: Deploy Playground to GitHub Pages + +on: + push: + branches: + - main + paths: + - "demo/**" + - "src/**" + - "package.json" + - "vite.config.*" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + deploy: + runs-on: ubuntu-22.04 + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Checkout + uses: actions/checkout@v6 + + - uses: pnpm/action-setup@v4 + name: Install PNPM + + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + cache: pnpm + node-version-file: package.json + registry-url: https://registry.npmjs.org + + - name: Install dependencies + run: pnpm install + + - name: Build + run: pnpm run build + + - name: Prepare pages artifact + run: | + mkdir -p _site/dist + cp demo/index.html _site/index.html + cp dist/ts.iife.js _site/dist/ts.iife.js + cp dist/ts.js _site/dist/ts.js + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index 9503bfd..e427171 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,10 @@ This tutorial will guide you through the process of integrating Topsort's Analytics.js library into your website to track events like impressions, clicks, and purchases. +## Playground + +Try the interactive playground at **https://topsort.github.io/analytics.js** — configure your token, add products, and see events fire in real time without any local setup. + ## 1. Introduction Topsort's `analytics.js` is a JavaScript library that allows you to automatically report user interaction events with products on your website to Topsort's Analytics service. This helps you understand how users are interacting with sponsored and organic listings. @@ -160,7 +164,18 @@ To track impressions for an organic product, add the `data-ts-product` attribute Clicks on organic products are tracked automatically when the product element has the `data-ts-product` attribute. If you need to specify which parts of the product element are clickable, you can use the `data-ts-clickable` attribute, just as you would for promoted products. -## 10. Troubleshooting +## 10. Local Development for playground + +To run the playground locally: + +```bash +npm install +npm run playground +``` + +This builds the library and serves the project. Open the URL shown in the terminal and navigate to `/demo/`. + +## 11. Troubleshooting ### "Uncaught Error: Mismatched anonymous define() module" diff --git a/biome.json b/biome.json index 6563750..6c08efc 100644 --- a/biome.json +++ b/biome.json @@ -2,7 +2,8 @@ "$schema": "./node_modules/@biomejs/biome/configuration_schema.json", "assist": { "actions": { "source": { "organizeImports": "on" } } }, "files": { - "ignoreUnknown": true + "ignoreUnknown": true, + "includes": ["**", "!demo"] }, "json": { "formatter": { diff --git a/demo/index.html b/demo/index.html new file mode 100644 index 0000000..4015d58 --- /dev/null +++ b/demo/index.html @@ -0,0 +1,887 @@ + + + + + + analytics.js Playground + + + +
+

analytics.js

+

Interactive Playground

+
+ +
+ + +
+
+

Live Preview

+
+
+ Elements with data-ts-* attributes + 0 +
+
+ Add elements using the form on the left. Impressions fire automatically when elements appear. Click on product cards to trigger click events. +
+
+
+ +
+

Event Log

+
+
+ Captured topsort CustomEvents + 0 +
+
+ Events will appear here as they are detected by analytics.js. +
+
+
+ +
+

Code Snippet

+
+
Copy & paste into your site
+
+ 

+            

+          

+        

+      

+    

+
+    
+  
+
diff --git a/package.json b/package.json
index cd4460a..93532a7 100644
--- a/package.json
+++ b/package.json
@@ -49,6 +49,7 @@
     "lint:ci": "biome ci",
     "test": "vitest run --coverage",
     "test:e2e": "vite build && vite build -c vite.config.browser-test.js && tsc && node dist/mocks/api-server.js",
+    "playground": "pnpm run build && npx serve .",
     "types:check": "tsc --noemit"
   },
   "author": "Topsort",