Android Codegen Setup

A guide to integrating EventPanel CLI into your Android project for type-safe analytics event code generation.

Demo Project: View Android Demo on GitHub →

Explore how analytics events are used in our Android demo project with generated, type-safe Kotlin code.

Overview

EventPanel CLI generates type-safe Kotlin analytics events from YAML configuration files, ensuring compile-time safety and reducing runtime errors in your Android application.

Features

• 🎯 Type-Safe Analytics: Generated analytics events with compile-time safety
• 📝 YAML Configuration: Event definitions managed through EventPanel.yaml
• 🔄 Code Generation: Automated Kotlin code generation from event schemas
• 🛡️ Type Safety: Compile-time validation of event parameters

Installation

Prerequisites

• Android Studio or IntelliJ IDEA
• Gradle-based Android project
• Kotlin support enabled

Install EventPanel CLI

Option 1: Homebrew (Recommended)

brew tap eventpanel/eventpanel
brew install eventpanel

Option 2: Manual Installation

Download the latest release from the EventPanel CLI repository and add it to your PATH.

Verify Installation

eventpanel --version

Project Initialization

Step 1: Initialize EventPanel Configuration

Run the initialization command in your project root directory:

eventpanel init --output app/src/main/java/com/yourapp/analytics/GeneratedAnalyticsEvents.kt

This command will:

• Create EventPanel.yaml configuration file
• Set up the default Kotlin configuration
• Configure the output path for generated events

Note: Replace the output path with your actual project structure. For example:

• app/src/main/java/com/yourapp/analytics/GeneratedAnalyticsEvents.kt
• src/main/kotlin/com/yourapp/analytics/GeneratedAnalyticsEvents.kt

The generated EventPanel.yaml will look like:

workspaceId: YOUR_WORKSPACE_ID
source: android
plugin:
  kotlingen:
    eventClassName: AnalyticsEvent
    generatedEventsPath: app/src/main/java/com/yourapp/analytics/GeneratedAnalyticsEvents.kt
    documentation: true
    packageName: com.yourapp
events: []

Note: The workspaceId and source fields are automatically configured based on your EventPanel workspace.

You can then add your events to the events array or configure them through the EventPanel web interface.

Step 2: Set API Token

After initialization, you need to authenticate with EventPanel by setting your API token:

1. Create an API Token:

   • Go to your EventPanel workspace settings
   • Navigate to the API tokens section
   • Create a new token

2. Set the Token:

   eventpanel set-token YOUR_API_TOKEN

   Or using the alternative command:

   eventpanel auth set-token YOUR_API_TOKEN

The token will be securely stored and used for all authenticated requests to EventPanel.

Note: Replace YOUR_API_TOKEN with the actual token you created in the workspace settings.

Step 3: Add Events to Configuration

After initialization, you can add events to your EventPanel.yaml using the eventpanel add command. There are several ways to add events:

Add a Single Event by ID

# Add latest version of an event
eventpanel add DWnQMGoYrvUyaTGpbmvr9

# Add specific version of an event
eventpanel add DWnQMGoYrvUyaTGpbmvr9 --version 2

Add an Event by Name

# Add latest version of an event by name
eventpanel add --name "User Login"

Add All Events

# Add all available events for the configured source
eventpanel add --all

Add Events by Category

# Add all events from a category by ID
eventpanel add --category-id "abc123"

# Add all events from a category by name
eventpanel add --category-name "Login Screen"

Manual Configuration

You can also manually edit EventPanel.yaml to add events:

events:
  - id: YOUR_EVENT_ID_1
    version: 1
  - id: YOUR_EVENT_ID_2
    version: 2

Note: Events can also be configured through the EventPanel web interface, which will sync automatically.

Step 4: Configure Gradle

Add the code generation task to your app/build.gradle.kts:

tasks.register("generateAnalyticsEvents") {
    doLast {
        exec {
            commandLine("eventpanel", "generate")
        }
    }
}

// Run code generation before compilation
tasks.named("preBuild") {
    dependsOn("generateAnalyticsEvents")
}

Note: The build script automatically detects the EventPanel CLI installation path (Homebrew or manual installation).

Step 5: Generate Analytics Code

Run the generation task:

./gradlew generateAnalyticsEvents

Or run directly:

eventpanel generate

Note: Code generation is automatically run during Android builds via the "generateAnalyticsEvents" Gradle task.

Usage

Basic Event Tracking

import com.yourapp.GeneratedAnalyticsEvents

// Track a profile screen view
val event = GeneratedAnalyticsEvents.ProfileScreen.profileScreenShown()
analytics.track(event)

// Track onboarding with origin enum
val onboardingEvent = GeneratedAnalyticsEvents.onboardingScreenShown(origin = Origin.Facebook)
analytics.track(onboardingEvent)

// Track loading with optional city ID
val loadingEvent = GeneratedAnalyticsEvents.loadingScreenShown(cityId = "NYC")
analytics.track(loadingEvent)

Generated Code Structure

The CLI generates Kotlin code in the following structure:

app/src/main/java/com/example/pizzadelivery/
└── GeneratedAnalyticsEvents.kt   # Generated event code with all event classes

The generated file contains:

• Event classes organized by category (e.g., ProfileScreen, Onboarding)
• Type-safe event constructors with required and optional parameters
• Enum types for event parameters (e.g., Origin)
• Base AnalyticsEvent interface implementation

Example Generated Events

// Profile Screen Events
GeneratedAnalyticsEvents.ProfileScreen.profileScreenShown()
GeneratedAnalyticsEvents.ProfileScreen.profileScreenClosed()

// Onboarding Events with Enum
GeneratedAnalyticsEvents.onboardingScreenShown(origin: Origin)

enum class Origin {
    Facebook,
    Google,
    Email
}

// Loading Events with Optional Parameters
GeneratedAnalyticsEvents.loadingScreenShown(cityId: String?)

Configuration Reference

EventPanel.yaml Structure

workspaceId: YOUR_WORKSPACE_ID      # Your EventPanel workspace ID
source: android                     # Source identifier
plugin:
  kotlingen:
    eventClassName: AnalyticsEvent  # Base event class name
    generatedEventsPath: app/src/main/java/com/example/app/GeneratedAnalyticsEvents.kt
    documentation: true             # Include documentation comments
    packageName: com.example.app    # Package name for generated code
events:
  - id: EVENT_ID                   # Event ID from EventPanel
  - id: EVENT_ID_2                 # Version optional (uses latest if omitted)
    version: 2                      # Optional: specific event schema version

Example Configuration

workspaceId: 00ab2c96-4e82-4166-b913-fb9aa7be6dbd
source: android
plugin:
  kotlingen:
    eventClassName: AnalyticsEvent
    generatedEventsPath: app/src/main/java/com/example/pizzadelivery/GeneratedAnalyticsEvents.kt
    documentation: true
    packageName: com.example.pizzadelivery
events:
  - id: A0CNO9LW4q2jgr8s4nsrU      # Uses latest version
  - id: Aae9pNlfoawHFaeM4ClwC
    version: 2                      # Specific version
  - id: Jd2R6diazU2cWzVguI8Rq

Adding Events Command Reference

The eventpanel add command provides multiple ways to add events:

Command	Description
eventpanel add <event-id>	Add latest version of an event by ID
eventpanel add <event-id> --version <version>	Add specific version of an event
eventpanel add --name <event-name>	Add latest version of an event by name
eventpanel add --all	Add all available events for the configured source
eventpanel add --category-id <id>	Add all events from a category by ID
eventpanel add --category-name <name>	Add all events from a category by name

Options:

• --scheme-update / --no-scheme-update: Control whether to apply scheme updates during generation (default: enabled)

Build Integration

The code generation can be integrated into your build process:

1. Automatic (Recommended): Runs before each build via Gradle task dependency (generateAnalyticsEvents)
2. Manual: Run ./gradlew generateAnalyticsEvents or eventpanel generate when needed
3. CI/CD: Include generation step in your CI pipeline

Troubleshooting

CLI Not Found

If you get command not found: eventpanel:

1. Verify installation: eventpanel --version
2. Check PATH: echo $PATH
3. Restart your terminal or IDE

Generation Errors

• Invalid YAML: Check your EventPanel.yaml syntax
• Missing Events: Ensure event IDs exist in your EventPanel workspace
• Path Issues: Verify generatedEventsPath exists and is writable

Build Issues

• Ensure Kotlin plugin is applied
• Check that generated files are included in your source sets
• Verify file paths match your project structure

Best Practices

1. Version Control: Commit EventPanel.yaml but consider ignoring generated files
2. CI/CD: Run generation in your CI pipeline for consistency
3. Code Review: Review generated code changes when event schemas update
4. Documentation: Use the documentation: true option for inline docs

Learn More

• 🚀 EventPanel CLI
• 🌐 EventPanel Website
• 📚 Android Documentation