January 20269 min read

Installation Guide

Step-by-step instructions for installing pxlpeak across different platforms, frameworks, and environments.

Overview

pxlpeak can be installed in multiple ways depending on your tech stack. This guide covers every installation method from simple script tags to framework-specific integrations.

Installation Methods

code

Choose Your Installation Method:

┌─────────────────────────────────────────────────────────────┐
│                    pxlpeak Installation                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Script    │  │     npm     │  │   Server    │        │
│  │    Tag      │  │   Package   │  │    SDK      │        │
│  │  (Easiest)  │  │ (JS/TS)     │  │  (Node.js)  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Google    │  │   Segment   │  │   Custom    │        │
│  │ Tag Manager │  │ Integration │  │    API      │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Script Tag Installation

The simplest way to add pxlpeak to any website.

Basic Installation

code

<!-- Add before </head> for best performance -->
<script
  defer
  src="https://cdn.pxlpeak.com/tracker.js"
  data-site="YOUR_SITE_ID"
></script>

With Configuration Options

code

<script
  defer
  src="https://cdn.pxlpeak.com/tracker.js"
  data-site="YOUR_SITE_ID"
  data-track-pageviews="true"
  data-track-outbound="true"
  data-track-downloads="true"
  data-respect-dnt="true"
  data-hash-mode="false"
  data-domain="yourdomain.com"
></script>

Configuration Attributes

| Attribute | Default | Description | |-----------|---------|-------------| | data-site | Required | Your unique site ID | | data-track-pageviews | true | Auto-track page views | | data-track-outbound | true | Track outbound link clicks | | data-track-downloads | true | Track file downloads | | data-respect-dnt | false | Respect Do Not Track header | | data-hash-mode | false | Track hash changes as pageviews | | data-domain | Auto | Override domain for tracking | | data-api-host | api.pxlpeak.com | Custom API endpoint |

Manual Event Tracking

code

<script>
  // Track custom events after tracker loads
  window.pxlpeak = window.pxlpeak || [];

  // Queue events before tracker loads
  pxlpeak.push(['track', 'button_clicked', { button: 'signup' }]);

  // Or use the API after load
  document.addEventListener('pxlpeak:ready', function() {
    pxlpeak.track('page_viewed', {
      category: 'blog',
      author: 'John Doe'
    });
  });
</script>

npm Package Installation

For JavaScript/TypeScript applications with a build process.

Installation

code

# npm
npm install @pxlpeak/tracker

# yarn
yarn add @pxlpeak/tracker

# pnpm
pnpm add @pxlpeak/tracker

# bun
bun add @pxlpeak/tracker

Basic Usage

code

import { init, track, identify } from '@pxlpeak/tracker';

// Initialize the tracker
init({
  siteId: 'YOUR_SITE_ID',
  publicKey: 'pk_live_xxxxxxxxxxxxx',

  // Options
  trackPageviews: true,
  trackOutbound: true,
  trackDownloads: true,
  respectDNT: false,
  debug: process.env.NODE_ENV === 'development'
});

// Track events
track('button_clicked', {
  button: 'signup',
  location: 'header'
});

// Identify users
identify('user_123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'pro'
});

TypeScript Support

code

import { init, track, identify } from '@pxlpeak/tracker';
import type { TrackOptions, UserProperties } from '@pxlpeak/tracker';

// Fully typed API
const options: TrackOptions = {
  siteId: 'YOUR_SITE_ID',
  publicKey: 'pk_live_xxxxxxxxxxxxx'
};

init(options);

// Type-safe event tracking
interface PurchaseEvent {
  orderId: string;
  revenue: number;
  currency: string;
  products: Array<{
    id: string;
    name: string;
    price: number;
    quantity: number;
  }>;
}

track<PurchaseEvent>('purchase_completed', {
  orderId: 'ORD-12345',
  revenue: 99.99,
  currency: 'USD',
  products: [
    { id: 'SKU-1', name: 'Pro Plan', price: 99.99, quantity: 1 }
  ]
});

Framework-Specific Installation

React

code

npm install @pxlpeak/react

code

// App.tsx or _app.tsx
import { PxlpeakProvider, useTrack } from '@pxlpeak/react';

function App() {
  return (
    <PxlpeakProvider
      siteId="YOUR_SITE_ID"
      publicKey="pk_live_xxxxxxxxxxxxx"
      options={{
        trackPageviews: true,
        debug: process.env.NODE_ENV === 'development'
      }}
    >
      <YourApp />
    </PxlpeakProvider>
  );
}

// In components
function SignupButton() {
  const track = useTrack();

  const handleClick = () => {
    track('signup_clicked', { location: 'hero' });
  };

  return <button onClick={handleClick}>Sign Up</button>;
}

Next.js (App Router)

code

npm install @pxlpeak/next

code

// app/layout.tsx
import { PxlpeakScript } from '@pxlpeak/next';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <PxlpeakScript
          siteId={process.env.NEXT_PUBLIC_PXLPEAK_SITE_ID!}
          publicKey={process.env.NEXT_PUBLIC_PXLPEAK_KEY!}
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

// For page view tracking with App Router
// app/providers.tsx
'use client';

import { PxlpeakProvider } from '@pxlpeak/next';
import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';

export function Providers({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    // Track page views on route change
    window.pxlpeak?.track('page_viewed', {
      path: pathname,
      search: searchParams.toString()
    });
  }, [pathname, searchParams]);

  return <>{children}</>;
}

Next.js (Pages Router)

code

// pages/_app.tsx
import { useEffect } from 'react';
import { useRouter } from 'next/router';
import Script from 'next/script';

function MyApp({ Component, pageProps }) {
  const router = useRouter();

  useEffect(() => {
    // Track page views on route change
    const handleRouteChange = (url: string) => {
      window.pxlpeak?.track('page_viewed', { path: url });
    };

    router.events.on('routeChangeComplete', handleRouteChange);
    return () => {
      router.events.off('routeChangeComplete', handleRouteChange);
    };
  }, [router.events]);

  return (
    <>
      <Script
        src="https://cdn.pxlpeak.com/tracker.js"
        data-site={process.env.NEXT_PUBLIC_PXLPEAK_SITE_ID}
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Vue.js

code

npm install @pxlpeak/vue

code

// main.ts
import { createApp } from 'vue';
import { PxlpeakPlugin } from '@pxlpeak/vue';
import App from './App.vue';

const app = createApp(App);

app.use(PxlpeakPlugin, {
  siteId: 'YOUR_SITE_ID',
  publicKey: 'pk_live_xxxxxxxxxxxxx',
  router: router, // Vue Router instance for auto pageview tracking
  options: {
    trackPageviews: true,
    debug: import.meta.env.DEV
  }
});

app.mount('#app');

// In components
<script setup>
import { useTrack } from '@pxlpeak/vue';

const track = useTrack();

const handleClick = () => {
  track('button_clicked', { button: 'signup' });
};
</script>

Nuxt 3

code

npm install @pxlpeak/nuxt

code

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pxlpeak/nuxt'],

  pxlpeak: {
    siteId: process.env.PXLPEAK_SITE_ID,
    publicKey: process.env.PXLPEAK_PUBLIC_KEY,
    trackPageviews: true,
    debug: process.env.NODE_ENV === 'development'
  }
});

// In components
<script setup>
const { track } = usePxlpeak();

const handleClick = () => {
  track('button_clicked', { button: 'signup' });
};
</script>

SvelteKit

code

npm install @pxlpeak/svelte

code

<!-- src/routes/+layout.svelte -->
<script>
  import { Pxlpeak } from '@pxlpeak/svelte';
  import { page } from '$app/stores';
  import { afterNavigate } from '$app/navigation';

  afterNavigate(() => {
    window.pxlpeak?.track('page_viewed', {
      path: $page.url.pathname
    });
  });
</script>

<Pxlpeak
  siteId={import.meta.env.VITE_PXLPEAK_SITE_ID}
  publicKey={import.meta.env.VITE_PXLPEAK_KEY}
/>

<slot />

Astro

code

npm install @pxlpeak/astro

code

// astro.config.mjs
import { defineConfig } from 'astro/config';
import pxlpeak from '@pxlpeak/astro';

export default defineConfig({
  integrations: [
    pxlpeak({
      siteId: import.meta.env.PXLPEAK_SITE_ID,
      publicKey: import.meta.env.PXLPEAK_PUBLIC_KEY
    })
  ]
});

Remix

code

npm install @pxlpeak/remix

code

// app/root.tsx
import { PxlpeakScripts, usePxlpeakPageview } from '@pxlpeak/remix';

export default function App() {
  // Auto-track page views
  usePxlpeakPageview();

  return (
    <html lang="en">
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <Outlet />
        <PxlpeakScripts
          siteId={process.env.PXLPEAK_SITE_ID}
          publicKey={process.env.PXLPEAK_PUBLIC_KEY}
        />
        <Scripts />
      </body>
    </html>
  );
}

Server-Side Installation

Node.js

code

npm install @pxlpeak/node

code

import { Pxlpeak } from '@pxlpeak/node';

const pxlpeak = new Pxlpeak({
  secretKey: process.env.PXLPEAK_SECRET_KEY
});

// Track server-side events
await pxlpeak.track({
  event: 'order_completed',
  userId: 'user_123',
  properties: {
    orderId: 'ORD-12345',
    revenue: 99.99,
    currency: 'USD'
  },
  // Optional: Include request context
  context: {
    ip: req.ip,
    userAgent: req.headers['user-agent']
  }
});

// Identify users
await pxlpeak.identify({
  userId: 'user_123',
  traits: {
    email: 'user@example.com',
    name: 'John Doe',
    plan: 'enterprise'
  }
});

// Batch events for efficiency
await pxlpeak.batch([
  { type: 'track', event: 'event_1', userId: 'user_1', properties: {} },
  { type: 'track', event: 'event_2', userId: 'user_2', properties: {} },
  { type: 'identify', userId: 'user_3', traits: { plan: 'pro' } }
]);

Python

code

pip install pxlpeak

code

from pxlpeak import Pxlpeak

pxlpeak = Pxlpeak(secret_key=os.environ['PXLPEAK_SECRET_KEY'])

# Track events
pxlpeak.track(
    user_id='user_123',
    event='purchase_completed',
    properties={
        'revenue': 99.99,
        'order_id': 'ORD-12345'
    }
)

# Identify users
pxlpeak.identify(
    user_id='user_123',
    traits={
        'email': 'user@example.com',
        'name': 'John Doe'
    }
)

# Flush events (send immediately)
pxlpeak.flush()

# Graceful shutdown
pxlpeak.shutdown()

Ruby

code

gem install pxlpeak

code

require 'pxlpeak'

Pxlpeak.configure do |config|
  config.secret_key = ENV['PXLPEAK_SECRET_KEY']
end

# Track events
Pxlpeak.track(
  user_id: 'user_123',
  event: 'purchase_completed',
  properties: {
    revenue: 99.99,
    order_id: 'ORD-12345'
  }
)

# Identify users
Pxlpeak.identify(
  user_id: 'user_123',
  traits: {
    email: 'user@example.com',
    name: 'John Doe'
  }
)

PHP

code

composer require pxlpeak/pxlpeak-php

code

<?php
use Pxlpeak\Pxlpeak;

$pxlpeak = new Pxlpeak([
    'secret_key' => getenv('PXLPEAK_SECRET_KEY')
]);

// Track events
$pxlpeak->track([
    'userId' => 'user_123',
    'event' => 'purchase_completed',
    'properties' => [
        'revenue' => 99.99,
        'orderId' => 'ORD-12345'
    ]
]);

// Identify users
$pxlpeak->identify([
    'userId' => 'user_123',
    'traits' => [
        'email' => 'user@example.com',
        'name' => 'John Doe'
    ]
]);

// Flush events
$pxlpeak->flush();

Google Tag Manager

Container Setup

Create a new tag in GTM
Choose "Custom HTML" tag type
Add the pxlpeak script:

code

<script>
  (function() {
    var script = document.createElement('script');
    script.defer = true;
    script.src = 'https://cdn.pxlpeak.com/tracker.js';
    script.setAttribute('data-site', '{{PXLPEAK_SITE_ID}}');
    document.head.appendChild(script);
  })();
</script>

Set trigger to "All Pages"

Custom Event Tracking

Create a custom HTML tag for event tracking:

code

<script>
  window.pxlpeak = window.pxlpeak || [];
  pxlpeak.push(['track', '{{Event Name}}', {
    category: '{{Event Category}}',
    label: '{{Event Label}}',
    value: '{{Event Value}}'
  }]);
</script>

Data Layer Integration

code

<script>
  // Listen for dataLayer events
  window.addEventListener('pxlpeak:ready', function() {
    // Push existing dataLayer events
    if (window.dataLayer) {
      window.dataLayer.forEach(function(event) {
        if (event.event && event.event !== 'gtm.js') {
          pxlpeak.track(event.event, event);
        }
      });
    }

    // Listen for new events
    var originalPush = window.dataLayer.push;
    window.dataLayer.push = function() {
      var args = Array.prototype.slice.call(arguments);
      args.forEach(function(event) {
        if (event.event) {
          pxlpeak.track(event.event, event);
        }
      });
      return originalPush.apply(window.dataLayer, args);
    };
  });
</script>

Verification

Verify Installation

code

// Check if tracker is loaded
if (window.pxlpeak) {
  console.log('pxlpeak tracker loaded');
}

// Listen for ready event
window.addEventListener('pxlpeak:ready', () => {
  console.log('pxlpeak ready');

  // Test tracking
  pxlpeak.track('test_event', { test: true });
});

// Debug mode
pxlpeak.debug(true);

Real-Time Debugger

code

// Enable verbose debugging
pxlpeak.debug({
  enabled: true,
  logLevel: 'verbose', // error, warn, info, verbose
  showInConsole: true,
  highlightTrackedElements: true
});

// View debug panel
pxlpeak.showDebugger();

Verification Checklist

code

## Installation Verification

### Basic Checks
- [ ] Script loads without errors in console
- [ ] Network tab shows requests to api.pxlpeak.com
- [ ] Real-time dashboard shows activity

### Pageview Tracking
- [ ] Page views appear in real-time view
- [ ] URL and title are correct
- [ ] Referrer is captured

### Event Tracking
- [ ] Custom events fire correctly
- [ ] Event properties are included
- [ ] User identification works

### Cross-Browser
- [ ] Chrome/Edge works
- [ ] Firefox works
- [ ] Safari works
- [ ] Mobile browsers work

Troubleshooting

Common Issues

| Issue | Cause | Solution | |-------|-------|----------| | Script not loading | Blocked by ad blocker | Use custom domain or first-party tracking | | Events not appearing | Wrong site ID | Verify site ID in dashboard | | Duplicate events | Multiple initializations | Ensure single init call | | Missing pageviews | SPA routing not tracked | Add router integration | | CORS errors | Wrong API host | Check API host configuration |

Debug Commands

code

// Check tracker status
console.log(pxlpeak.getConfig());

// View queued events
console.log(pxlpeak.getQueue());

// Force flush events
pxlpeak.flush();

// Clear local data
pxlpeak.reset();

Related Documentation:

January 20269 min read

Installation Guide

Step-by-step instructions for installing pxlpeak across different platforms, frameworks, and environments.

Overview

pxlpeak can be installed in multiple ways depending on your tech stack. This guide covers every installation method from simple script tags to framework-specific integrations.

Installation Methods

code

Choose Your Installation Method:

┌─────────────────────────────────────────────────────────────┐
│                    pxlpeak Installation                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Script    │  │     npm     │  │   Server    │        │
│  │    Tag      │  │   Package   │  │    SDK      │        │
│  │  (Easiest)  │  │ (JS/TS)     │  │  (Node.js)  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Google    │  │   Segment   │  │   Custom    │        │
│  │ Tag Manager │  │ Integration │  │    API      │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Script Tag Installation

The simplest way to add pxlpeak to any website.

Basic Installation

code

<!-- Add before </head> for best performance -->
<script
  defer
  src="https://cdn.pxlpeak.com/tracker.js"
  data-site="YOUR_SITE_ID"
></script>

With Configuration Options

code

<script
  defer
  src="https://cdn.pxlpeak.com/tracker.js"
  data-site="YOUR_SITE_ID"
  data-track-pageviews="true"
  data-track-outbound="true"
  data-track-downloads="true"
  data-respect-dnt="true"
  data-hash-mode="false"
  data-domain="yourdomain.com"
></script>

Configuration Attributes

Manual Event Tracking

code

<script>
  // Track custom events after tracker loads
  window.pxlpeak = window.pxlpeak || [];

  // Queue events before tracker loads
  pxlpeak.push(['track', 'button_clicked', { button: 'signup' }]);

  // Or use the API after load
  document.addEventListener('pxlpeak:ready', function() {
    pxlpeak.track('page_viewed', {
      category: 'blog',
      author: 'John Doe'
    });
  });
</script>

npm Package Installation

For JavaScript/TypeScript applications with a build process.

Installation

code

# npm
npm install @pxlpeak/tracker

# yarn
yarn add @pxlpeak/tracker

# pnpm
pnpm add @pxlpeak/tracker

# bun
bun add @pxlpeak/tracker

Basic Usage

code

import { init, track, identify } from '@pxlpeak/tracker';

// Initialize the tracker
init({
  siteId: 'YOUR_SITE_ID',
  publicKey: 'pk_live_xxxxxxxxxxxxx',

  // Options
  trackPageviews: true,
  trackOutbound: true,
  trackDownloads: true,
  respectDNT: false,
  debug: process.env.NODE_ENV === 'development'
});

// Track events
track('button_clicked', {
  button: 'signup',
  location: 'header'
});

// Identify users
identify('user_123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'pro'
});

TypeScript Support

code

import { init, track, identify } from '@pxlpeak/tracker';
import type { TrackOptions, UserProperties } from '@pxlpeak/tracker';

// Fully typed API
const options: TrackOptions = {
  siteId: 'YOUR_SITE_ID',
  publicKey: 'pk_live_xxxxxxxxxxxxx'
};

init(options);

// Type-safe event tracking
interface PurchaseEvent {
  orderId: string;
  revenue: number;
  currency: string;
  products: Array<{
    id: string;
    name: string;
    price: number;
    quantity: number;
  }>;
}

track<PurchaseEvent>('purchase_completed', {
  orderId: 'ORD-12345',
  revenue: 99.99,
  currency: 'USD',
  products: [
    { id: 'SKU-1', name: 'Pro Plan', price: 99.99, quantity: 1 }
  ]
});

Framework-Specific Installation

React

code

npm install @pxlpeak/react

code

// App.tsx or _app.tsx
import { PxlpeakProvider, useTrack } from '@pxlpeak/react';

function App() {
  return (
    <PxlpeakProvider
      siteId="YOUR_SITE_ID"
      publicKey="pk_live_xxxxxxxxxxxxx"
      options={{
        trackPageviews: true,
        debug: process.env.NODE_ENV === 'development'
      }}
    >
      <YourApp />
    </PxlpeakProvider>
  );
}

// In components
function SignupButton() {
  const track = useTrack();

  const handleClick = () => {
    track('signup_clicked', { location: 'hero' });
  };

  return <button onClick={handleClick}>Sign Up</button>;
}

Next.js (App Router)

code

npm install @pxlpeak/next

code

// app/layout.tsx
import { PxlpeakScript } from '@pxlpeak/next';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <PxlpeakScript
          siteId={process.env.NEXT_PUBLIC_PXLPEAK_SITE_ID!}
          publicKey={process.env.NEXT_PUBLIC_PXLPEAK_KEY!}
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

// For page view tracking with App Router
// app/providers.tsx
'use client';

import { PxlpeakProvider } from '@pxlpeak/next';
import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';

export function Providers({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    // Track page views on route change
    window.pxlpeak?.track('page_viewed', {
      path: pathname,
      search: searchParams.toString()
    });
  }, [pathname, searchParams]);

  return <>{children}</>;
}

Next.js (Pages Router)

code

// pages/_app.tsx
import { useEffect } from 'react';
import { useRouter } from 'next/router';
import Script from 'next/script';

function MyApp({ Component, pageProps }) {
  const router = useRouter();

  useEffect(() => {
    // Track page views on route change
    const handleRouteChange = (url: string) => {
      window.pxlpeak?.track('page_viewed', { path: url });
    };

    router.events.on('routeChangeComplete', handleRouteChange);
    return () => {
      router.events.off('routeChangeComplete', handleRouteChange);
    };
  }, [router.events]);

  return (
    <>
      <Script
        src="https://cdn.pxlpeak.com/tracker.js"
        data-site={process.env.NEXT_PUBLIC_PXLPEAK_SITE_ID}
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Vue.js

code

npm install @pxlpeak/vue

code

// main.ts
import { createApp } from 'vue';
import { PxlpeakPlugin } from '@pxlpeak/vue';
import App from './App.vue';

const app = createApp(App);

app.use(PxlpeakPlugin, {
  siteId: 'YOUR_SITE_ID',
  publicKey: 'pk_live_xxxxxxxxxxxxx',
  router: router, // Vue Router instance for auto pageview tracking
  options: {
    trackPageviews: true,
    debug: import.meta.env.DEV
  }
});

app.mount('#app');

// In components
<script setup>
import { useTrack } from '@pxlpeak/vue';

const track = useTrack();

const handleClick = () => {
  track('button_clicked', { button: 'signup' });
};
</script>

Nuxt 3

code

npm install @pxlpeak/nuxt

code

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pxlpeak/nuxt'],

  pxlpeak: {
    siteId: process.env.PXLPEAK_SITE_ID,
    publicKey: process.env.PXLPEAK_PUBLIC_KEY,
    trackPageviews: true,
    debug: process.env.NODE_ENV === 'development'
  }
});

// In components
<script setup>
const { track } = usePxlpeak();

const handleClick = () => {
  track('button_clicked', { button: 'signup' });
};
</script>

SvelteKit

code

npm install @pxlpeak/svelte

code

<!-- src/routes/+layout.svelte -->
<script>
  import { Pxlpeak } from '@pxlpeak/svelte';
  import { page } from '$app/stores';
  import { afterNavigate } from '$app/navigation';

  afterNavigate(() => {
    window.pxlpeak?.track('page_viewed', {
      path: $page.url.pathname
    });
  });
</script>

<Pxlpeak
  siteId={import.meta.env.VITE_PXLPEAK_SITE_ID}
  publicKey={import.meta.env.VITE_PXLPEAK_KEY}
/>

<slot />

Astro

code

npm install @pxlpeak/astro

code

// astro.config.mjs
import { defineConfig } from 'astro/config';
import pxlpeak from '@pxlpeak/astro';

export default defineConfig({
  integrations: [
    pxlpeak({
      siteId: import.meta.env.PXLPEAK_SITE_ID,
      publicKey: import.meta.env.PXLPEAK_PUBLIC_KEY
    })
  ]
});

Remix

code

npm install @pxlpeak/remix

code

// app/root.tsx
import { PxlpeakScripts, usePxlpeakPageview } from '@pxlpeak/remix';

export default function App() {
  // Auto-track page views
  usePxlpeakPageview();

  return (
    <html lang="en">
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <Outlet />
        <PxlpeakScripts
          siteId={process.env.PXLPEAK_SITE_ID}
          publicKey={process.env.PXLPEAK_PUBLIC_KEY}
        />
        <Scripts />
      </body>
    </html>
  );
}

Server-Side Installation

Node.js

code

npm install @pxlpeak/node

code

import { Pxlpeak } from '@pxlpeak/node';

const pxlpeak = new Pxlpeak({
  secretKey: process.env.PXLPEAK_SECRET_KEY
});

// Track server-side events
await pxlpeak.track({
  event: 'order_completed',
  userId: 'user_123',
  properties: {
    orderId: 'ORD-12345',
    revenue: 99.99,
    currency: 'USD'
  },
  // Optional: Include request context
  context: {
    ip: req.ip,
    userAgent: req.headers['user-agent']
  }
});

// Identify users
await pxlpeak.identify({
  userId: 'user_123',
  traits: {
    email: 'user@example.com',
    name: 'John Doe',
    plan: 'enterprise'
  }
});

// Batch events for efficiency
await pxlpeak.batch([
  { type: 'track', event: 'event_1', userId: 'user_1', properties: {} },
  { type: 'track', event: 'event_2', userId: 'user_2', properties: {} },
  { type: 'identify', userId: 'user_3', traits: { plan: 'pro' } }
]);

Python

code

pip install pxlpeak

code

from pxlpeak import Pxlpeak

pxlpeak = Pxlpeak(secret_key=os.environ['PXLPEAK_SECRET_KEY'])

# Track events
pxlpeak.track(
    user_id='user_123',
    event='purchase_completed',
    properties={
        'revenue': 99.99,
        'order_id': 'ORD-12345'
    }
)

# Identify users
pxlpeak.identify(
    user_id='user_123',
    traits={
        'email': 'user@example.com',
        'name': 'John Doe'
    }
)

# Flush events (send immediately)
pxlpeak.flush()

# Graceful shutdown
pxlpeak.shutdown()

Ruby

code

gem install pxlpeak

code

require 'pxlpeak'

Pxlpeak.configure do |config|
  config.secret_key = ENV['PXLPEAK_SECRET_KEY']
end

# Track events
Pxlpeak.track(
  user_id: 'user_123',
  event: 'purchase_completed',
  properties: {
    revenue: 99.99,
    order_id: 'ORD-12345'
  }
)

# Identify users
Pxlpeak.identify(
  user_id: 'user_123',
  traits: {
    email: 'user@example.com',
    name: 'John Doe'
  }
)

PHP

code

composer require pxlpeak/pxlpeak-php

code

<?php
use Pxlpeak\Pxlpeak;

$pxlpeak = new Pxlpeak([
    'secret_key' => getenv('PXLPEAK_SECRET_KEY')
]);

// Track events
$pxlpeak->track([
    'userId' => 'user_123',
    'event' => 'purchase_completed',
    'properties' => [
        'revenue' => 99.99,
        'orderId' => 'ORD-12345'
    ]
]);

// Identify users
$pxlpeak->identify([
    'userId' => 'user_123',
    'traits' => [
        'email' => 'user@example.com',
        'name' => 'John Doe'
    ]
]);

// Flush events
$pxlpeak->flush();

Google Tag Manager

Container Setup

Create a new tag in GTM
Choose "Custom HTML" tag type
Add the pxlpeak script:

code

<script>
  (function() {
    var script = document.createElement('script');
    script.defer = true;
    script.src = 'https://cdn.pxlpeak.com/tracker.js';
    script.setAttribute('data-site', '{{PXLPEAK_SITE_ID}}');
    document.head.appendChild(script);
  })();
</script>

Set trigger to "All Pages"

Custom Event Tracking

Create a custom HTML tag for event tracking:

code

<script>
  window.pxlpeak = window.pxlpeak || [];
  pxlpeak.push(['track', '{{Event Name}}', {
    category: '{{Event Category}}',
    label: '{{Event Label}}',
    value: '{{Event Value}}'
  }]);
</script>

Data Layer Integration

code

<script>
  // Listen for dataLayer events
  window.addEventListener('pxlpeak:ready', function() {
    // Push existing dataLayer events
    if (window.dataLayer) {
      window.dataLayer.forEach(function(event) {
        if (event.event && event.event !== 'gtm.js') {
          pxlpeak.track(event.event, event);
        }
      });
    }

    // Listen for new events
    var originalPush = window.dataLayer.push;
    window.dataLayer.push = function() {
      var args = Array.prototype.slice.call(arguments);
      args.forEach(function(event) {
        if (event.event) {
          pxlpeak.track(event.event, event);
        }
      });
      return originalPush.apply(window.dataLayer, args);
    };
  });
</script>

Verification

Verify Installation

code

// Check if tracker is loaded
if (window.pxlpeak) {
  console.log('pxlpeak tracker loaded');
}

// Listen for ready event
window.addEventListener('pxlpeak:ready', () => {
  console.log('pxlpeak ready');

  // Test tracking
  pxlpeak.track('test_event', { test: true });
});

// Debug mode
pxlpeak.debug(true);

Real-Time Debugger

code

// Enable verbose debugging
pxlpeak.debug({
  enabled: true,
  logLevel: 'verbose', // error, warn, info, verbose
  showInConsole: true,
  highlightTrackedElements: true
});

// View debug panel
pxlpeak.showDebugger();

Verification Checklist

code

## Installation Verification

### Basic Checks
- [ ] Script loads without errors in console
- [ ] Network tab shows requests to api.pxlpeak.com
- [ ] Real-time dashboard shows activity

### Pageview Tracking
- [ ] Page views appear in real-time view
- [ ] URL and title are correct
- [ ] Referrer is captured

### Event Tracking
- [ ] Custom events fire correctly
- [ ] Event properties are included
- [ ] User identification works

### Cross-Browser
- [ ] Chrome/Edge works
- [ ] Firefox works
- [ ] Safari works
- [ ] Mobile browsers work

Troubleshooting

Common Issues

Debug Commands

code

// Check tracker status
console.log(pxlpeak.getConfig());

// View queued events
console.log(pxlpeak.getQueue());

// Force flush events
pxlpeak.flush();

// Clear local data
pxlpeak.reset();

Related Documentation: