@databuddy/sdk 1.0.0 → 1.2.0
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 +129 -0
- package/dist/Databuddy.d.ts +8 -0
- package/dist/Databuddy.js +46 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/types.d.ts +1 -1
- package/package.json +4 -2
- package/src/DatabuddyProvider.tsx +0 -33
- package/src/index.ts +0 -2
- package/src/types.ts +0 -173
- package/tsconfig.json +0 -19
package/README.md
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# Databuddy SDK & React Component
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@databuddy/sdk)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
[](https://docs.databuddy.cc)
|
|
6
|
+
|
|
7
|
+
> **The easiest, privacy-first way to add analytics to your web app.**
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## ✨ Features
|
|
12
|
+
|
|
13
|
+
- 📊 **Automatic page/screen view tracking**
|
|
14
|
+
- ⚡ **Performance, Web Vitals, and error tracking**
|
|
15
|
+
- 🧑💻 **Custom event tracking**
|
|
16
|
+
- 🧩 **Drop-in React/Next.js component: `<Databuddy />`**
|
|
17
|
+
- 🛡️ **Privacy-first: anonymized by default, sampling, batching, and more**
|
|
18
|
+
- 🛠️ **Type-safe config and autocompletion**
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 🚀 Quickstart
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
bun add @databuddy/sdk
|
|
26
|
+
# or
|
|
27
|
+
npm install @databuddy/sdk
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Add to your root layout (Next.js/React):
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
import { Databuddy } from '@databuddy/sdk';
|
|
34
|
+
|
|
35
|
+
export default function RootLayout({ children }) {
|
|
36
|
+
return (
|
|
37
|
+
<html lang="en">
|
|
38
|
+
<head />
|
|
39
|
+
<Databuddy
|
|
40
|
+
clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
|
|
41
|
+
trackScreenViews
|
|
42
|
+
trackPerformance
|
|
43
|
+
trackErrors
|
|
44
|
+
enableBatching
|
|
45
|
+
batchSize={20}
|
|
46
|
+
/>
|
|
47
|
+
<body>{children}</body>
|
|
48
|
+
</html>
|
|
49
|
+
);
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 🛠️ Configuration Options
|
|
56
|
+
|
|
57
|
+
All options are type-safe and documented in `DatabuddyConfig`:
|
|
58
|
+
|
|
59
|
+
| Option | Type | Default | Description |
|
|
60
|
+
|-----------------------|-----------|--------------|-------------|
|
|
61
|
+
| `clientId` | string | — | **Required.** Your Databuddy project client ID. |
|
|
62
|
+
| `clientSecret` | string | — | (Advanced) For server-side use only. |
|
|
63
|
+
| `apiUrl` | string | `https://api.databuddy.cc` | Custom API endpoint. |
|
|
64
|
+
| `scriptUrl` | string | `https://app.databuddy.cc/databuddy.js` | Custom script URL. |
|
|
65
|
+
| `sdk` | string | `web` | SDK name. Only override for custom builds. |
|
|
66
|
+
| `sdkVersion` | string | *auto* | SDK version. Defaults to package version. |
|
|
67
|
+
| `disabled` | boolean | `false` | Disable all tracking. |
|
|
68
|
+
| `waitForProfile` | boolean | `false` | Wait for user profile before sending events. |
|
|
69
|
+
| `trackScreenViews` | boolean | `true` | Auto-track page/screen views. |
|
|
70
|
+
| `trackHashChanges` | boolean | `false` | Track hash changes in URL. |
|
|
71
|
+
| `trackAttributes` | boolean | `false` | Track data-* attributes. |
|
|
72
|
+
| `trackOutgoingLinks` | boolean | `false` | Track outgoing link clicks. |
|
|
73
|
+
| `trackSessions` | boolean | `false` | Track user sessions. |
|
|
74
|
+
| `trackPerformance` | boolean | `true` | Track page performance. |
|
|
75
|
+
| `trackWebVitals` | boolean | `true` | Track Web Vitals. |
|
|
76
|
+
| `trackEngagement` | boolean | `false` | Track engagement metrics. |
|
|
77
|
+
| `trackScrollDepth` | boolean | `false` | Track scroll depth. |
|
|
78
|
+
| `trackExitIntent` | boolean | `false` | Track exit intent. |
|
|
79
|
+
| `trackInteractions` | boolean | `false` | Track user interactions. |
|
|
80
|
+
| `trackErrors` | boolean | `true` | Track JS errors. |
|
|
81
|
+
| `trackBounceRate` | boolean | `false` | Track bounce rate. |
|
|
82
|
+
| `samplingRate` | number | `1.0` | Sampling rate (0.0–1.0). |
|
|
83
|
+
| `enableRetries` | boolean | `true` | Retry failed requests. |
|
|
84
|
+
| `maxRetries` | number | `3` | Max retries. |
|
|
85
|
+
| `initialRetryDelay` | number | `500` | Initial retry delay (ms). |
|
|
86
|
+
| `enableBatching` | boolean | `true` | Enable event batching. |
|
|
87
|
+
| `batchSize` | number | `20` | Events per batch (1–50). |
|
|
88
|
+
| `batchTimeout` | number | `5000` | Batch timeout (ms, 100–30000). |
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## 💡 FAQ
|
|
93
|
+
|
|
94
|
+
**Q: Is Databuddy privacy-friendly?**
|
|
95
|
+
A: Yes! All analytics are anonymized by default. No cookies, no fingerprinting, no PII.
|
|
96
|
+
|
|
97
|
+
**Q: Can I use this in Next.js, Remix, or plain React?**
|
|
98
|
+
A: Yes! `<Databuddy />` works in any React app. For non-React, use the script tag directly.
|
|
99
|
+
|
|
100
|
+
**Q: How do I disable analytics in development?**
|
|
101
|
+
A: Use the `disabled` prop: `<Databuddy disabled={process.env.NODE_ENV === 'development'} ... />`
|
|
102
|
+
|
|
103
|
+
**Q: Where do I find my `clientId`?**
|
|
104
|
+
A: In your [Databuddy dashboard](https://app.databuddy.cc).
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 🧑💻 Troubleshooting
|
|
109
|
+
|
|
110
|
+
- **Script not loading?**
|
|
111
|
+
- Make sure your `clientId` is correct and the script URL is reachable.
|
|
112
|
+
- **No events in dashboard?**
|
|
113
|
+
- Check your config, especially `clientId` and network requests in the browser dev tools.
|
|
114
|
+
- **Type errors?**
|
|
115
|
+
- All config options are type-safe. Use your IDE's autocomplete for help.
|
|
116
|
+
- **SSR/Next.js?**
|
|
117
|
+
- The component is safe for SSR/React Server Components. It only injects the script on the client.
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## 📚 Documentation & Support
|
|
122
|
+
|
|
123
|
+
- [Databuddy Docs](https://docs.databuddy.cc)
|
|
124
|
+
- [Dashboard](https://app.databuddy.cc)
|
|
125
|
+
- [Contact Support](https://www.databuddy.cc/contact)
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
© Databuddy. All rights reserved.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { DatabuddyConfig } from './types';
|
|
2
|
+
/**
|
|
3
|
+
* <Databuddy /> component for Next.js/React apps
|
|
4
|
+
* Injects the databuddy.js script with all config as data attributes
|
|
5
|
+
* Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
|
|
6
|
+
*/
|
|
7
|
+
export declare function Databuddy(props: DatabuddyConfig): null;
|
|
8
|
+
export default Databuddy;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
import pkg from '../package.json';
|
|
3
|
+
import { useEffect } from 'react';
|
|
4
|
+
/**
|
|
5
|
+
* <Databuddy /> component for Next.js/React apps
|
|
6
|
+
* Injects the databuddy.js script with all config as data attributes
|
|
7
|
+
* Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
|
|
8
|
+
*/
|
|
9
|
+
export function Databuddy(props) {
|
|
10
|
+
useEffect(() => {
|
|
11
|
+
if (typeof window === 'undefined')
|
|
12
|
+
return;
|
|
13
|
+
if (props.disabled)
|
|
14
|
+
return;
|
|
15
|
+
if (document.querySelector('script[data-databuddy-injected]'))
|
|
16
|
+
return;
|
|
17
|
+
const script = document.createElement('script');
|
|
18
|
+
script.src = props.scriptUrl || 'https://app.databuddy.cc/databuddy.js';
|
|
19
|
+
script.defer = true;
|
|
20
|
+
script.setAttribute('data-databuddy-injected', 'true');
|
|
21
|
+
// Always set sdkVersion from package.json unless explicitly overridden
|
|
22
|
+
const sdkVersion = props.sdkVersion || pkg.version;
|
|
23
|
+
script.setAttribute('data-sdk-version', sdkVersion);
|
|
24
|
+
for (const [key, value] of Object.entries(props)) {
|
|
25
|
+
if (value !== undefined && key !== 'sdkVersion') {
|
|
26
|
+
const dataKey = `data-${key.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
|
|
27
|
+
// Convert booleans and numbers to string for HTML attributes
|
|
28
|
+
if (typeof value === 'boolean') {
|
|
29
|
+
script.setAttribute(dataKey, value ? 'true' : 'false');
|
|
30
|
+
}
|
|
31
|
+
else if (typeof value === 'number') {
|
|
32
|
+
script.setAttribute(dataKey, value.toString());
|
|
33
|
+
}
|
|
34
|
+
else {
|
|
35
|
+
script.setAttribute(dataKey, String(value));
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
document.head.appendChild(script);
|
|
40
|
+
return () => {
|
|
41
|
+
script.remove();
|
|
42
|
+
};
|
|
43
|
+
}, [props]);
|
|
44
|
+
return null;
|
|
45
|
+
}
|
|
46
|
+
export default Databuddy;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export * from './
|
|
1
|
+
export * from './Databuddy';
|
|
2
2
|
export * from './types';
|
package/dist/index.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export * from './
|
|
1
|
+
export * from './Databuddy';
|
|
2
2
|
export * from './types';
|
package/dist/types.d.ts
CHANGED
package/package.json
CHANGED
|
@@ -1,12 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@databuddy/sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Official Databuddy Analytics SDK",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"exports": {
|
|
8
8
|
".": "./dist/index.js"
|
|
9
9
|
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist"
|
|
12
|
+
],
|
|
10
13
|
"keywords": [
|
|
11
14
|
"analytics",
|
|
12
15
|
"tracking",
|
|
@@ -16,7 +19,6 @@
|
|
|
16
19
|
"scripts": {
|
|
17
20
|
"build": "tsc --project tsconfig.json"
|
|
18
21
|
},
|
|
19
|
-
"author": "Databuddy",
|
|
20
22
|
"license": "MIT",
|
|
21
23
|
"devDependencies": {
|
|
22
24
|
"@types/node": "^20.0.0",
|
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
'use client';
|
|
2
|
-
|
|
3
|
-
import { useEffect } from 'react';
|
|
4
|
-
import type { DatabuddyConfig } from './types';
|
|
5
|
-
|
|
6
|
-
/**
|
|
7
|
-
* <Databuddy /> component for Next.js/React apps
|
|
8
|
-
* Injects the databuddy.js script with all config as data attributes
|
|
9
|
-
* Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
|
|
10
|
-
*/
|
|
11
|
-
export function Databuddy(props: DatabuddyConfig) {
|
|
12
|
-
useEffect(() => {
|
|
13
|
-
if (typeof window === 'undefined') return;
|
|
14
|
-
if (document.querySelector('script[data-databuddy-injected]')) return;
|
|
15
|
-
const script = document.createElement('script');
|
|
16
|
-
script.src = props.scriptUrl || 'https://app.databuddy.cc/databuddy.js';
|
|
17
|
-
script.defer = true;
|
|
18
|
-
script.setAttribute('data-databuddy-injected', 'true');
|
|
19
|
-
for (const [key, value] of Object.entries(props)) {
|
|
20
|
-
if (value !== undefined) {
|
|
21
|
-
const dataKey = `data-${key.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
|
|
22
|
-
script.setAttribute(dataKey, String(value));
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
document.head.appendChild(script);
|
|
26
|
-
return () => {
|
|
27
|
-
script.remove();
|
|
28
|
-
};
|
|
29
|
-
}, [props]);
|
|
30
|
-
return null;
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
export default Databuddy;
|
package/src/index.ts
DELETED
package/src/types.ts
DELETED
|
@@ -1,173 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Configuration options for the Databuddy SDK and <Databuddy /> component.
|
|
3
|
-
* All options are passed as data attributes to the injected script.
|
|
4
|
-
*/
|
|
5
|
-
export interface DatabuddyConfig {
|
|
6
|
-
/**
|
|
7
|
-
* Your Databuddy project client ID (required).
|
|
8
|
-
* Get this from your Databuddy dashboard.
|
|
9
|
-
* Example: '3ed1fce1-5a56-4cbc-a917-66864f6d18e3'
|
|
10
|
-
*/
|
|
11
|
-
clientId: string;
|
|
12
|
-
|
|
13
|
-
/**
|
|
14
|
-
* (Advanced) Your Databuddy client secret for server-side operations.
|
|
15
|
-
* Not required for browser usage.
|
|
16
|
-
*/
|
|
17
|
-
clientSecret?: string;
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
* Custom API endpoint for event ingestion.
|
|
21
|
-
* Default: 'https://api.databuddy.cc'
|
|
22
|
-
*/
|
|
23
|
-
apiUrl?: string;
|
|
24
|
-
|
|
25
|
-
/**
|
|
26
|
-
* Custom script URL for the Databuddy browser bundle.
|
|
27
|
-
* Default: 'https://app.databuddy.cc/databuddy.js'
|
|
28
|
-
*/
|
|
29
|
-
scriptUrl?: string;
|
|
30
|
-
|
|
31
|
-
/**
|
|
32
|
-
* SDK name for analytics (default: 'web').
|
|
33
|
-
* Only override if you are building a custom integration.
|
|
34
|
-
*/
|
|
35
|
-
sdk?: string;
|
|
36
|
-
|
|
37
|
-
/**
|
|
38
|
-
* SDK version (default: '1.0.0').
|
|
39
|
-
* Only override for custom builds.
|
|
40
|
-
*/
|
|
41
|
-
sdkVersion?: string;
|
|
42
|
-
|
|
43
|
-
/**
|
|
44
|
-
* Disable all tracking (default: false).
|
|
45
|
-
* If true, no events will be sent.
|
|
46
|
-
*/
|
|
47
|
-
disabled?: boolean;
|
|
48
|
-
|
|
49
|
-
/**
|
|
50
|
-
* Wait for user profile before sending events (advanced, default: false).
|
|
51
|
-
*/
|
|
52
|
-
waitForProfile?: boolean;
|
|
53
|
-
|
|
54
|
-
// --- Tracking Features ---
|
|
55
|
-
|
|
56
|
-
/**
|
|
57
|
-
* Automatically track screen/page views (default: true).
|
|
58
|
-
*/
|
|
59
|
-
trackScreenViews?: boolean;
|
|
60
|
-
|
|
61
|
-
/**
|
|
62
|
-
* Track hash changes in the URL (default: false).
|
|
63
|
-
*/
|
|
64
|
-
trackHashChanges?: boolean;
|
|
65
|
-
|
|
66
|
-
/**
|
|
67
|
-
* Track data-* attributes on elements (default: false).
|
|
68
|
-
*/
|
|
69
|
-
trackAttributes?: boolean;
|
|
70
|
-
|
|
71
|
-
/**
|
|
72
|
-
* Track clicks on outgoing links (default: false).
|
|
73
|
-
*/
|
|
74
|
-
trackOutgoingLinks?: boolean;
|
|
75
|
-
|
|
76
|
-
/**
|
|
77
|
-
* Track user sessions (default: false).
|
|
78
|
-
*/
|
|
79
|
-
trackSessions?: boolean;
|
|
80
|
-
|
|
81
|
-
/**
|
|
82
|
-
* Track page performance metrics (default: true).
|
|
83
|
-
*/
|
|
84
|
-
trackPerformance?: boolean;
|
|
85
|
-
|
|
86
|
-
/**
|
|
87
|
-
* Track Web Vitals metrics (default: true).
|
|
88
|
-
*/
|
|
89
|
-
trackWebVitals?: boolean;
|
|
90
|
-
|
|
91
|
-
/**
|
|
92
|
-
* Track user engagement metrics (default: false).
|
|
93
|
-
*/
|
|
94
|
-
trackEngagement?: boolean;
|
|
95
|
-
|
|
96
|
-
/**
|
|
97
|
-
* Track scroll depth (default: false).
|
|
98
|
-
*/
|
|
99
|
-
trackScrollDepth?: boolean;
|
|
100
|
-
|
|
101
|
-
/**
|
|
102
|
-
* Track exit intent (default: false).
|
|
103
|
-
*/
|
|
104
|
-
trackExitIntent?: boolean;
|
|
105
|
-
|
|
106
|
-
/**
|
|
107
|
-
* Track user interactions (default: false).
|
|
108
|
-
*/
|
|
109
|
-
trackInteractions?: boolean;
|
|
110
|
-
|
|
111
|
-
/**
|
|
112
|
-
* Track JavaScript errors (default: true).
|
|
113
|
-
*/
|
|
114
|
-
trackErrors?: boolean;
|
|
115
|
-
|
|
116
|
-
/**
|
|
117
|
-
* Track bounce rate (default: false).
|
|
118
|
-
*/
|
|
119
|
-
trackBounceRate?: boolean;
|
|
120
|
-
|
|
121
|
-
// --- Advanced/Performance ---
|
|
122
|
-
|
|
123
|
-
/**
|
|
124
|
-
* Sampling rate for events (0.0 to 1.0, default: 1.0).
|
|
125
|
-
* Example: 0.5 = 50% of events sent.
|
|
126
|
-
*/
|
|
127
|
-
samplingRate?: number;
|
|
128
|
-
|
|
129
|
-
/**
|
|
130
|
-
* Enable retries for failed requests (default: true).
|
|
131
|
-
*/
|
|
132
|
-
enableRetries?: boolean;
|
|
133
|
-
|
|
134
|
-
/**
|
|
135
|
-
* Maximum number of retries for failed requests (default: 3).
|
|
136
|
-
* Only used if enableRetries is true.
|
|
137
|
-
*/
|
|
138
|
-
maxRetries?: number;
|
|
139
|
-
|
|
140
|
-
/**
|
|
141
|
-
* Initial retry delay in milliseconds (default: 500).
|
|
142
|
-
* Only used if enableRetries is true.
|
|
143
|
-
*/
|
|
144
|
-
initialRetryDelay?: number;
|
|
145
|
-
|
|
146
|
-
/**
|
|
147
|
-
* Enable event batching (default: true).
|
|
148
|
-
*/
|
|
149
|
-
enableBatching?: boolean;
|
|
150
|
-
|
|
151
|
-
/**
|
|
152
|
-
* Number of events to batch before sending (default: 20).
|
|
153
|
-
* Only used if enableBatching is true.
|
|
154
|
-
* Min: 1, Max: 50
|
|
155
|
-
*/
|
|
156
|
-
batchSize?: number;
|
|
157
|
-
|
|
158
|
-
/**
|
|
159
|
-
* Batch timeout in milliseconds (default: 5000).
|
|
160
|
-
* Only used if enableBatching is true.
|
|
161
|
-
* Min: 100, Max: 30000
|
|
162
|
-
*/
|
|
163
|
-
batchTimeout?: number;
|
|
164
|
-
}
|
|
165
|
-
|
|
166
|
-
/**
|
|
167
|
-
* Event properties that can be attached to any event
|
|
168
|
-
*/
|
|
169
|
-
export interface EventProperties {
|
|
170
|
-
/** Custom properties for the event */
|
|
171
|
-
[key: string]: string | number | boolean | null | undefined | EventProperties;
|
|
172
|
-
}
|
|
173
|
-
|
package/tsconfig.json
DELETED
|
@@ -1,19 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"compilerOptions": {
|
|
3
|
-
"target": "es2018",
|
|
4
|
-
"module": "esnext",
|
|
5
|
-
"lib": ["dom", "esnext"],
|
|
6
|
-
"declaration": true,
|
|
7
|
-
"declarationDir": "dist",
|
|
8
|
-
"strict": true,
|
|
9
|
-
"moduleResolution": "node",
|
|
10
|
-
"esModuleInterop": true,
|
|
11
|
-
"skipLibCheck": true,
|
|
12
|
-
"forceConsistentCasingInFileNames": true,
|
|
13
|
-
"outDir": "dist",
|
|
14
|
-
"rootDir": "src",
|
|
15
|
-
"jsx": "react-jsx"
|
|
16
|
-
},
|
|
17
|
-
"include": ["src/**/*"],
|
|
18
|
-
"exclude": ["node_modules", "dist", "**/*.test.ts"]
|
|
19
|
-
}
|