External Page Tracker

The External Page Tracker is a lightweight JavaScript snippet that connects your external pages to the TagadaPay funnel system. It enables accurate analytics (device, browser, OS), session tracking, and funnel navigation on pages not hosted on TagadaPay.

This is essential for WooCommerce stores, WordPress sites, custom landing pages, or any external page that is part of your funnel. Without the tracker, analytics data will be inaccurate (e.g., showing the server’s User-Agent instead of the visitor’s browser).

Why You Need This

When a funnel includes steps hosted outside TagadaPay (e.g., your WooCommerce store), the TagadaPay platform has no visibility into what happens on those pages. The External Page Tracker solves this by:

Creating a session — authenticates the visitor and creates an anonymous token
Tracking page views — records which funnel step the visitor is on
Capturing real device data — sends the actual browser User-Agent, screen size, and device info (instead of a server-side PHP User-Agent)
Enabling funnel navigation — allows the visitor to move to the next step via JavaScript
Preserving identity — maintains the same customer identity across TagadaPay-hosted and external pages

┌────────────────┐     ┌──────────────────┐     ┌────────────────┐
│  Your Store     │ ──► │  TagadaPay        │ ──► │  Thank You     │
│  (WooCommerce)  │     │  Checkout         │     │  Page          │
│  + Tracker ✅   │     │  (hosted)         │     │  (hosted)      │
└────────────────┘     └──────────────────┘     └────────────────┘

Quick Start

Option 1: CDN (recommended for most sites)

Add this before the closing </body> tag on your external page:

<script src="https://cdn.jsdelivr.net/npm/@tagadapay/plugin-sdk/dist/external-tracker.min.js"></script>
<script>
  TagadaTracker.init({
    storeId: 'store_xxx',       // Your TagadaPay store ID
    accountId: 'acc_xxx',       // Your TagadaPay account ID
    stepId: 'step_xxx',         // The funnel step this page represents
    funnelId: 'funnel_xxx',     // Optional: auto-detected from URL params
    debug: false,               // Set true during development

    onReady: function(session) {
      console.log('Tracker ready:', session.sessionId);
    },
    onError: function(error) {
      console.error('Tracker failed:', error.message);
    }
  });
</script>

Option 2: NPM Package

npm install @tagadapay/plugin-sdk

import { TagadaTracker } from '@tagadapay/plugin-sdk/v2/standalone';

await TagadaTracker.init({
  storeId: 'store_xxx',
  accountId: 'acc_xxx',
  stepId: 'step_xxx',
  debug: process.env.NODE_ENV === 'development',

  onReady: (session) => {
    console.log('Ready:', session);
  }
});

You can find your storeId, accountId, and stepId in the TagadaPay dashboard under Storefront → [Your Funnel] → External Step → Tracking Script.

Configuration

Required Parameters

Parameter	Type	Description
`storeId`	`string`	Your TagadaPay store ID (e.g., `store_019dd15cdb5b`)
`accountId`	`string`	Your TagadaPay account ID (e.g., `acc_4ff19578aaa2`)
`stepId`	`string`	The funnel step ID this page represents (e.g., `step_abc123`)

Optional Parameters

Parameter	Type	Default	Description
`funnelId`	`string`	Auto-detected from URL	Funnel ID (if not in URL params)
`stepName`	`string`	—	Human-readable step name for analytics
`stepType`	`string`	—	Step categorization (`landing`, `offer`)
`apiBaseUrl`	`string`	`https://app.tagadapay.com`	API base URL (only change for self-hosted or local dev)
`debug`	`boolean`	`false`	Enable verbose console logging

Callbacks

Callback	Signature	Description
`onReady`	`(session: ExternalTrackerSession) => void`	Called when the tracker is fully initialized
`onError`	`(error: Error) => void`	Called on failure — when provided, `init()` will not throw

When onError is not provided, init() will throw on failure. Always use onError or wrap init() in a try/catch.

API Reference

`TagadaTracker.init(config)`

Initialize the tracker. Must be called once per page load. Returns a Promise<ExternalTrackerSession | null>.

const session = await TagadaTracker.init({
  storeId: 'store_xxx',
  accountId: 'acc_xxx',
  stepId: 'step_xxx',
});

The returned session object:

interface ExternalTrackerSession {
  sessionId: string;      // Funnel session ID
  customerId: string;     // Anonymous customer ID
  storeId: string;        // Store ID
  funnelId?: string;      // Funnel ID (if resolved)
  currentStepId?: string; // Current step ID
  cmsToken?: string;      // Auth token (for API calls)
}

`TagadaTracker.navigate(options)`

Navigate to the next funnel step. By default, this redirects the browser automatically.

await TagadaTracker.navigate({
  eventType: 'form.submitted',
  eventData: {
    email: 'user@example.com',
    source: 'landing-page'
  },
  autoRedirect: true,  // default: true
});

Option	Type	Default	Description
`eventType`	`string`	—	Event type (e.g., `form.submitted`)
`eventData`	`object`	`{}`	Arbitrary event data
`autoRedirect`	`boolean`	`true`	Auto-redirect to the next step URL
`returnUrl`	`string`	—	Override the redirect URL

`TagadaTracker.trackEvent(options)`

Track a custom event for analytics without navigating. Non-blocking — errors are silently swallowed.

TagadaTracker.trackEvent({
  name: 'video_play',
  data: { videoId: 'hero-video', watchTime: 30 }
});

TagadaTracker.trackEvent({
  name: 'add_to_cart',
  data: { productId: 'prod_123', quantity: 2 }
});

`TagadaTracker.buildUrl(baseUrl, params?)`

Build a URL that preserves funnel session context. Use this when linking to other external pages within the same funnel.

const nextPageUrl = TagadaTracker.buildUrl('https://mysite.com/offer', {
  customParam: 'value'
});
// https://mysite.com/offer?funnelSessionId=fs_xxx&token=xxx&funnelId=xxx&storeId=xxx&customParam=value

`TagadaTracker.reset(newStepId)`

Reset the tracker to a different step without re-creating the session. Useful for single-page applications.

await TagadaTracker.reset('step_new_step_id');

`TagadaTracker.destroy()`

Clean up the tracker, remove event listeners, and clear state. Call this when the tracker is no longer needed.

TagadaTracker.destroy();

Utility Methods

Method	Returns	Description
`isReady()`	`boolean`	Whether the tracker is initialized
`getSession()`	`ExternalTrackerSession\|null`	Current session data
`getCustomerId()`	`string\|null`	Customer ID
`getFunnelSessionId()`	`string\|null`	Funnel session ID
`getClient()`	`TagadaClient\|null`	Underlying SDK client (advanced)
`version`	`string`	Tracker version (e.g., `1.0.0`)

Examples

WooCommerce / WordPress

If you’re using the TagadaPay WooCommerce plugin, the tracker is injected automatically. No manual setup needed. For manual integration, add the tracker to your theme’s footer.php:

<script src="https://cdn.jsdelivr.net/npm/@tagadapay/plugin-sdk/dist/external-tracker.min.js"></script>
<script>
  TagadaTracker.init({
    storeId: '<?php echo esc_js(TGD_STORE_ID); ?>',
    accountId: '<?php echo esc_js(TGD_ACCOUNT_ID); ?>',
    stepId: '<?php echo esc_js(TGD_STEP_ID); ?>',
    funnelId: '<?php echo esc_js(TGD_FUNNEL_ID); ?>',
    debug: <?php echo TGD_DEBUG ? 'true' : 'false'; ?>,

    onReady: function(session) {
      // Store token in cookie for server-side use
      document.cookie = 'tgd_token=' + (session.cmsToken || '') + ';path=/;samesite=lax';
      document.cookie = 'tgd_customer_id=' + (session.customerId || '') + ';path=/;samesite=lax';
    }
  });
</script>

Landing Page with CTA Button

<!DOCTYPE html>
<html>
<body>
  <h1>Special Offer</h1>
  <p>Get 50% off today!</p>
  <button id="buy-now">Buy Now</button>

  <script src="https://cdn.jsdelivr.net/npm/@tagadapay/plugin-sdk/dist/external-tracker.min.js"></script>
  <script>
    TagadaTracker.init({
      storeId: 'store_xxx',
      accountId: 'acc_xxx',
      stepId: 'step_landing',
      debug: true,
    });

    document.getElementById('buy-now').addEventListener('click', function() {
      TagadaTracker.navigate({
        eventType: 'offer.accepted',
        eventData: { offerId: 'summer-sale' }
      });
    });
  </script>
</body>
</html>

Lead Capture Form

<form id="lead-form">
  <input type="email" name="email" placeholder="Your email" required />
  <button type="submit">Get Started</button>
</form>

<script src="https://cdn.jsdelivr.net/npm/@tagadapay/plugin-sdk/dist/external-tracker.min.js"></script>
<script>
  TagadaTracker.init({
    storeId: 'store_xxx',
    accountId: 'acc_xxx',
    stepId: 'step_lead_capture',
  });

  document.getElementById('lead-form').addEventListener('submit', function(e) {
    e.preventDefault();
    var email = e.target.email.value;

    TagadaTracker.navigate({
      eventType: 'form.submitted',
      eventData: { email: email },
    });
  });
</script>

Single Page App (React)

import { useEffect } from 'react';
import { TagadaTracker } from '@tagadapay/plugin-sdk/v2/standalone';

function ExternalPage({ stepId }: { stepId: string }) {
  useEffect(() => {
    TagadaTracker.init({
      storeId: 'store_xxx',
      accountId: 'acc_xxx',
      stepId,
      onError: (err) => console.error('Tracker failed:', err),
    });

    return () => {
      TagadaTracker.destroy();
    };
  }, [stepId]);

  const handleCTA = async () => {
    await TagadaTracker.navigate({
      eventType: 'button.clicked',
      autoRedirect: false, // handle routing yourself
    });
  };

  return <button onClick={handleCTA}>Continue</button>;
}

How It Works Internally

init() is called — validates config, creates an anonymous session token via POST /api/v1/cms/session/anonymous
Session initialized — sends device/browser data via POST /api/v1/cms/session/v2/init
Funnel registered — tells the orchestrator which step the visitor is on via POST /api/v1/funnel/initialize
onReady fires — session is ready, page view is tracked
navigate() called — sends navigation event, orchestrator determines the next step URL, browser redirects

All API calls include the real browser User-Agent, screen resolution, and device data — ensuring accurate analytics.

Troubleshooting

Console shows 'storeId is required'

Make sure you’re passing a valid storeId string. Check the TagadaPay dashboard for your store ID.

Console shows 'accountId is required'

The accountId parameter is required since v1.0.0. Find it in your TagadaPay dashboard under Settings → Account.

Analytics show wrong OS (e.g., 'PHP/8.2')

This means session initialization is happening server-side (PHP) instead of client-side. Make sure the External Page Tracker script is loaded in the browser, not called from PHP.

Tracker shows 'No plugin config found - using defaults'

The tracker bundle may be outdated. Make sure you’re using the latest version from the CDN. Clear your browser cache or add a version query parameter: ?v=1.0.0.

Duplicate /api/v1/funnel/initialize calls

Make sure you’re using the latest tracker version (1.0.0+). Older versions had a bug where both the tracker and the SDK client would independently initialize the funnel.

Next Steps

Trigger Checkout

Create checkout sessions from any website

Plugin SDK

Build full custom checkout experiences

Funnels

Learn about multi-step funnels

API Reference

Full REST API documentation

​External Page Tracker

​Why You Need This

​Quick Start

​Option 1: CDN (recommended for most sites)

​Option 2: NPM Package

​Configuration

​Required Parameters

​Optional Parameters

​Callbacks

​API Reference

​TagadaTracker.init(config)

​TagadaTracker.navigate(options)

​TagadaTracker.trackEvent(options)

​TagadaTracker.buildUrl(baseUrl, params?)

​TagadaTracker.reset(newStepId)

​TagadaTracker.destroy()

​Utility Methods

​Examples

​WooCommerce / WordPress

​Landing Page with CTA Button

​Lead Capture Form

​Single Page App (React)

​How It Works Internally

​Troubleshooting

​Next Steps

Trigger Checkout

Plugin SDK

Funnels

API Reference

External Page Tracker

Why You Need This

Quick Start

Option 1: CDN (recommended for most sites)

Option 2: NPM Package

Configuration

Required Parameters

Optional Parameters

Callbacks

API Reference

`TagadaTracker.init(config)`

`TagadaTracker.navigate(options)`

`TagadaTracker.trackEvent(options)`

`TagadaTracker.buildUrl(baseUrl, params?)`

`TagadaTracker.reset(newStepId)`

`TagadaTracker.destroy()`

Utility Methods

Examples

WooCommerce / WordPress

Landing Page with CTA Button

Lead Capture Form

Single Page App (React)

How It Works Internally

Troubleshooting

Next Steps