@pageflock/analytics 0.0.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,7 +10,7 @@ The script tag still works on its own (see [`@pageflock/tracker`](https://www.np
10
10
  npm install @pageflock/analytics
11
11
  ```
12
12
 
13
- You need a site ID from the Pageflock dashboard and the URL of your ingest Worker's collect endpoint, `https://YOUR-PAGEFLOCK-INGEST/api/e`.
13
+ You need a site ID from the Pageflock dashboard. Events go to Pageflock's hosted ingest, `https://e.pageflock.com/api/e`, unless you set `endpoint` (see [Self-hosting](#self-hosting)).
14
14
 
15
15
  ## Next.js
16
16
 
@@ -28,10 +28,7 @@ export default function RootLayout({
28
28
  <html lang="en">
29
29
  <body>
30
30
  {children}
31
- <Analytics
32
- site="SITE_ID"
33
- endpoint="https://YOUR-PAGEFLOCK-INGEST/api/e"
34
- />
31
+ <Analytics site="SITE_ID" />
35
32
  </body>
36
33
  </html>
37
34
  );
@@ -48,7 +45,7 @@ import { Analytics } from "@pageflock/analytics/react";
48
45
  export const App = () => (
49
46
  <>
50
47
  <Routes />
51
- <Analytics site="SITE_ID" endpoint="https://YOUR-PAGEFLOCK-INGEST/api/e" />
48
+ <Analytics site="SITE_ID" />
52
49
  </>
53
50
  );
54
51
  ```
@@ -65,7 +62,7 @@ import { Analytics } from "@pageflock/analytics/vue";
65
62
  </script>
66
63
 
67
64
  <template>
68
- <Analytics site="SITE_ID" endpoint="https://YOUR-PAGEFLOCK-INGEST/api/e" />
65
+ <Analytics site="SITE_ID" />
69
66
  <RouterView />
70
67
  </template>
71
68
  ```
@@ -79,7 +76,7 @@ import { Analytics } from "@pageflock/analytics/vue";
79
76
  import { inject } from "@pageflock/analytics";
80
77
  import { dev } from "$app/environment";
81
78
 
82
- inject({ site: "SITE_ID", endpoint: "https://YOUR-PAGEFLOCK-INGEST/api/e", debug: dev });
79
+ inject({ site: "SITE_ID", debug: dev });
83
80
 
84
81
  let { children } = $props();
85
82
  </script>
@@ -95,7 +92,7 @@ Astro bundles `<script>` tags, so add this to your base layout:
95
92
  <script>
96
93
  import { inject } from "@pageflock/analytics";
97
94
 
98
- inject({ site: "SITE_ID", endpoint: "https://YOUR-PAGEFLOCK-INGEST/api/e" });
95
+ inject({ site: "SITE_ID" });
99
96
  </script>
100
97
  ```
101
98
 
@@ -104,7 +101,7 @@ Astro bundles `<script>` tags, so add this to your base layout:
104
101
  ```ts
105
102
  import { inject } from "@pageflock/analytics";
106
103
 
107
- inject({ site: "SITE_ID", endpoint: "https://YOUR-PAGEFLOCK-INGEST/api/e" });
104
+ inject({ site: "SITE_ID" });
108
105
  ```
109
106
 
110
107
  ## Custom events
@@ -126,7 +123,7 @@ No-code events work too: `<button data-track="Signup" data-track-plan="pro">`.
126
123
  | Option | Type | Default | What it does |
127
124
  | --- | --- | --- | --- |
128
125
  | `site` | `string` | required | The site ID from the Pageflock dashboard. |
129
- | `endpoint` | `string` | required | The collect endpoint, `https://YOUR-PAGEFLOCK-INGEST/api/e`. |
126
+ | `endpoint` | `string` | `https://e.pageflock.com/api/e` | The collect endpoint. Only set it when you self-host. |
130
127
  | `autoEvents` | `boolean` | `false` | Also track outbound link clicks, file downloads and 404 pages, like `s.auto.js`. |
131
128
  | `hashRouting` | `boolean` | `false` | Count `#hash` changes as page views, for hash-routed apps. |
132
129
  | `beforeSend` | `(event: AnalyticsEvent) => AnalyticsEvent \| null` | none | Change an event before it is sent, or return `null` to drop it. |
@@ -134,14 +131,27 @@ No-code events work too: `<button data-track="Signup" data-track-plan="pro">`.
134
131
 
135
132
  `site`, `endpoint`, `autoEvents` and `hashRouting` are read when tracking starts. `beforeSend` and `debug` can change on later renders.
136
133
 
134
+ ### Self-hosting
135
+
136
+ Running your own Pageflock? Point `endpoint` at your ingest Worker's collect endpoint:
137
+
138
+ ```tsx
139
+ <Analytics site="SITE_ID" endpoint="https://YOUR-PAGEFLOCK-INGEST/api/e" />
140
+ ```
141
+
142
+ The install screen in your own dashboard fills this in for you.
143
+
144
+ ### Content Security Policy
145
+
146
+ If your site sets a Content Security Policy, allow the endpoint in `connect-src`, for example `connect-src 'self' https://e.pageflock.com`. The package is bundled into your code, so `script-src` needs nothing new.
147
+
137
148
  ### beforeSend
138
149
 
139
- Every event, page views included, passes through `beforeSend` as `{ name, url, props }`. Page views are named `pageview`, and time on page is sent as `engagement`.
150
+ Every event, page views included, passes through `beforeSend` as `{ name, url, props }`. Page views are named `pageview`, and time on page and scroll depth are sent as `engagement`.
140
151
 
141
152
  ```tsx
142
153
  <Analytics
143
154
  site="SITE_ID"
144
- endpoint="https://YOUR-PAGEFLOCK-INGEST/api/e"
145
155
  beforeSend={(event) => {
146
156
  if (new URL(event.url).pathname.startsWith("/admin")) {
147
157
  return null;
@@ -158,7 +168,3 @@ Every event, page views included, passes through `beforeSend` as `{ name, url, p
158
168
  Like the script, the package sends nothing on `localhost`, from `file:` pages or in automated browsers, and it waits until a prerendered page is shown. Turn on `debug` to see what would be sent. It uses no cookies, no `localStorage` or `sessionStorage`, and no fingerprinting APIs.
159
169
 
160
170
  Each entry bundles the tracker core, so the package has no runtime dependencies. React and Vue are optional peer dependencies.
161
-
162
- ## Licence
163
-
164
- MIT, unlike the rest of the Pageflock repository, so it can ship in any site.
@@ -38,6 +38,13 @@ var createTracker = (options) => {
38
38
  let lastUrl;
39
39
  let visibleSince = Date.now();
40
40
  let engaged = 0;
41
+ let depth = 0;
42
+ const measureDepth = () => {
43
+ depth = Math.max(
44
+ depth,
45
+ (scrollY + innerHeight) / document.documentElement.scrollHeight
46
+ );
47
+ };
41
48
  const send = (eventName, eventProps, extra) => {
42
49
  let name = eventName;
43
50
  let url = lastUrl ?? location.href;
@@ -70,10 +77,12 @@ var createTracker = (options) => {
70
77
  engaged += Date.now() - visibleSince;
71
78
  }
72
79
  visibleSince = Date.now();
80
+ measureDepth();
73
81
  if (lastUrl && engaged > 0) {
74
- send("engagement", void 0, { e: engaged });
82
+ send("engagement", void 0, { e: engaged, d: depth });
75
83
  }
76
84
  engaged = 0;
85
+ depth = 0;
77
86
  };
78
87
  const pageview = () => {
79
88
  const url = hashRouting ? location.href : location.href.split("#")[0];
@@ -103,6 +112,7 @@ var createTracker = (options) => {
103
112
  }
104
113
  });
105
114
  addEventListener("pagehide", flushEngagement);
115
+ addEventListener("scroll", measureDepth, { passive: true });
106
116
  document.addEventListener("click", (event) => {
107
117
  const element = event.target?.closest?.(
108
118
  "[data-track]"
@@ -114,8 +124,13 @@ var createTracker = (options) => {
114
124
  });
115
125
  return { track: (name, props) => send(name, props), pageview };
116
126
  };
117
- var init = ({ autoEvents, ...options }) => {
118
- const tracker = createTracker(options);
127
+ var DEFAULT_ENDPOINT = "https://e.pageflock.com/api/e";
128
+ var init = ({
129
+ autoEvents,
130
+ endpoint = DEFAULT_ENDPOINT,
131
+ ...options
132
+ }) => {
133
+ const tracker = createTracker({ ...options, endpoint });
119
134
  tracker.pageview();
120
135
  if (autoEvents) {
121
136
  installAutoEvents(tracker);
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  inject
3
- } from "./chunk-7JF7P3VW.js";
3
+ } from "./chunk-6IXYXMX6.js";
4
4
 
5
5
  // src/react.ts
6
6
  import { useEffect } from "react";
package/dist/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  inject,
3
3
  track
4
- } from "./chunks/chunk-7JF7P3VW.js";
4
+ } from "./chunks/chunk-6IXYXMX6.js";
5
5
  export {
6
6
  inject,
7
7
  track
package/dist/next.js CHANGED
@@ -1,10 +1,10 @@
1
1
  "use client";
2
2
  import {
3
3
  Analytics
4
- } from "./chunks/chunk-4ZAVKYVM.js";
4
+ } from "./chunks/chunk-AYI42IVX.js";
5
5
  import {
6
6
  track
7
- } from "./chunks/chunk-7JF7P3VW.js";
7
+ } from "./chunks/chunk-6IXYXMX6.js";
8
8
  export {
9
9
  Analytics,
10
10
  track
package/dist/react.js CHANGED
@@ -1,10 +1,10 @@
1
1
  "use client";
2
2
  import {
3
3
  Analytics
4
- } from "./chunks/chunk-4ZAVKYVM.js";
4
+ } from "./chunks/chunk-AYI42IVX.js";
5
5
  import {
6
6
  track
7
- } from "./chunks/chunk-7JF7P3VW.js";
7
+ } from "./chunks/chunk-6IXYXMX6.js";
8
8
  export {
9
9
  Analytics,
10
10
  track
@@ -9,8 +9,12 @@ export interface AnalyticsEvent {
9
9
  export interface AnalyticsOptions {
10
10
  /** The site ID from the Pageflock dashboard. */
11
11
  site: string;
12
- /** Full URL of the collect endpoint, for example https://pageflock.example.com/api/e. */
13
- endpoint: string;
12
+ /**
13
+ * Full URL of the collect endpoint. Leave it out to send to Pageflock's
14
+ * hosted ingest (https://e.pageflock.com/api/e); set it when you self-host,
15
+ * for example https://pageflock.example.com/api/e.
16
+ */
17
+ endpoint?: string;
14
18
  /** Also track outbound link clicks, file downloads and 404 pages. */
15
19
  autoEvents?: boolean;
16
20
  /** Count changes of `location.hash` as page views. */
@@ -3,7 +3,7 @@
3
3
  * layout (`app/layout.tsx`) or `pages/_app.tsx`:
4
4
  *
5
5
  * import { Analytics } from "@pageflock/analytics/next";
6
- * <Analytics site="SITE_ID" endpoint="https://pageflock.example.com/api/e" />
6
+ * <Analytics site="SITE_ID" />
7
7
  *
8
8
  * Client navigations go through `history.pushState`, which the tracker
9
9
  * already follows, so no router hooks are needed.
@@ -8,10 +8,7 @@ export declare const Analytics: import("vue").DefineComponent<import("vue").Extr
8
8
  type: StringConstructor;
9
9
  required: true;
10
10
  };
11
- endpoint: {
12
- type: StringConstructor;
13
- required: true;
14
- };
11
+ endpoint: StringConstructor;
15
12
  autoEvents: BooleanConstructor;
16
13
  hashRouting: BooleanConstructor;
17
14
  debug: BooleanConstructor;
@@ -21,10 +18,7 @@ export declare const Analytics: import("vue").DefineComponent<import("vue").Extr
21
18
  type: StringConstructor;
22
19
  required: true;
23
20
  };
24
- endpoint: {
25
- type: StringConstructor;
26
- required: true;
27
- };
21
+ endpoint: StringConstructor;
28
22
  autoEvents: BooleanConstructor;
29
23
  hashRouting: BooleanConstructor;
30
24
  debug: BooleanConstructor;
package/dist/vue.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  inject,
3
3
  track
4
- } from "./chunks/chunk-7JF7P3VW.js";
4
+ } from "./chunks/chunk-6IXYXMX6.js";
5
5
 
6
6
  // src/vue.ts
7
7
  import { defineComponent, onMounted } from "vue";
@@ -9,7 +9,7 @@ var Analytics = defineComponent({
9
9
  name: "PageflockAnalytics",
10
10
  props: {
11
11
  site: { type: String, required: true },
12
- endpoint: { type: String, required: true },
12
+ endpoint: String,
13
13
  autoEvents: Boolean,
14
14
  hashRouting: Boolean,
15
15
  debug: Boolean,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pageflock/analytics",
3
- "version": "0.0.0",
3
+ "version": "0.1.1",
4
4
  "description": "Pageflock analytics for React, Next.js, Vue and any bundled site: cookieless, under 2 KB.",
5
5
  "keywords": [
6
6
  "analytics",
@@ -59,7 +59,7 @@
59
59
  "typescript": "7.0.2",
60
60
  "vitest": "5.1.0",
61
61
  "vue": "3.5.45",
62
- "@pageflock/tracker": "0.0.0"
62
+ "@pageflock/tracker": "0.1.1"
63
63
  },
64
64
  "peerDependencies": {
65
65
  "react": ">=18",
@@ -74,7 +74,7 @@
74
74
  }
75
75
  },
76
76
  "scripts": {
77
- "build": "node --experimental-strip-types scripts/build.ts && tsc -p tsconfig.build.json",
77
+ "build": "node scripts/build.ts && tsc -p tsconfig.build.json",
78
78
  "check-types": "tsc --noEmit",
79
79
  "test": "vitest run"
80
80
  }