Web SDK - Tracking Events

Track events with the FunnelMob Web SDK.

Standard Attribution Events (Recommended)

Use these typed methods to track standard events that ad networks like Meta and TikTok use to measure conversions and optimize campaign delivery. By sending these events, you enable ad platforms to attribute installs, optimize for high-value users, and report on key actions like purchases, signups, and engagement.

Basic usage

// Engagement & commerce
FunnelMob.shared.trackPageView();
FunnelMob.shared.trackViewContent();
FunnelMob.shared.trackSearch();
FunnelMob.shared.trackAddToCart();
FunnelMob.shared.trackAddToWishlist();
FunnelMob.shared.trackInitiateCheckout();
FunnelMob.shared.trackAddPaymentInfo();
 
// Lead generation
FunnelMob.shared.trackLead();
FunnelMob.shared.trackCompleteRegistration();
FunnelMob.shared.trackContact();
FunnelMob.shared.trackSchedule();
FunnelMob.shared.trackFindLocation();
FunnelMob.shared.trackSubmitApplication();
 
// App events (Meta)
FunnelMob.shared.trackAchieveLevel();
FunnelMob.shared.trackUnlockAchievement();
FunnelMob.shared.trackCompleteTutorial();
FunnelMob.shared.trackActivateApp();
FunnelMob.shared.trackRate();
FunnelMob.shared.trackInAppAdClick();
FunnelMob.shared.trackInAppAdImpression();
 
// TikTok-specific
FunnelMob.shared.trackApplicationApproval();
FunnelMob.shared.trackDownload();
FunnelMob.shared.trackSubmitForm(); // TikTok legacy — use trackLead() for new implementations

Events with revenue

trackPurchase, trackSubscribe, trackStartTrial, and trackDonate require value and currency:

// Purchase (Meta + TikTok)
FunnelMob.shared.trackPurchase(29.99, 'USD');
 
// Subscription (Meta + TikTok)
FunnelMob.shared.trackSubscribe(9.99, 'USD');
 
// Free trial — pass 0 for value (Meta + TikTok)
FunnelMob.shared.trackStartTrial(0, 'USD');
 
// Donation (Meta only)
FunnelMob.shared.trackDonate(50.00, 'USD');
 
// In-app virtual currency — value only, no currency (Meta only)
FunnelMob.shared.trackSpentCredits(500);

Events with parameters

All typed methods accept an optional parameters argument:

import { FunnelMobEventParameters } from '@funnelmob/sdk';
 
const params = new FunnelMobEventParameters()
  .set('content_ids', ['SKU123'])
  .set('content_name', 'Blue Widget')
  .set('value', 29.99)
  .set('currency', 'USD');
 
FunnelMob.shared.trackViewContent(params);
FunnelMob.shared.trackPurchase(29.99, 'USD', params);

All 29 standard attribution events

Method	Description
`trackPageView()`	Fires on every page load
`trackViewContent()`	Visit to a product or content page
`trackSearch()`	Search performed
`trackAddToCart()`	Item added to cart
`trackAddToWishlist()`	Item saved to wishlist
`trackInitiateCheckout()`	Checkout process started
`trackAddPaymentInfo()`	Payment info entered
`trackPurchase(value, currency)`	Transaction completed
`trackLead()`	Contact info submitted
`trackCompleteRegistration()`	Account registration completed
`trackContact()`	Contact initiated
`trackSchedule()`	Appointment booked
`trackFindLocation()`	Business location searched
`trackCustomizeProduct()`	Product customized
`trackSubmitApplication()`	Application submitted
`trackStartTrial(value, currency)`	Free trial started
`trackSubscribe(value, currency)`	Paid subscription started
`trackApplicationApproval()`	Application approved
`trackDownload()`	File downloaded
`trackSubmitForm()`	Legacy Lead event — use `trackLead()`
`trackAchieveLevel()`	Level reached in app/game
`trackUnlockAchievement()`	Achievement unlocked
`trackRate()`	Rating submitted
`trackCompleteTutorial()`	In-app tutorial completed
`trackActivateApp()`	App launched
`trackInAppAdClick()`	In-app ad clicked
`trackInAppAdImpression()`	In-app ad shown
`trackDonate(value, currency)`	Donation made
`trackSpentCredits(value)`	Virtual currency spent

Custom Events

Track any event specific to your app that isn't covered by the standard attribution events above. Custom events are useful for measuring in-app behavior, building internal analytics, and tracking actions unique to your product.

Tracking a custom event

FunnelMob.shared.trackEvent('onboarding_complete');

Events with Revenue

For standard events like purchases and subscriptions, use the typed methods above (e.g., trackPurchase(value, currency)). Use trackEvent with revenue only for custom events that aren't covered by the standard methods:

import { FunnelMobRevenue } from '@funnelmob/sdk';
 
const revenue = FunnelMobRevenue.usd(29.99);
FunnelMob.shared.trackEvent('tip_sent', revenue);
 
// Other currencies
const eur = FunnelMobRevenue.eur(19.99);
const gbp = FunnelMobRevenue.gbp(14.99);
const jpy = new FunnelMobRevenue(2000, 'JPY');

Events with Parameters

import { FunnelMobEventParameters } from '@funnelmob/sdk';
 
// Fluent builder pattern
const params = new FunnelMobEventParameters()
  .set('item_id', 'sku_123')
  .set('quantity', 2)
  .set('price', 29.99)
  .set('is_gift', false);
 
FunnelMob.shared.trackEvent('add_to_cart', params);
 
// Or create from an object
const params = FunnelMobEventParameters.fromObject({
  item_id: 'sku_123',
  quantity: 2,
  price: 29.99,
});

Events with Revenue and Parameters

const revenue = FunnelMobRevenue.usd(99.00);
const params = new FunnelMobEventParameters()
  .set('recipient', 'user_456')
  .set('message', 'Great work!');
 
FunnelMob.shared.trackEvent('tip_sent', revenue, params);

Standard Events (Legacy Constants)

For backward compatibility, fm_-prefixed string constants are still available:

import { StandardEvents } from '@funnelmob/sdk';
 
FunnelMob.shared.trackEvent(StandardEvents.REGISTRATION);
FunnelMob.shared.trackEvent(StandardEvents.LOGIN);
FunnelMob.shared.trackEvent(StandardEvents.PURCHASE);
FunnelMob.shared.trackEvent(StandardEvents.SUBSCRIBE);
FunnelMob.shared.trackEvent(StandardEvents.TUTORIAL_COMPLETE);
FunnelMob.shared.trackEvent(StandardEvents.LEVEL_COMPLETE);
FunnelMob.shared.trackEvent(StandardEvents.ADD_TO_CART);
FunnelMob.shared.trackEvent(StandardEvents.CHECKOUT);

Event	Constant	Value
Registration	`StandardEvents.REGISTRATION`	`fm_registration`
Login	`StandardEvents.LOGIN`	`fm_login`
Purchase	`StandardEvents.PURCHASE`	`fm_purchase`
Subscribe	`StandardEvents.SUBSCRIBE`	`fm_subscribe`
Tutorial Complete	`StandardEvents.TUTORIAL_COMPLETE`	`fm_tutorial_complete`
Level Complete	`StandardEvents.LEVEL_COMPLETE`	`fm_level_complete`
Add to Cart	`StandardEvents.ADD_TO_CART`	`fm_add_to_cart`
Checkout	`StandardEvents.CHECKOUT`	`fm_checkout`

Validation

Event Names

Must not be empty
Maximum 100 characters
Must match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$

// Valid
FunnelMob.shared.trackEvent('purchase');           // OK
FunnelMob.shared.trackEvent('level_2_complete');   // OK
 
// Invalid (logged as errors, not thrown)
FunnelMob.shared.trackEvent('2nd_level');          // Starts with number
FunnelMob.shared.trackEvent('my-event');           // Contains hyphen
FunnelMob.shared.trackEvent('');                   // Empty

Currency

Must be a 3-letter ISO 4217 code
Automatically converted to uppercase

new FunnelMobRevenue(29.99, 'USD');   // OK
new FunnelMobRevenue(29.99, 'usd');   // Converted to 'USD'
 
// Invalid
new FunnelMobRevenue(29.99, 'US');    // Too short
new FunnelMobRevenue(29.99, 'USDD'); // Too long