iOS SDK - Tracking Events

Track events with the FunnelMob iOS 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(value: 29.99, currency: "USD")
 
// Subscription (Meta + TikTok)
FunnelMob.shared.trackSubscribe(value: 9.99, currency: "USD")
 
// Free trial — pass 0 for value (Meta + TikTok)
FunnelMob.shared.trackStartTrial(value: 0, currency: "USD")
 
// Donation (Meta only)
FunnelMob.shared.trackDonate(value: 50.00, currency: "USD")
 
// In-app virtual currency — value only, no currency (Meta only)
FunnelMob.shared.trackSpentCredits(value: 500)

Events with parameters

All typed methods accept an optional parameters argument:

var params = FunnelMobEventParameters()
params.set("content_ids", value: "SKU123")
params.set("content_name", value: "Blue Widget")
params.set("value", value: 29.99)
params.set("currency", value: "USD")
 
FunnelMob.shared.trackViewContent(parameters: params)
FunnelMob.shared.trackPurchase(value: 29.99, currency: "USD", parameters: 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:

let revenue = FunnelMobRevenue.usd(29.99)
FunnelMob.shared.trackEvent("tip_sent", revenue: revenue)
 
// Other currencies
let eur = FunnelMobRevenue.eur(19.99)
let gbp = FunnelMobRevenue.gbp(14.99)
let jpy = FunnelMobRevenue(amount: 2000.0, currency: "JPY")
 
// Using Decimal for precision
let precise = FunnelMobRevenue(amount: Decimal(string: "99.99")!, currency: "USD")

Events with Parameters

// Using mutating struct
var params = FunnelMobEventParameters()
params.set("item_id", value: "sku_123")
params.set("quantity", value: 2)
params.set("price", value: 29.99)
params.set("is_gift", value: false)
 
FunnelMob.shared.trackEvent("add_to_cart", parameters: params)
 
// Using dictionary literal
let params: FunnelMobEventParameters = [
    "item_id": "sku_123",
    "quantity": 2,
    "price": 29.99,
    "is_gift": false
]
 
FunnelMob.shared.trackEvent("add_to_cart", parameters: params)
 
// From a dictionary
let params = FunnelMobEventParameters([
    "item_id": "sku_123",
    "quantity": 2
])

Events with Revenue and Parameters

let revenue = FunnelMobRevenue.usd(99.00)
var params = FunnelMobEventParameters()
params.set("recipient", value: "user_456")
params.set("message", value: "Great work!")
 
FunnelMob.shared.trackEvent("tip_sent", revenue: revenue, parameters: params)

Standard Events (Legacy Constants)

For backward compatibility, fm_-prefixed string constants are still available via FunnelMob.StandardEvent:

FunnelMob.shared.trackEvent(FunnelMob.StandardEvent.registration)
FunnelMob.shared.trackEvent(FunnelMob.StandardEvent.login)
FunnelMob.shared.trackEvent(FunnelMob.StandardEvent.purchase)
FunnelMob.shared.trackEvent(FunnelMob.StandardEvent.subscribe)
FunnelMob.shared.trackEvent(FunnelMob.StandardEvent.tutorialComplete)
FunnelMob.shared.trackEvent(FunnelMob.StandardEvent.levelComplete)
FunnelMob.shared.trackEvent(FunnelMob.StandardEvent.addToCart)
FunnelMob.shared.trackEvent(FunnelMob.StandardEvent.checkout)

Event	Constant	Value
Registration	`FunnelMob.StandardEvent.registration`	`fm_registration`
Login	`FunnelMob.StandardEvent.login`	`fm_login`
Purchase	`FunnelMob.StandardEvent.purchase`	`fm_purchase`
Subscribe	`FunnelMob.StandardEvent.subscribe`	`fm_subscribe`
Tutorial Complete	`FunnelMob.StandardEvent.tutorialComplete`	`fm_tutorial_complete`
Level Complete	`FunnelMob.StandardEvent.levelComplete`	`fm_level_complete`
Add to Cart	`FunnelMob.StandardEvent.addToCart`	`fm_add_to_cart`
Checkout	`FunnelMob.StandardEvent.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
FunnelMob.shared.trackEvent("buttonClick")        // OK
 
// Invalid (logged as errors)
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

// Valid
FunnelMobRevenue(amount: 29.99, currency: "USD")
FunnelMobRevenue(amount: 29.99, currency: "usd")  // Converted to "USD"