Pier39 Conversion Tracking SDK

A lightweight, easy-to-integrate conversion tracking pixel for accurate measurement of user actions such as purchases, sign-ups, and other valuable events.

Quick Start

1. Add the Pixel Base Code

Place the following script before the closing </head> tag on every page where you want tracking to be available:

<script>
  (function(w,d,s,u,n,a){
    w['Pier39PixelObject'] = n;
    w[n] = w[n] || function() {
      (w[n].q = w[n].q || []).push(arguments);
    };
    a = d.createElement(s);
    a.async = true;
    a.src = u;
    var m = d.getElementsByTagName(s)[0];
    m.parentNode.insertBefore(a, m);
  })(window, document, 'script', 'https://cdn.pier39.ai/pixel.js', 'pier39');
</script>

2. Track a Conversion Event

To record a conversion, place the following script on the page where the conversion occurs (e.g., post-checkout or signup confirmation):

<script>
  pier39('track', 'conversion', {
    eventId: 'UNIQUE_EVENT_UUID', // Replace with your actual event UUID
  });
</script>

3. Test the Integration (Optional but Recommended)

While testing, add the test: true flag to the tracking call. This ensures the event is logged in test mode and won't affect live reporting.

<script>
  pier39('track', 'conversion', {
    eventId: 'unique_event_uuid',
    test: true
  });
</script>

When using the test flag, you'll see a message like "Test conversion tracked" logged in your browser's developer console, confirming the pixel is active.

Features

• Lightweight: Minimal impact on page load times
• Asynchronous: Non-blocking script loading
• Queue System: Tracks events even if called before script loads
• Test Mode: Safe testing without affecting production data
• Error Handling: Graceful failure with comprehensive logging
• Retry Logic: Automatic retries for failed requests
• TypeScript: Fully typed for better development experience

API Reference

pier39(command, eventType, data)

Parameters

• command (string): The action to perform. Currently supports 'track'.
• eventType (string): The type of event. Currently supports 'conversion'.
• data (object): Event data containing:
  • eventId (string, required): Unique identifier for the event
  • test (boolean, optional): Set to true for testing purposes
  • timestamp (number, optional): Custom timestamp (defaults to current time)
  • url (string, optional): Custom URL (defaults to current page URL)
  • userAgent (string, optional): Custom user agent (defaults to browser user agent)

Examples

// Basic conversion tracking
pier39('track', 'conversion', {
  eventId: 'purchase-12345'
});

// Test conversion (won't affect live data)
pier39('track', 'conversion', {
  eventId: 'test-purchase-12345',
  test: true
});

// Conversion with custom data
pier39('track', 'conversion', {
  eventId: 'signup-67890',
  timestamp: Date.now(),
  url: 'https://example.com/signup-complete'
});

Development

Prerequisites

• Node.js (>= 14.0.0)
• npm

Setup

# Install dependencies
npm install

# Build the SDK
npm run build

# Build the pixel loader
npm run build:loader

# Start development server
npm run dev

# Run tests
npm run test

# Type checking
npm run type-check

# Lint code
npm run lint

# Format code
npm run format

Project Structure

src/
├── api/                 # API client and types
├── core/                # Core SDK functionality
├── utils/               # Utilities (logger, etc.)
├── types.ts            # Main type definitions
├── environments.ts     # Environment configuration
├── constants.ts        # Constants and defaults
└── index.ts           # Main entry point

integration/
└── pixel-loader.ts    # Browser pixel loader script

webpack/               # Build configurations
public/               # Test page for development
tests/               # Test files

Building

The build process creates two main outputs:

1. dist/pixel.js: The main SDK bundle loaded by the pixel
2. dist/loader/pixel-loader.min.js: The minimal loader script (embedded in the pixel code)

Testing

Open http://localhost:3000 when running the dev server to access the test page with interactive conversion tracking examples.

Configuration

Environments

The SDK supports multiple environments:

• Production: https://cdn.pier39.ai/pixel.js
• Staging: https://cdn-staging.pier39.ai/pixel.js
• Development: https://cdn-dev.pier39.ai/pixel.js

Customization

The SDK can be initialized with custom configuration:

// This is handled automatically by the pixel loader
window.Pier39ConversionSDK.initializeSDK({
  environment: 'production', // 'production' | 'staging' | 'development'
  isTestMode: false
});

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• Internet Explorer 11+ (with polyfills)

Security

• All requests are sent over HTTPS
• No personally identifiable information is collected by default
• Event IDs should not contain sensitive data

License

ISC License