# Whop Ads Tracking

Track conversions from your funnel pages to the Whop Pixel using the HandL JS library.

# Base Installation

### Prerequisites

- HandL JS library must be loaded on your page
- You must have a Whop Account ID from your Whop Dashboard

### Step 1: Get Your Whop Account ID

1. Log in to your [Whop Dashboard](https://whop.com/dashboard)
2. Look at the dashboard URL
3. Copy the portion after `dashboard/` that begins with `biz_` (format: `biz_xxxxxxxxxxxxx`)

### Step 2: Initialize Whop Pixel

Add the following script to your HTML page **before** the HandL script tag:

```html
<script>
    // Set your Whop Account ID
    window.whop_account_id = 'YOUR_WHOP_ACCOUNT_ID_HERE';
</script>

<!-- Load HandL script --> Make sure to change your license key
<script>
var handl_custom_params = [];
var handl_js = document.createElement("script");
handl_js.setAttribute("src", "https://track.utmsimple.com/utm.js?license=<license code goes here>"), document.head.appendChild(handl_js), 
handl_js.onload = function() {
    /*This is the UTM Simple ready event, you can put any code you'd like to trigger after the script fully loaded here*/ 
    console.log("I'm ready")
    console.log("prnting all the cookies")
    console.log(HandL.getAll())
}; 
</script> 

```

Example:

```html
<script>
    window.whop_account_id = 'biz_xxxxxxxxxxxxx';
</script>
<script src="https://cdn.example.com/utm.js"></script>

```

### Multiple Accounts

To track the same funnel across several Whop accounts, pass an array of Account IDs:

```html
<script>
    window.whop_account_id = ['biz_xxxxxxxxxxxxx', 'biz_yyyyyyyyyyyyy'];
</script>

```

**Note:** Do not also paste Whop's own pixel snippet on the page. HandL loads it for you, and adding both will double-count your events.

### Step 3: Verify Installation

After the page loads, the Whop Pixel will automatically:

- Load the Whop Pixel script
- Set your account scope
- Fire a `page` event

You can verify the installation by:

1. Opening browser DevTools (F12)
2. Going to the Network tab
3. Filtering for `t.whop.tw`
4. You should see requests to Whop's tracking endpoint

# Event Sending

### Basic Event Sending

Use the `HandL.sendWhopEvent()` function to send events to Whop:

```javascript
HandL.sendWhopEvent(eventName, eventData);

```

**Parameters:**

- `eventName` (string, required): The name of the event
- `eventData` (object, optional): Event properties and customer information

**Note:** Do not track Whop's native checkout, subscriptions or trials. Whop records those itself. Use `sendWhopEvent` only for funnel steps on your own pages.

### Standard Events

Whop supports the following standard events:

#### lead

Track contact info or opt-in form submissions:

```javascript
HandL.sendWhopEvent('lead', {
    event_id: 'lead_8f21c0'
});

```

#### schedule

Track call or appointment bookings:

```javascript
HandL.sendWhopEvent('schedule', {
    value: 50,
    currency: 'USD'
});

```

#### submit\_application

Track application submissions:

```javascript
HandL.sendWhopEvent('submit_application');

```

#### contact

Track conversation or contact requests:

```javascript
HandL.sendWhopEvent('contact');

```

#### complete\_registration

Track signup or registration completion:

```javascript
HandL.sendWhopEvent('complete_registration');

```

#### view\_content

Track key page or content views:

```javascript
HandL.sendWhopEvent('view_content');

```

#### add\_to\_cart

Track items added to cart:

```javascript
HandL.sendWhopEvent('add_to_cart', {
    value: 19.99,
    currency: 'USD'
});

```

#### purchase

Track completed sales on your own checkout only:

```javascript
HandL.sendWhopEvent('purchase', {
    value: 29.99,
    currency: 'USD',
    event_id: 'order_12345'
});

```

### Custom Events

You can also send custom events with any event name:

```javascript
HandL.sendWhopEvent('CustomEventName', {
    value: 10,
    currency: 'USD'
});

```

### Event Data Parameters

Common event parameters you can include:

<table id="bkmrk-parametertypedescrip"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>`value`</td><td>number</td><td>Monetary value of the event</td><td>`29.99`</td></tr><tr><td>`currency`</td><td>string</td><td>Currency code (ISO 4217), defaults to USD</td><td>`'USD'`, `'EUR'`</td></tr><tr><td>`event_id`</td><td>string</td><td>Unique identifier, prevents duplicate counting</td><td>`'order_12345'`</td></tr></tbody></table>

Customer information fields can also be passed here. See **Advanced Matching**.

# Advanced Matching

Advanced matching allows Whop to match events to users more accurately by sending customer identifiers alongside the event.

**Important:** Unlike TikTok and Meta, Whop expects customer fields in **plain text**. HandL sends them unhashed by design. Do not hash emails or phone numbers before passing them.

### How It Works

1. **Data Collection:** When users fill out forms, HandL automatically captures customer details. Data is stored in localStorage with keys such as `em` (email) and `ph` (phone).
2. **Automatic Merging:** Every call to `HandL.sendWhopEvent()` merges any stored customer values into the event payload. Fields you pass directly always override the stored values.
3. **External ID:** Uses the `first_handlID` cookie as `external_id`. This is automatically generated on first visit.
4. **Full Name:** When a first or last name is available, HandL composes `name` automatically.

### Manual Data Collection

You can pass customer fields directly on any event:

```javascript
HandL.sendWhopEvent('lead', {
    event_id: 'lead_8f21c0',
    email: 'visitor@example.com',
    first_name: 'Jane',
    last_name: 'Doe',
    phone: '+15551234567'
});

```

### Advanced Matching Parameters

Whop supports the following identifiers (all sent as plain text):

<table id="bkmrk-parameterdescription"><thead><tr><th>Parameter</th><th>Description</th><th>Source</th></tr></thead><tbody><tr><td>`email`</td><td>User's email address</td><td>`localStorage.getItem('em')`</td></tr><tr><td>`first_name`</td><td>User's first name</td><td>`localStorage.getItem('fn')`</td></tr><tr><td>`last_name`</td><td>User's last name</td><td>`localStorage.getItem('ln')`</td></tr><tr><td>`name`</td><td>Full name</td><td>Composed from first and last name</td></tr><tr><td>`phone`</td><td>User's phone number</td><td>`localStorage.getItem('ph')`</td></tr><tr><td>`city`</td><td>User's city</td><td>`localStorage.getItem('ct')`</td></tr><tr><td>`state`</td><td>User's state</td><td>`localStorage.getItem('st')`</td></tr><tr><td>`postal_code`</td><td>User's postal code</td><td>`localStorage.getItem('zp')`</td></tr><tr><td>`country`</td><td>User's country</td><td>`localStorage.getItem('country')`</td></tr><tr><td>`external_id`</td><td>Unique identifier</td><td>`Cookies.get('first_handlID')`</td></tr></tbody></table>

Empty fields are dropped automatically and never sent.

### Verification

To verify advanced matching is working:

1. Open browser DevTools (F12)
2. Go to the Network tab
3. Filter for `t.whop.tw`
4. Inspect the request payload and confirm your customer fields are present

# Custom Events / Listeners

### Listening to Whop Events

HandL fires custom events you can listen to:

```javascript
// Listen for Whop initialization
document.body.addEventListener('UTMSimpleWhopInitCompleted', function(event) {
    console.log('Whop Pixel initialized');
});

// Listen for any Whop event completion
document.body.addEventListener('UTMSimpleWhopEventCompleted', function(event) {
    console.log('Whop event sent');
});

// Listen for specific event completion
document.body.addEventListener('UTMSimpleWhoppurchaseCompleted', function(event) {
    console.log('Purchase event sent to Whop');
});

```

**Note:** The event-specific listener name is `UTMSimpleWhop` + your event name + `Completed`, using the event name exactly as you passed it. Because Whop's standard events are lowercase, `sendWhopEvent('purchase')` fires `UTMSimpleWhoppurchaseCompleted`.

### Example: Track Button Clicks

```javascript
document.getElementById('book-call-button').addEventListener('click', function() {
    HandL.sendWhopEvent('schedule', {
        value: 50,
        currency: 'USD'
    });
});

```

### Example: Track Form Submissions

```html
<form id="contact-form" onsubmit="trackFormSubmission(event)">
    <!-- form fields -->
</form>

<script>
function trackFormSubmission(event) {
    // Form submission logic here

    HandL.sendWhopEvent('lead', {
        event_id: 'lead_' + Date.now()
    });
}
</script>

```