ClickBeam Integration

Complete guide for implementing ClickBeam client-side tracking on your website. This guide covers installation, event tracking, and advanced configuration options.

User Guide
Client-Side Tracking

Technical Requirements

  • Active API token for your advertiser account
  • Access to edit your website's HTML (ability to add scripts to <head> section)
  • Basic knowledge of HTML/JavaScript for custom event implementation
  • Modern browser supporting JavaScript ES6+ (all current browsers supported)

Step 1: Generate API Token

1.1

Navigate to Advertiser Dashboard

Open your advertiser dashboard from the main navigation or advertiser list.

1.2

Create Active API Token

Scroll to the "API Tokens" section and click "Generate New Token". The token will be created and marked as active automatically.

Important: The installation script will only appear once you have an active API token. You can have multiple tokens, but only one can be active at a time for ClickBeam integration.

Step 2: Install Tracking Script

2.1

Copy Installation Script

In your advertiser dashboard, locate the "Installation Script" section. Click "Copy Script" to copy the complete installation code to your clipboard.

Example installation script structure:

<script>
    (function(w,d,s,l,i){
        w[l]=w[l]||function(){(w[l].q=w[l].q||[]).push(Array.from(arguments))};
        var f=d.getElementsByTagName(s)[0],j=d.createElement(s);
        j.async=true;j.src='https://your-domain.com/magic/advertiser-id.min.js';
        f.parentNode.insertBefore(j,f);
        w[l]('init', 'your-api-token', 'https://your-api-url', 'advertiser-id');
    })(window,document,'script','beam');
</script>
2.2

Add Script to Website

Paste the installation script into the <head> section of your website, ideally near the top for earliest possible initialization.

Best Practice: Place the script in your site's global header template so it loads on every page. This ensures consistent tracking across your entire website.
2.3

Deploy to Website

Save your changes and deploy the updated HTML to your website. The script will load asynchronously and automatically start tracking page views.

Step 3: Verify Installation

3.1

Check Browser Console

Open your website in a browser and open Developer Tools (F12 or right-click → Inspect). Check the Console tab for ClickBeam initialization messages.

Expected console output:

ClickBeam initialized successfully
Page view tracked automatically
3.2

Verify Network Requests

In Developer Tools, switch to the Network tab. Look for requests to your API endpoint (typically /api/track). You should see POST requests with 200 status codes.

3.3

Check Intelligence Dashboard

Navigate to your advertiser's Intelligence Reports. You should see page_view events appearing with source attribution showing "clickbeam".

Note: Events typically appear in Intelligence Reports within 1-2 seconds. If you don't see events, check the troubleshooting section below.

Step 4: Implement Event Tracking

ClickBeam automatically tracks page views. For custom events like purchases, leads, and cart actions, add JavaScript event calls where those actions occur.

4.1

Understanding Queue-Safe Calls

ClickBeam uses intelligent queueing to handle asynchronous script loading. Always use the queue-safe pattern:

Recommended: beam('trackPurchase', {...})

Queue-safe - works even if script hasn't loaded yet

Also works: beam.trackPurchase({...})

Requires script to be fully loaded first

4.2

Event Examples

Below are common event implementations. Copy and customize these for your specific use cases.

Purchase Event

E-commerce

Track completed purchases on your order confirmation page. 

beam('trackPurchase', {
    event_id: 'purchase-12345',
    transaction_id: 'TXN-ABC123',
    value: 29.99,
    currency: 'USD',
    user_data: {
        em: 'customer@example.com',  // Automatically hashed
        ph: '+15551234567'            // Automatically hashed
    },
    content_ids: ['product-1', 'product-2'],
    content_type: 'product'
});

Lead Event

Forms

Track form submissions and lead generation events. 

beam('trackLead', {
    event_id: 'lead-67890',
    value: 50.00,
    currency: 'USD',
    user_data: {
        em: 'lead@example.com',
        fn: 'John',
        ln: 'Doe'
    },
    content_name: 'Contact Form',
    content_category: 'Lead Generation'
});

Add to Cart Event

E-commerce

Track when users add products to their shopping cart. 

beam('trackAddToCart', {
    event_id: 'cart-add-111',
    value: 19.99,
    currency: 'USD',
    content_ids: ['product-123'],
    content_category: 'Electronics',
    content_type: 'product',
    content_name: 'Blue Widget'
});

Complete Registration Event

Account

Track user account registrations and sign-ups. 

beam('trackCompleteRegistration', {
    event_id: 'signup-222',
    user_data: {
        em: 'customer@example.com'
    },
    method: 'email',
    content_name: 'Account Registration'
});

Advanced Configuration

CNAME Setup

For optimal performance and tracking reliability, configure a CNAME record:

  • First-party context (better privacy)
  • Reduced ad-blocker interference
  • No CORS complexity
beam.yourdomain.com → CNAME → api.tandembeam.com

Privacy & PII Handling

ClickBeam automatically handles Personally Identifiable Information (PII):

  • Email (em): SHA-256 hashed before API transmission
  • Phone (ph): Normalized and SHA-256 hashed
  • Edge processing: No raw PII reaches backend

Best Practices

Recommended Implementation Patterns

Use Unique Event IDs: Generate unique identifiers for each event to prevent duplication across platforms (e.g., purchase-${orderId})
ISO Currency Codes: Always use standard 3-letter currency codes (USD, EUR, GBP) for accurate conversion tracking
Consistent Content IDs: Use the same product/content identifiers across all events for accurate attribution and remarketing
Test Before Production: Use the platform test tools to verify event tracking before deploying to production
Queue-Safe Pattern: Always use beam('method', params) to avoid timing-dependent failures

Troubleshooting

Common Issues

"beam is not defined" Error
The installation script hasn't loaded yet. Use the queue-safe pattern beam('method', params) instead of beam.method(params).
Script Not Loading (404 Error)
Verify the script URL in your installation code matches your advertiser ID and domain configuration. Check your advertiser dashboard for the correct installation script.
Events Not Appearing in Dashboard
Check browser console for errors. Verify your API token is active. Ensure you're not blocking API requests with ad blockers or privacy extensions.
CORS Errors
Set up a CNAME record pointing to the API domain to eliminate cross-origin issues. Alternatively, verify your domain is configured in advertiser settings.
Duplicate Events
Ensure you're using unique event_id values for each event. ClickBeam deduplicates based on event_id, so reusing IDs will cause events to be merged.

Next Steps

Once ClickBeam is installed and tracking events, configure Event Settings to forward events to advertising platforms.

Configure Event Settings → Testing Guide