Install Pirsch | OpsBlu Docs

Install Pirsch

Install the Pirsch tracking tag or SDK — step-by-step embed instructions, verification, and troubleshooting.

Overview

Installing Pirsch analytics is straightforward and can be accomplished in minutes. Pirsch offers multiple installation methods to accommodate different website architectures and technical requirements, from simple HTML script tags to npm packages for modern JavaScript frameworks.

This guide walks you through each installation method, helping you choose the right approach for your website and get Pirsch running quickly while maintaining user privacy and GDPR compliance without requiring cookie consent banners.

Prerequisites

Before installing Pirsch, ensure you have:

  1. Pirsch Account: Sign up at pirsch.io
  2. Website Domain: Add your domain in the Pirsch dashboard
  3. Identification Code: Get your unique code from Settings > Websites
  4. Website Access: Ability to add code to your website's HTML

Installation Methods

The simplest installation method for standard websites. This tracks pageviews automatically but doesn't include custom event tracking.

Step 1: Get Your Identification Code

  1. Log into your Pirsch dashboard
  2. Navigate to Settings > Websites
  3. Copy your identification code

Step 2: Add Script to Your Website

Add this script tag in the <head> or before the closing </body> tag:

<script defer src="https://api.pirsch.io/pirsch.js"
  id="pirschjs"
  data-code="YOUR_IDENTIFICATION_CODE"></script>

Example in HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>

  <!-- Pirsch Analytics -->
  <script defer src="https://api.pirsch.io/pirsch.js"
    id="pirschjs"
    data-code="YOUR_IDENTIFICATION_CODE"></script>
</head>
<body>
  <!-- Your website content -->
</body>
</html>

Why Use defer?

The defer attribute ensures the script:

  • Downloads in parallel with HTML parsing
  • Executes after the DOM is ready
  • Doesn't block page rendering
  • Improves page load performance

Method 2: Extended Script (With Custom Events)

Use this version if you need to track custom events, button clicks, form submissions, or other user interactions.

<script defer src="https://api.pirsch.io/pirsch-extended.js"
  id="pirschextendedjs"
  data-code="YOUR_IDENTIFICATION_CODE"></script>

Full example with event tracking:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>My Website</title>

  <!-- Pirsch Extended Analytics -->
  <script defer src="https://api.pirsch.io/pirsch-extended.js"
    id="pirschextendedjs"
    data-code="YOUR_IDENTIFICATION_CODE"></script>
</head>
<body>
  <button id="cta-button">Subscribe Now</button>

  <script>
    // Track button click
    document.getElementById('cta-button').addEventListener('click', function() {
      pirsch('CTA Click', {
        meta: {
          button: 'Subscribe',
          location: 'Hero'
        }
      });
    });
  </script>
</body>
</html>

Method 3: Script Configuration Options

Customize Pirsch behavior with data attributes:

<script defer src="https://api.pirsch.io/pirsch-extended.js"
  id="pirschextendedjs"
  data-code="YOUR_CODE"
  data-disable-cookies="true"
  data-dev="localhost,dev.example.com,*.test"
  data-disable-scripts="true"
  data-disable-outbound-links="true"></script>

Configuration Options:

Attribute Description Default
data-code Your identification code (required) -
data-disable-cookies Disable all cookies false
data-dev Comma-separated domains to ignore -
data-disable-scripts Disable automatic script tracking false
data-disable-outbound-links Disable outbound link tracking false

Method 4: NPM Package for JavaScript Frameworks

For modern JavaScript frameworks like React, Vue, or Next.js, you can use npm packages.

Installation

npm install pirsch-sdk

React Implementation

import { useEffect } from 'react';
import { Pirsch } from 'pirsch-sdk';

function App() {
  useEffect(() => {
    const pirsch = new Pirsch({
      code: 'YOUR_IDENTIFICATION_CODE',
      dev: process.env.NODE_ENV === 'development'
    });

    // Track pageview
    pirsch.hit();

    // Track custom event
    pirsch.event('App Loaded', {
      framework: 'React',
      version: '18.0'
    });
  }, []);

  return <div>My App</div>;
}

Vue.js Implementation

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import { Pirsch } from 'pirsch-sdk';

const app = createApp(App);

// Initialize Pirsch
const pirsch = new Pirsch({
  code: 'YOUR_IDENTIFICATION_CODE'
});

// Make available globally
app.config.globalProperties.$pirsch = pirsch;

app.mount('#app');

Next.js Implementation

// pages/_app.js
import { useEffect } from 'react';
import { useRouter } from 'next/router';

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

  useEffect(() => {
    // Load Pirsch script
    const script = document.createElement('script');
    script.src = 'https://api.pirsch.io/pirsch.js';
    script.defer = true;
    script.setAttribute('id', 'pirschjs');
    script.setAttribute('data-code', process.env.NEXT_PUBLIC_PIRSCH_CODE);
    document.head.appendChild(script);

    // Track route changes
    const handleRouteChange = () => {
      if (window.pirsch) {
        window.pirsch.hit();
      }
    };

    router.events.on('routeChangeComplete', handleRouteChange);

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

  return <Component {...pageProps} />;
}

export default MyApp;

Method 5: Server-Side Tracking

For applications that need ad-blocker immunity or server-rendered tracking.

Get Access Token

  1. Go to Pirsch dashboard
  2. Navigate to Settings > API
  3. Generate a new access token
  4. Store securely in environment variables

Node.js/Express Example

const axios = require('axios');

async function trackPageview(req) {
  try {
    await axios.post('https://api.pirsch.io/api/v1/hit', {
      url: `https://example.com${req.path}`,
      ip: req.ip,
      user_agent: req.headers['user-agent'],
      accept_language: req.headers['accept-language'],
      referrer: req.headers['referer'] || ''
    }, {
      headers: {
        'Authorization': `Bearer ${process.env.PIRSCH_ACCESS_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
  } catch (error) {
    console.error('Pirsch tracking failed:', error.message);
  }
}

// Middleware
app.use((req, res, next) => {
  trackPageview(req);
  next();
});

Platform-Specific Installation

WordPress

Option 1: Code Insertion Plugin

  1. Install "Insert Headers and Footers" plugin
  2. Go to Settings > Insert Headers and Footers
  3. Paste Pirsch script in the header section

Option 2: Theme Functions

Add to your theme's functions.php:

function add_pirsch_analytics() {
    ?>
    <script defer src="https://api.pirsch.io/pirsch.js"
      id="pirschjs"
      data-code="YOUR_CODE"></script>
    <?php
}
add_action('wp_head', 'add_pirsch_analytics');

Shopify

  1. Go to your Shopify admin
  2. Navigate to Online Store > Themes
  3. Click Actions > Edit code
  4. Open theme.liquid
  5. Add Pirsch script before </head>
<!-- Pirsch Analytics -->
<script defer src="https://api.pirsch.io/pirsch.js"
  id="pirschjs"
  data-code="YOUR_CODE"></script>

Webflow

  1. Go to Project Settings
  2. Click Custom Code tab
  3. Paste Pirsch script in "Head Code" section
  4. Publish your site

Squarespace

  1. Go to Settings > Advanced > Code Injection
  2. Paste Pirsch script in Header section
  3. Save changes

Ghost

  1. Go to Settings > Code Injection
  2. Paste Pirsch script in Site Header section
  3. Save changes

Validation and Testing

Step 1: Verify Script Installation

Check Script Load:

  1. Open your website
  2. Press F12 to open Developer Tools
  3. Go to Network tab
  4. Refresh the page
  5. Filter by "pirsch"
  6. Verify pirsch.js or pirsch-extended.js loads successfully (Status: 200)

Check Console:

// Run in browser console
console.log(typeof pirsch !== 'undefined' ? 'Pirsch loaded successfully' : 'Pirsch not loaded');

Step 2: Test Pageview Tracking

  1. Visit your website
  2. Open Network tab in DevTools
  3. Filter by "pirsch.io"
  4. Navigate to a different page
  5. Look for POST requests to api.pirsch.io/api/v1/hit
  6. Verify request returns 200 status

Step 3: Verify in Dashboard

  1. Wait 5-10 minutes for data processing
  2. Log into Pirsch dashboard
  3. Go to your website's analytics
  4. Check for recent pageviews in real-time or hourly stats
  5. Verify page paths and referrers appear correctly

Step 4: Test Custom Events (Extended Script Only)

// Run in browser console
pirsch('Test Event', { meta: { test: true } });

Check Events section in dashboard after 5-10 minutes.

Common Installation Issues

Script Not Loading

Issue: Pirsch script doesn't load in Network tab

Solutions:

  • Verify the script URL is correct (https://api.pirsch.io/pirsch.js)
  • Check for ad blockers or privacy extensions
  • Ensure your firewall isn't blocking api.pirsch.io
  • Verify script tag is properly closed

No Data in Dashboard

Issue: Pageviews don't appear in Pirsch dashboard

Solutions:

  • Wait 5-10 minutes for data processing
  • Verify identification code is correct
  • Check that domain matches what's configured in Pirsch
  • Ensure you're not blocking your own visits (check dev exclusions)

Events Not Firing

Issue: Custom events don't appear

Solutions:

  • Confirm you're using pirsch-extended.js, not pirsch.js
  • Verify pirsch() function is available: typeof pirsch
  • Check browser console for JavaScript errors
  • Ensure events are in correct format with meta: {} object

Duplicate Pageviews

Issue: Each page counts as 2 pageviews

Solutions:

  • Check for duplicate script tags in HTML
  • Verify you're not using both client-side and server-side tracking
  • Ensure SPA route tracking isn't duplicating hits

Troubleshooting

Issue Cause Solution
Script blocked by ad blocker Browser extension Use server-side tracking or proxy
403 Forbidden error Wrong identification code Verify code in Pirsch dashboard
Mixed content warning HTTP on HTTPS site Ensure script URL uses HTTPS
Script not executing Missing defer/async Add defer attribute to script tag
Events undefined Basic script loaded Replace with pirsch-extended.js
CSP violations Content Security Policy Add api.pirsch.io to CSP script-src
Double tracking on SPA Manual + automatic tracking Remove duplicate hit() calls
No data on localhost Dev domain excluded Remove localhost from data-dev attribute

Best Practices

  1. Use defer Attribute: Always use defer for optimal performance
  2. Place in <head>: Load scripts early for accurate tracking
  3. Environment Variables: Store codes/tokens in env vars, not source code
  4. Dev Exclusions: Use data-dev to exclude development environments
  5. Test Thoroughly: Verify tracking in staging before production deployment
  6. Monitor Errors: Set up error logging for tracking failures
  7. Update Regularly: Keep SDK packages up to date
  8. Document Setup: Record which installation method you used

Security Considerations

  1. Never Commit Tokens: Don't commit access tokens to version control
  2. Use Environment Variables: Store sensitive data in .env files
  3. Restrict API Tokens: Generate separate tokens for different environments
  4. Monitor Usage: Regularly check for unusual API activity
  5. HTTPS Only: Always use HTTPS for script sources
Back to top