Android SDK - Tracking Events

Track events with the FunnelMob Android 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.trackPageView()
FunnelMob.trackViewContent()
FunnelMob.trackSearch()
FunnelMob.trackAddToCart()
FunnelMob.trackAddToWishlist()
FunnelMob.trackInitiateCheckout()
FunnelMob.trackAddPaymentInfo()
 
// Lead generation
FunnelMob.trackLead()
FunnelMob.trackCompleteRegistration()
FunnelMob.trackContact()
FunnelMob.trackSchedule()
FunnelMob.trackFindLocation()
FunnelMob.trackSubmitApplication()
 
// App events (Meta)
FunnelMob.trackAchieveLevel()
FunnelMob.trackUnlockAchievement()
FunnelMob.trackCompleteTutorial()
FunnelMob.trackActivateApp()
FunnelMob.trackRate()
FunnelMob.trackInAppAdClick()
FunnelMob.trackInAppAdImpression()
 
// TikTok-specific
FunnelMob.trackApplicationApproval()
FunnelMob.trackDownload()
FunnelMob.trackSubmitForm() // TikTok legacy — use trackLead() for new implementations

Events with revenue

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

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

Events with parameters

All typed methods accept an optional parameters argument:

import com.funnelmob.sdk.FunnelMobEventParameters
 
val params = FunnelMobEventParameters.build {
    set("content_ids", "SKU123")
    set("content_name", "Blue Widget")
    set("value", 29.99)
    set("currency", "USD")
}
 
FunnelMob.trackViewContent(params)
FunnelMob.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.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 com.funnelmob.sdk.FunnelMobRevenue
 
val revenue = FunnelMobRevenue.usd(29.99)
FunnelMob.trackEvent("tip_sent", revenue)
 
// Other currencies
val eur = FunnelMobRevenue.eur(19.99)
val gbp = FunnelMobRevenue.gbp(14.99)
val jpy = FunnelMobRevenue.of(2000.0, "JPY")
 
// Using BigDecimal for precision
val precise = FunnelMobRevenue.usd(BigDecimal("99.99"))

Events with Parameters

import com.funnelmob.sdk.FunnelMobEventParameters
 
// Using Builder
val params = FunnelMobEventParameters.Builder()
    .set("item_id", "sku_123")
    .set("quantity", 2)
    .set("price", 29.99)
    .set("is_gift", false)
    .build()
 
FunnelMob.trackEvent("add_to_cart", params)
 
// Using DSL (Kotlin)
val params = FunnelMobEventParameters.build {
    set("item_id", "sku_123")
    set("quantity", 2)
    set("price", 29.99)
}
 
// From a Map
val params = FunnelMobEventParameters.fromMap(mapOf(
    "item_id" to "sku_123",
    "quantity" to 2
))

Events with Revenue and Parameters

val revenue = FunnelMobRevenue.usd(99.00)
val params = FunnelMobEventParameters.build {
    set("recipient", "user_456")
    set("message", "Great work!")
}
 
FunnelMob.trackEvent("tip_sent", revenue, params)

Standard Events (Legacy Constants)

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

import com.funnelmob.sdk.FunnelMobStandardEvents
 
FunnelMob.trackEvent(FunnelMobStandardEvents.REGISTRATION)
FunnelMob.trackEvent(FunnelMobStandardEvents.LOGIN)
FunnelMob.trackEvent(FunnelMobStandardEvents.PURCHASE)
FunnelMob.trackEvent(FunnelMobStandardEvents.SUBSCRIBE)
FunnelMob.trackEvent(FunnelMobStandardEvents.TUTORIAL_COMPLETE)
FunnelMob.trackEvent(FunnelMobStandardEvents.LEVEL_COMPLETE)
FunnelMob.trackEvent(FunnelMobStandardEvents.ADD_TO_CART)
FunnelMob.trackEvent(FunnelMobStandardEvents.CHECKOUT)

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

Java Interoperability

All public methods have @JvmStatic annotations:

import com.funnelmob.sdk.FunnelMob;
import com.funnelmob.sdk.FunnelMobRevenue;
import com.funnelmob.sdk.FunnelMobEventParameters;
 
// Track events
FunnelMob.trackEvent("button_click");
 
// With revenue
FunnelMobRevenue revenue = FunnelMobRevenue.usd(29.99);
FunnelMob.trackEvent("purchase", revenue);
 
// With parameters
FunnelMobEventParameters params = new FunnelMobEventParameters.Builder()
    .set("item_id", "sku_123")
    .set("quantity", 2)
    .build();
FunnelMob.trackEvent("add_to_cart", params);

Validation

Event Names

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

// Valid
FunnelMob.trackEvent("purchase")           // OK
FunnelMob.trackEvent("level_2_complete")   // OK
 
// Invalid (logged as errors)
FunnelMob.trackEvent("2nd_level")          // Starts with number
FunnelMob.trackEvent("my-event")           // Contains hyphen
FunnelMob.trackEvent("")                   // Empty

Currency

Must be a 3-letter ISO 4217 code
Automatically converted to uppercase with FunnelMobRevenue.of()

FunnelMobRevenue.usd(29.99)               // OK
FunnelMobRevenue.of(29.99, "jpy")          // Converted to "JPY"
 
// Invalid (throws IllegalArgumentException)
FunnelMobRevenue.of(29.99, "US")           // Too short
FunnelMobRevenue.of(29.99, "USDD")         // Too long