> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Event Tracking
> Track standalone events not associated with pages
**Use PageTracker Instead for Most Cases**
For most tracking scenarios, **[PageTracker](/sdks/mobile/android/features/page-tracking) 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.
## 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
Use **[PageTracker](/sdks/mobile/android/features/page-tracking)** for:
* Article or content views
* Screen views in your app
* Any page the user navigates to
* When you need engagement metrics
* When you want contextual cohorts
**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
```kotlin theme={"dark"}
val eventTracker = permutive.eventTracker()
```
EventTracker is lightweight and can be created anytime you need to track a standalone event.
### Tracking an Event
```kotlin Kotlin theme={"dark"}
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"
)
)
}
}
}
```
```java Java theme={"dark"}
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
```kotlin theme={"dark"}
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()
)
)
}
}
```
```kotlin theme={"dark"}
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()
}
}
```
```kotlin theme={"dark"}
// 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
```kotlin theme={"dark"}
// ❌ 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
```kotlin theme={"dark"}
// ✅ 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](/sdks/mobile/android/core-concepts/event-properties) for complete documentation.
### Example
```kotlin theme={"dark"}
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](../troubleshooting/common-errors.mdx#schema-validation-failed)
### 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
* 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
* Use EventTracker for page/screen views
* Use EventTracker when PageTracker is more appropriate
* Create events without checking schema
* Track PII in event properties
***
## Related Documentation
Recommended primary method
Add structured data to events
Get started with the SDK
Track video content
Solve common issues
***
## API Reference
For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html).
### 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