Skip to main content
Use PageTracker Instead for Most CasesFor most tracking scenarios, PageTracker is the recommended approach as it integrates better with Permutive’s standard events and provides richer insights. Use EventTracker only for specific use cases where PageTracker doesn’t fit.

Valid Use Cases

Event Properties

Comparison

​
When to Use Which?

EventTracker should be used only for:
  • Standalone events not associated with a page or screen
  • Button clicks or interactions not tied to page views
  • Background events (app lifecycle, notifications)
  • Form submissions without page context
  • Lightweight events without engagement tracking needs
Default to PageTracker for most tracking needs. Most customer implementations should primarily use PageTracker with EventTracker reserved for specific cases.

​
Basic Usage

​
Creating an EventTracker

val eventTracker = permutive.eventTracker()
EventTracker is lightweight and can be created anytime you need to track a standalone event.

​
Tracking an Event

import com.permutive.android.EventProperties

class MainActivity : AppCompatActivity() {

    private val permutive by lazy {
        (application as MyApplication).permutive
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val eventTracker = permutive.eventTracker()

        // Track a simple event
        settingsButton.setOnClickListener {
            eventTracker.track("SettingsButtonClicked")
        }

        // Track an event with properties
        shareButton.setOnClickListener {
            eventTracker.track(
                "ContentShared",
                EventProperties.from(
                    "share_method" to "email",
                    "content_type" to "article"
                )
            )
        }
    }
}

import com.permutive.android.EventProperties;
import com.permutive.android.EventTracker;

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Permutive permutive = ((MyApplication) getApplication()).getPermutive();
        EventTracker eventTracker = permutive.eventTracker();

        // Track a simple event
        settingsButton.setOnClickListener(v -> {
            eventTracker.track("SettingsButtonClicked");
        });

        // Track an event with properties
        shareButton.setOnClickListener(v -> {
            EventProperties properties = new EventProperties.Builder()
                .with("share_method", "email")
                .with("content_type", "article")
                .build();
            eventTracker.track("ContentShared", properties);
        });
    }
}

​
Valid Use Cases

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        val eventTracker = permutive.eventTracker()
        eventTracker.track(
            "AppLaunched",
            EventProperties.from(
                "app_version" to BuildConfig.VERSION_NAME,
                "is_first_launch" to isFirstLaunch()
            )
        )
    }
}

class SyncWorker : Worker(context, params) {

    override fun doWork(): Result {
        val eventTracker = permutive.eventTracker()

        eventTracker.track(
            "DataSynced",
            EventProperties.from(
                "items_synced" to 42,
                "sync_duration_ms" to 1250
            )
        )

        return Result.success()
    }
}

// In a dialog or overlay that's not a full page
class RatingDialog : DialogFragment() {

    fun onRatingSubmitted(rating: Int) {
        val eventTracker = permutive.eventTracker()

        eventTracker.track(
            "AppRated",
            EventProperties.from(
                "rating" to rating,
                "prompt_location" to "after_checkout"
            )
        )
    }
}

​
Invalid Use Cases (Use PageTracker Instead)

​
❌ Don’t: Track Screen Views with EventTracker

// ❌ WRONG - This should use PageTracker!
class ArticleActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val eventTracker = permutive.eventTracker()
        eventTracker.track("ArticleViewed")  // Use PageTracker instead!
    }
}

​
✅ Do: Use PageTracker for Screen Views

// ✅ CORRECT - Use PageTracker for pages/screens
class ArticleActivity : AppCompatActivity() {
    
    private lateinit var pageTracker: PageTracker
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        pageTracker = permutive.trackPage(
            title = "Article Title",
            url = Uri.parse("app://article/123")
        )
    }
    
    override fun onDestroy() {
        super.onDestroy()
        pageTracker.close()
    }
}

​
Event Properties

Events can include structured properties. See Event Properties Guide for complete documentation.

​
Example

eventTracker.track(
    "PurchaseCompleted",
    EventProperties.from(
        "order_id" to "ORD-12345",
        "total_amount" to 99.99,
        "currency" to "USD",
        "item_count" to 3,
        "payment_method" to "credit_card",
        "shipping_method" to "express"
    )
)

​
Troubleshooting

​
Events Not Accepted

Problem: Events showing as rejected in logs. Cause: Event schema doesn’t match dashboard configuration. Solution:
  1. Verify event name matches dashboard (case-sensitive)
  2. Check property names and types match schema
  3. See Common Errors

​
Should I Use EventTracker or PageTracker?

Ask yourself:
  • Is this a page or screen the user is viewing? → Use PageTracker
  • Do I need to track engagement time or scroll depth? → Use PageTracker
  • Do I want contextual cohorts for this content? → Use PageTracker
  • Is this a standalone action/event? → Use EventTracker
When in doubt, use PageTracker.

​
Comparison: EventTracker vs PageTracker

FeatureEventTrackerPageTracker
Use CaseStandalone eventsPage/screen views
Engagement Tracking❌ No✅ Yes (automatic)
Scroll Depth❌ No✅ Yes
Contextual Cohorts❌ No✅ Yes (with URLs)
Platform IntegrationBasic✅ Full integration
Lifecycle ManagementNonepause/resume/close
Insights QualityBasic✅ Rich
RecommendationSpecific cases onlyPrimary method

​
Best Practices

  • Use EventTracker for truly standalone events
  • Use EventTracker for background/system events
  • Prefer PageTracker for user-facing content
  • Include relevant event properties
  • Follow your event schema exactly

Page Tracking

Recommended primary method

Event Properties

Add structured data to events

Quick Start Guide

Get started with the SDK

Video Tracking

Track video content

Issues

Solve common issues

​
API Reference

For complete API documentation, see the Javadocs.

​
EventTracker Interface

  • track(eventName: String) - Track event without properties
  • track(eventName: String, properties: EventProperties?) - Track event with properties

​
Creating EventTracker

  • Permutive.eventTracker() - Create an EventTracker instance