First-party analytics - Own your fan data in Firestore
Consent-aware - GDPR/CCPA compliant with built-in consent management
Platform pixel orchestration - Forward events to Meta, TikTok, Google Ads (consent-gated)
Zero-config - Works with environment variables out of the box
Lightweight - ~15KB gzipped browser bundle
GTM compatible - Custom template for Google Tag Manager integration
React/Next.js optimized - SSR-safe hooks and components

Installation

npm install @hifilabs/pixel
# or
pnpm add @hifilabs/pixel

Quick Start

Option 1: ArtistOS Component (Recommended)

Zero-config setup that reads from environment variables:

// app/layout.tsx
import { ArtistOS } from '@hifilabs/pixel';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ArtistOS />
        {children}
      </body>
    </html>
  );
}

Set environment variables:

NEXT_PUBLIC_ARTIST_ID=your-artist-id
NEXT_PUBLIC_META_PIXEL_ID=123456789        # Optional
NEXT_PUBLIC_TIKTOK_PIXEL_ID=ABC123DEF      # Optional
NEXT_PUBLIC_GOOGLE_ADS_ID=AW-123456789     # Optional

Option 2: With Props

import { ArtistOS } from '@hifilabs/pixel';

<ArtistOS
  artistId="your-artist-id"
  metaPixelId="123456789"
  tiktokPixelId="ABC123DEF"
  googleAdsId="AW-123456789"
  debug={process.env.NODE_ENV === 'development'}
/>

Option 3: Script Tag (HTML)

Using Pixel CDN (Recommended) - Config auto-loaded from artistHQ:

<script
  src="https://pixel-cdn.hifilabs.workers.dev/your-artist-id.js"
  data-project-id="your-project-id"
  data-debug="true"
></script>

The CDN version automatically includes your pixel configuration (Meta, TikTok, Google Ads IDs) from artistHQ → Settings → Integrations. Changes are reflected without redeploying.

Manual Configuration - Explicit pixel IDs in script:

<script
  src="https://e.os.xyz/pixel.js"
  data-artist-id="your-artist-id"
  data-meta-pixel-id="123456789"
  data-tiktok-pixel-id="ABC123DEF"
  data-google-ads-id="AW-123456789"
  data-debug="true"
></script>

Platform Pixel Orchestration

artistPixel orchestrates third-party platform pixels with consent awareness:

First-party first: artistPixel always collects first-party data
Consent-gated: Platform pixels (Meta, TikTok, Google Ads) only load when marketing consent is granted
Event forwarding: Events are automatically forwarded to platform pixels

Supported Platforms

Platform	Environment Variable	Prop
Meta/Facebook	`NEXT_PUBLIC_META_PIXEL_ID`	`metaPixelId`
TikTok	`NEXT_PUBLIC_TIKTOK_PIXEL_ID`	`tiktokPixelId`
Google Ads	`NEXT_PUBLIC_GOOGLE_ADS_ID`	`googleAdsId`

Granular Event Forwarding

Control which events are forwarded to platform pixels:

<ArtistOS
  artistId="your-artist-id"
  metaPixelId="123456789"
  forwardEvents={{
    pageview: true,    // Forward page views (default: true)
    purchase: true,    // Forward purchases (default: true)
    addToCart: true,   // Forward add to cart (default: true)
    lead: true,        // Forward leads (default: true)
    custom: ['newsletter_signup', 'merch_view']  // Custom events to forward
  }}
/>

Tracking API

Using Hooks (React)

import { useArtistOS } from '@hifilabs/pixel';

function MyComponent() {
  const { track, page, purchase, identify } = useArtistOS();

  // Track custom event
  track('newsletter_signup', { source: 'footer' });

  // Track page view
  page({ title: 'Product Page' });

  // Track purchase
  purchase(99.99, 'USD', { product: 'Album', sku: 'ALB-001' });

  // Identify user
  await identify('fan@email.com', { name: 'Fan Name' });
}

Using SSR-Safe Functions

import { track, page, purchase, identify } from '@hifilabs/pixel';

// Works in client components, safe to import in server components
track('event_name', { property: 'value' });
page({ title: 'Page Title' });
purchase(29.99, 'USD', { item: 'Merch' });
await identify('email@example.com');

<ArtistOS
  artistId="your-artist-id"
  consentMode="built-in"  // Shows built-in consent banner
/>

import { useArtistOS } from '@hifilabs/pixel';

function CustomConsentBanner() {
  const { setConsent, getConsent } = useArtistOS();

  const handleAcceptAll = () => {
    setConsent({
      analytics: true,
      marketing: true,
      personalization: true,
      timestamp: new Date().toISOString()
    });
  };

  const handleRejectMarketing = () => {
    setConsent({
      analytics: true,
      marketing: false,
      personalization: false,
      timestamp: new Date().toISOString()
    });
  };

  return (
    <div>
      <button onClick={handleAcceptAll}>Accept All</button>
      <button onClick={handleRejectMarketing}>Essential Only</button>
    </div>
  );
}

1. Default: denied
2. Show banner
3. User chooses
4. Update consent
5. Track (if analytics granted)
6. Platform pixels injected (if marketing consent granted)

Google Tag Manager Integration

Import the custom template from gtm/artistPixel.tpl:

In GTM, go to Templates > New
Import the template file
Create a new tag using the template
Configure with your Artist ID and optional platform pixel IDs

See gtm/README.md for detailed instructions.

Specialized Tracking Hooks

import {
  useArtistPixelEcommerce,  // Products, cart, checkout
  useArtistPixelMedia,       // Audio/video tracking
  useArtistPixelEngagement,  // Shares, likes, scroll depth
  useArtistPixelForm,        // Form interactions
  useArtistPixelSearch,      // Search & discovery
  useArtistPixelNotification,// Push, email, in-app
  useArtistPixelSocial,      // Social & community
  useArtistPixelAuth,        // Authentication flows
  useArtistPixelError,       // Error monitoring
  useArtistPixelAB,          // A/B testing
  useArtistPixelLive,        // Livestream events
  useArtistPixelSubscription,// Subscriptions & payments
} from '@hifilabs/pixel';

Configuration Options

ArtistOS Props

Prop	Type	Default	Description
`artistId`	`string`	env var	Artist identifier
`metaPixelId`	`string`	env var	Meta/Facebook Pixel ID
`tiktokPixelId`	`string`	env var	TikTok Pixel ID
`googleAdsId`	`string`	env var	Google Ads ID (AW-xxx)
`consentMode`	`'built-in' \| 'c15t' \| 'custom'`	`'custom'`	Consent management mode
`forwardEvents`	`ForwardingConfig`	all true	Event forwarding config
`debug`	`boolean`	`false`	Enable debug logging
`exclude`	`string[]`	`[]`	URL patterns to exclude
`trackFileDownloads`	`boolean`	`false`	Auto-track file downloads
`hashRouting`	`boolean`	`false`	Track hash route changes

Script Data Attributes

Attribute	Description
`data-artist-id`	Artist identifier (required)
`data-project-id`	Project identifier
`data-meta-pixel-id`	Meta/Facebook Pixel ID
`data-tiktok-pixel-id`	TikTok Pixel ID
`data-google-ads-id`	Google Ads ID
`data-forward-pageview`	Forward pageviews (`true`/`false`)
`data-forward-purchase`	Forward purchases (`true`/`false`)
`data-forward-custom`	Custom events (comma-separated)
`data-exclude-pages`	URL patterns to exclude (comma-separated)
`data-debug`	Enable debug mode

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      artistPixel                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              First-Party Collection                  │    │
│  │         (Always runs, stores in Firestore)          │    │
│  └─────────────────────────────────────────────────────┘    │
│                            │                                 │
│                     consent check                            │
│                            │                                 │
│  ┌─────────────────────────▼─────────────────────────────┐  │
│  │           Platform Pixel Orchestrator                  │  │
│  │        (Only when marketing consent granted)           │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐             │  │
│  │  │   Meta   │  │  TikTok  │  │  Google  │             │  │
│  │  │  Pixel   │  │  Pixel   │  │   Ads    │             │  │
│  │  └──────────┘  └──────────┘  └──────────┘             │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Documentation

Quick Reference - Common patterns and quick setup
GTM Integration - Google Tag Manager setup

License

MIT

Keywords

FAQs

What is @hifilabs/pixel?

Is @hifilabs/pixel well maintained?

Package last updated on 12 Feb 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@hifilabs/pixel

@hifilabs/pixel (artistPixel)

Features