Event Tracking

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?

Use EventTracker
Use PageTracker (Preferred)

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

App Lifecycle Events

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()
            )
        )
    }
}

Background Events

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()
    }
}

Button Clicks (Not on a Page)

// 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:

Verify event name matches dashboard (case-sensitive)
Check property names and types match schema
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

Feature	EventTracker	PageTracker
Use Case	Standalone events	Page/screen views
Engagement Tracking	❌ No	✅ Yes (automatic)
Scroll Depth	❌ No	✅ Yes
Contextual Cohorts	❌ No	✅ Yes (with URLs)
Platform Integration	Basic	✅ Full integration
Lifecycle Management	None	pause/resume/close
Insights Quality	Basic	✅ Rich
Recommendation	Specific cases only	Primary method

Best Practices

Do
Don't

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

Get Started

Products

Deployment

Governance

Valid Use Cases

Event Properties

Comparison

When to Use Which?

Basic Usage

Creating an EventTracker

Tracking an Event

Valid Use Cases

Invalid Use Cases (Use PageTracker Instead)

❌ Don’t: Track Screen Views with EventTracker

✅ Do: Use PageTracker for Screen Views

Event Properties

Example

Troubleshooting

Events Not Accepted

Should I Use EventTracker or PageTracker?

Comparison: EventTracker vs PageTracker

Best Practices

Page Tracking

Event Properties

Quick Start Guide

Video Tracking

Issues

API Reference

EventTracker Interface

Creating EventTracker

Valid Use Cases

Event Properties

Comparison

​When to Use Which?

​Basic Usage

​Creating an EventTracker

​Tracking an Event

​Valid Use Cases

​Invalid Use Cases (Use PageTracker Instead)

​❌ Don’t: Track Screen Views with EventTracker

​✅ Do: Use PageTracker for Screen Views

​Event Properties

​Example

​Troubleshooting

​Events Not Accepted

​Should I Use EventTracker or PageTracker?

​Comparison: EventTracker vs PageTracker

​Best Practices

​Related Documentation

Page Tracking

Event Properties

Quick Start Guide

Video Tracking

Issues

​API Reference

​EventTracker Interface

​Creating EventTracker

When to Use Which?

Basic Usage

Creating an EventTracker

Tracking an Event

Valid Use Cases

Invalid Use Cases (Use PageTracker Instead)

❌ Don’t: Track Screen Views with EventTracker

✅ Do: Use PageTracker for Screen Views

Event Properties

Example

Troubleshooting

Events Not Accepted

Should I Use EventTracker or PageTracker?

Comparison: EventTracker vs PageTracker

Best Practices

Related Documentation

API Reference

EventTracker Interface

Creating EventTracker