@hifilabs/pixel 0.9.1 → 0.10.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 +314 -0
- package/dist/browser.js +331 -23
- package/dist/browser.min.js +5 -5
- package/dist/index.esm.d.ts +26 -0
- package/dist/index.js +215 -141
- package/dist/index.mjs +215 -141
- package/package.json +4 -3
package/README.md
ADDED
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
# @hifilabs/pixel (artistPixel)
|
|
2
|
+
|
|
3
|
+
A lightweight, consent-aware analytics pixel for artist fan tracking with **platform pixel orchestration** (Meta, TikTok, Google Ads).
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **First-party analytics** - Own your fan data in Firestore
|
|
8
|
+
- **Consent-aware** - GDPR/CCPA compliant with built-in consent management
|
|
9
|
+
- **Platform pixel orchestration** - Forward events to Meta, TikTok, Google Ads (consent-gated)
|
|
10
|
+
- **Zero-config** - Works with environment variables out of the box
|
|
11
|
+
- **Lightweight** - ~15KB gzipped browser bundle
|
|
12
|
+
- **GTM compatible** - Custom template for Google Tag Manager integration
|
|
13
|
+
- **React/Next.js optimized** - SSR-safe hooks and components
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install @hifilabs/pixel
|
|
19
|
+
# or
|
|
20
|
+
pnpm add @hifilabs/pixel
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Quick Start
|
|
24
|
+
|
|
25
|
+
### Option 1: ArtistOS Component (Recommended)
|
|
26
|
+
|
|
27
|
+
Zero-config setup that reads from environment variables:
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
// app/layout.tsx
|
|
31
|
+
import { ArtistOS } from '@hifilabs/pixel';
|
|
32
|
+
|
|
33
|
+
export default function RootLayout({ children }) {
|
|
34
|
+
return (
|
|
35
|
+
<html>
|
|
36
|
+
<body>
|
|
37
|
+
<ArtistOS />
|
|
38
|
+
{children}
|
|
39
|
+
</body>
|
|
40
|
+
</html>
|
|
41
|
+
);
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Set environment variables:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
NEXT_PUBLIC_ARTIST_ID=your-artist-id
|
|
49
|
+
NEXT_PUBLIC_META_PIXEL_ID=123456789 # Optional
|
|
50
|
+
NEXT_PUBLIC_TIKTOK_PIXEL_ID=ABC123DEF # Optional
|
|
51
|
+
NEXT_PUBLIC_GOOGLE_ADS_ID=AW-123456789 # Optional
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Option 2: With Props
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
import { ArtistOS } from '@hifilabs/pixel';
|
|
58
|
+
|
|
59
|
+
<ArtistOS
|
|
60
|
+
artistId="your-artist-id"
|
|
61
|
+
metaPixelId="123456789"
|
|
62
|
+
tiktokPixelId="ABC123DEF"
|
|
63
|
+
googleAdsId="AW-123456789"
|
|
64
|
+
debug={process.env.NODE_ENV === 'development'}
|
|
65
|
+
/>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Option 3: Script Tag (HTML)
|
|
69
|
+
|
|
70
|
+
**Using Pixel CDN (Recommended)** - Config auto-loaded from artistHQ:
|
|
71
|
+
|
|
72
|
+
```html
|
|
73
|
+
<script
|
|
74
|
+
src="https://pixel-cdn.hifilabs.workers.dev/your-artist-id.js"
|
|
75
|
+
data-project-id="your-project-id"
|
|
76
|
+
data-debug="true"
|
|
77
|
+
></script>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The CDN version automatically includes your pixel configuration (Meta, TikTok, Google Ads IDs) from artistHQ → Settings → Integrations. Changes are reflected without redeploying.
|
|
81
|
+
|
|
82
|
+
**Manual Configuration** - Explicit pixel IDs in script:
|
|
83
|
+
|
|
84
|
+
```html
|
|
85
|
+
<script
|
|
86
|
+
src="https://balance-pixel-proxy.hifilabs.workers.dev/pixel.js"
|
|
87
|
+
data-artist-id="your-artist-id"
|
|
88
|
+
data-meta-pixel-id="123456789"
|
|
89
|
+
data-tiktok-pixel-id="ABC123DEF"
|
|
90
|
+
data-google-ads-id="AW-123456789"
|
|
91
|
+
data-debug="true"
|
|
92
|
+
></script>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Platform Pixel Orchestration
|
|
96
|
+
|
|
97
|
+
artistPixel orchestrates third-party platform pixels with consent awareness:
|
|
98
|
+
|
|
99
|
+
1. **First-party first**: artistPixel always collects first-party data
|
|
100
|
+
2. **Consent-gated**: Platform pixels (Meta, TikTok, Google Ads) only load when marketing consent is granted
|
|
101
|
+
3. **Event forwarding**: Events are automatically forwarded to platform pixels
|
|
102
|
+
|
|
103
|
+
### Supported Platforms
|
|
104
|
+
|
|
105
|
+
| Platform | Environment Variable | Prop |
|
|
106
|
+
|----------|---------------------|------|
|
|
107
|
+
| Meta/Facebook | `NEXT_PUBLIC_META_PIXEL_ID` | `metaPixelId` |
|
|
108
|
+
| TikTok | `NEXT_PUBLIC_TIKTOK_PIXEL_ID` | `tiktokPixelId` |
|
|
109
|
+
| Google Ads | `NEXT_PUBLIC_GOOGLE_ADS_ID` | `googleAdsId` |
|
|
110
|
+
|
|
111
|
+
### Granular Event Forwarding
|
|
112
|
+
|
|
113
|
+
Control which events are forwarded to platform pixels:
|
|
114
|
+
|
|
115
|
+
```tsx
|
|
116
|
+
<ArtistOS
|
|
117
|
+
artistId="your-artist-id"
|
|
118
|
+
metaPixelId="123456789"
|
|
119
|
+
forwardEvents={{
|
|
120
|
+
pageview: true, // Forward page views (default: true)
|
|
121
|
+
purchase: true, // Forward purchases (default: true)
|
|
122
|
+
addToCart: true, // Forward add to cart (default: true)
|
|
123
|
+
lead: true, // Forward leads (default: true)
|
|
124
|
+
custom: ['newsletter_signup', 'merch_view'] // Custom events to forward
|
|
125
|
+
}}
|
|
126
|
+
/>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Tracking API
|
|
130
|
+
|
|
131
|
+
### Using Hooks (React)
|
|
132
|
+
|
|
133
|
+
```tsx
|
|
134
|
+
import { useArtistOS } from '@hifilabs/pixel';
|
|
135
|
+
|
|
136
|
+
function MyComponent() {
|
|
137
|
+
const { track, page, purchase, identify } = useArtistOS();
|
|
138
|
+
|
|
139
|
+
// Track custom event
|
|
140
|
+
track('newsletter_signup', { source: 'footer' });
|
|
141
|
+
|
|
142
|
+
// Track page view
|
|
143
|
+
page({ title: 'Product Page' });
|
|
144
|
+
|
|
145
|
+
// Track purchase
|
|
146
|
+
purchase(99.99, 'USD', { product: 'Album', sku: 'ALB-001' });
|
|
147
|
+
|
|
148
|
+
// Identify user
|
|
149
|
+
await identify('fan@email.com', { name: 'Fan Name' });
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Using SSR-Safe Functions
|
|
154
|
+
|
|
155
|
+
```tsx
|
|
156
|
+
import { track, page, purchase, identify } from '@hifilabs/pixel';
|
|
157
|
+
|
|
158
|
+
// Works in client components, safe to import in server components
|
|
159
|
+
track('event_name', { property: 'value' });
|
|
160
|
+
page({ title: 'Page Title' });
|
|
161
|
+
purchase(29.99, 'USD', { item: 'Merch' });
|
|
162
|
+
await identify('email@example.com');
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Consent Management
|
|
166
|
+
|
|
167
|
+
### Built-in Consent Banner
|
|
168
|
+
|
|
169
|
+
```tsx
|
|
170
|
+
<ArtistOS
|
|
171
|
+
artistId="your-artist-id"
|
|
172
|
+
consentMode="built-in" // Shows built-in consent banner
|
|
173
|
+
/>
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Custom Consent Integration
|
|
177
|
+
|
|
178
|
+
```tsx
|
|
179
|
+
import { useArtistOS } from '@hifilabs/pixel';
|
|
180
|
+
|
|
181
|
+
function CustomConsentBanner() {
|
|
182
|
+
const { setConsent, getConsent } = useArtistOS();
|
|
183
|
+
|
|
184
|
+
const handleAcceptAll = () => {
|
|
185
|
+
setConsent({
|
|
186
|
+
analytics: true,
|
|
187
|
+
marketing: true,
|
|
188
|
+
personalization: true,
|
|
189
|
+
timestamp: new Date().toISOString()
|
|
190
|
+
});
|
|
191
|
+
};
|
|
192
|
+
|
|
193
|
+
const handleRejectMarketing = () => {
|
|
194
|
+
setConsent({
|
|
195
|
+
analytics: true,
|
|
196
|
+
marketing: false,
|
|
197
|
+
personalization: false,
|
|
198
|
+
timestamp: new Date().toISOString()
|
|
199
|
+
});
|
|
200
|
+
};
|
|
201
|
+
|
|
202
|
+
return (
|
|
203
|
+
<div>
|
|
204
|
+
<button onClick={handleAcceptAll}>Accept All</button>
|
|
205
|
+
<button onClick={handleRejectMarketing}>Essential Only</button>
|
|
206
|
+
</div>
|
|
207
|
+
);
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Consent Flow
|
|
212
|
+
|
|
213
|
+
```
|
|
214
|
+
1. Default: denied
|
|
215
|
+
2. Show banner
|
|
216
|
+
3. User chooses
|
|
217
|
+
4. Update consent
|
|
218
|
+
5. Track (if analytics granted)
|
|
219
|
+
6. Platform pixels injected (if marketing consent granted)
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Google Tag Manager Integration
|
|
223
|
+
|
|
224
|
+
Import the custom template from `gtm/artistPixel.tpl`:
|
|
225
|
+
|
|
226
|
+
1. In GTM, go to Templates > New
|
|
227
|
+
2. Import the template file
|
|
228
|
+
3. Create a new tag using the template
|
|
229
|
+
4. Configure with your Artist ID and optional platform pixel IDs
|
|
230
|
+
|
|
231
|
+
See [gtm/README.md](./gtm/README.md) for detailed instructions.
|
|
232
|
+
|
|
233
|
+
## Specialized Tracking Hooks
|
|
234
|
+
|
|
235
|
+
```tsx
|
|
236
|
+
import {
|
|
237
|
+
useArtistPixelEcommerce, // Products, cart, checkout
|
|
238
|
+
useArtistPixelMedia, // Audio/video tracking
|
|
239
|
+
useArtistPixelEngagement, // Shares, likes, scroll depth
|
|
240
|
+
useArtistPixelForm, // Form interactions
|
|
241
|
+
useArtistPixelSearch, // Search & discovery
|
|
242
|
+
useArtistPixelNotification,// Push, email, in-app
|
|
243
|
+
useArtistPixelSocial, // Social & community
|
|
244
|
+
useArtistPixelAuth, // Authentication flows
|
|
245
|
+
useArtistPixelError, // Error monitoring
|
|
246
|
+
useArtistPixelAB, // A/B testing
|
|
247
|
+
useArtistPixelLive, // Livestream events
|
|
248
|
+
useArtistPixelSubscription,// Subscriptions & payments
|
|
249
|
+
} from '@hifilabs/pixel';
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
## Configuration Options
|
|
253
|
+
|
|
254
|
+
### ArtistOS Props
|
|
255
|
+
|
|
256
|
+
| Prop | Type | Default | Description |
|
|
257
|
+
|------|------|---------|-------------|
|
|
258
|
+
| `artistId` | `string` | env var | Artist identifier |
|
|
259
|
+
| `metaPixelId` | `string` | env var | Meta/Facebook Pixel ID |
|
|
260
|
+
| `tiktokPixelId` | `string` | env var | TikTok Pixel ID |
|
|
261
|
+
| `googleAdsId` | `string` | env var | Google Ads ID (AW-xxx) |
|
|
262
|
+
| `consentMode` | `'built-in' \| 'c15t' \| 'custom'` | `'custom'` | Consent management mode |
|
|
263
|
+
| `forwardEvents` | `ForwardingConfig` | all true | Event forwarding config |
|
|
264
|
+
| `debug` | `boolean` | `false` | Enable debug logging |
|
|
265
|
+
| `exclude` | `string[]` | `[]` | URL patterns to exclude |
|
|
266
|
+
| `trackFileDownloads` | `boolean` | `false` | Auto-track file downloads |
|
|
267
|
+
| `hashRouting` | `boolean` | `false` | Track hash route changes |
|
|
268
|
+
|
|
269
|
+
### Script Data Attributes
|
|
270
|
+
|
|
271
|
+
| Attribute | Description |
|
|
272
|
+
|-----------|-------------|
|
|
273
|
+
| `data-artist-id` | Artist identifier (required) |
|
|
274
|
+
| `data-project-id` | Project identifier |
|
|
275
|
+
| `data-meta-pixel-id` | Meta/Facebook Pixel ID |
|
|
276
|
+
| `data-tiktok-pixel-id` | TikTok Pixel ID |
|
|
277
|
+
| `data-google-ads-id` | Google Ads ID |
|
|
278
|
+
| `data-forward-pageview` | Forward pageviews (`true`/`false`) |
|
|
279
|
+
| `data-forward-purchase` | Forward purchases (`true`/`false`) |
|
|
280
|
+
| `data-forward-custom` | Custom events (comma-separated) |
|
|
281
|
+
| `data-exclude-pages` | URL patterns to exclude (comma-separated) |
|
|
282
|
+
| `data-debug` | Enable debug mode |
|
|
283
|
+
|
|
284
|
+
## Architecture
|
|
285
|
+
|
|
286
|
+
```
|
|
287
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
288
|
+
│ artistPixel │
|
|
289
|
+
│ ┌─────────────────────────────────────────────────────┐ │
|
|
290
|
+
│ │ First-Party Collection │ │
|
|
291
|
+
│ │ (Always runs, stores in Firestore) │ │
|
|
292
|
+
│ └─────────────────────────────────────────────────────┘ │
|
|
293
|
+
│ │ │
|
|
294
|
+
│ consent check │
|
|
295
|
+
│ │ │
|
|
296
|
+
│ ┌─────────────────────────▼─────────────────────────────┐ │
|
|
297
|
+
│ │ Platform Pixel Orchestrator │ │
|
|
298
|
+
│ │ (Only when marketing consent granted) │ │
|
|
299
|
+
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
|
300
|
+
│ │ │ Meta │ │ TikTok │ │ Google │ │ │
|
|
301
|
+
│ │ │ Pixel │ │ Pixel │ │ Ads │ │ │
|
|
302
|
+
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
|
|
303
|
+
│ └───────────────────────────────────────────────────────┘ │
|
|
304
|
+
└─────────────────────────────────────────────────────────────┘
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
## Documentation
|
|
308
|
+
|
|
309
|
+
- [Quick Reference](./docs/QUICK-REFERENCE.md) - Common patterns and quick setup
|
|
310
|
+
- [GTM Integration](./gtm/README.md) - Google Tag Manager setup
|
|
311
|
+
|
|
312
|
+
## License
|
|
313
|
+
|
|
314
|
+
MIT
|