Cross-Platform Compressor

A lightweight utility for compressing and encoding UTM parameters and tracking data.

Features

• Compresses UTM parameters and tracking IDs (e.g., gclid, fbclid)
• Supports any custom parameters beyond standard UTM parameters
• Uses efficient key/value mapping for common values
• Provides Base62 encoding for compact representation
• Written in TypeScript with full type definitions
• Works in both Node.js and browser environments

Installation

npm install cross-platform-compressor

or

yarn add cross-platform-compressor

Usage

Basic Usage

import { CrossPlatformCompressor } from "cross-platform-compressor";

// Example: Encode UTM parameters
const result = CrossPlatformCompressor.encode({
  utm_source: "google",
  utm_medium: "cpc",
  utm_campaign: "spring_sale",
  utm_content: "banner",
  utm_term: "discount",
  gclid: "Cj0KCQjw_12345678",
});

// Result will be a compressed string in base62 encoding
console.log(result);

Using Custom Parameters

import { CrossPlatformCompressor } from "cross-platform-compressor";

// Example: Encode UTM parameters along with custom parameters
const result = CrossPlatformCompressor.encode({
  utm_source: "google",
  utm_medium: "cpc",
  // Custom parameters - any key/value pairs are supported
  product_id: "12345",
  category: "electronics",
  referrer: "partner_site",
  visitor_type: "new",
});

// Result will include both standard and custom parameters
console.log(result);

TypeScript Usage

import {
  CrossPlatformCompressor,
  CompressionData,
} from "cross-platform-compressor";

const trackingData: CompressionData = {
  utm_source: "facebook",
  utm_medium: "social",
  utm_campaign: "holiday_special",
  // Any custom parameters
  region: "north_america",
  language: "en",
};

const encodedData = CrossPlatformCompressor.encode(trackingData);

Supported Parameters

The library supports the following tracking parameters as well as any custom parameters you need:

| Parameter | Description | | ------------ | ----------------------------------------------- | | utm_source | Identifies which site sent the traffic | | utm_medium | The marketing medium (e.g., cpc, banner, email) | | utm_campaign | The specific campaign name | | utm_content | Identifies what specifically was clicked | | utm_term | Identifies search terms | | utm_id | Campaign ID | | utm_cid | Campaign ID (alternative) | | gad_source | Google Ads source | | gclid | Google Click Identifier | | fbclid | Facebook Click Identifier | | msclkid | Microsoft Click Identifier | | * | Any custom parameter key/value pairs |

How It Works

1. Parameter key mapping: Long parameter names are mapped to shorter ones (predefined parameters) or kept as-is (custom parameters)
2. Value compression: Common values are mapped to shorter representations
3. Number compression: Numbers are formatted with delimiters for better compression
4. Data compression: The resulting JSON is compressed using GZIP
5. Base62 encoding: Finally, the compressed data is encoded to a base62 string

Browser Compatibility

The library is compatible with all modern browsers and environments.

License

MIT