iOS Codegen Setup

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

Demo Project: View iOS Demo on GitHub →

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

Overview

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

Features

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

Installation

Prerequisites

• Xcode 14.0 or later
• Swift 5.7 or later
• macOS 12.0 or later

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 DemoApp/Analytics/GeneratedAnalyticsEvents.swift

This command will:

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

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

• DemoApp/Analytics/GeneratedAnalyticsEvents.swift
• YourApp/Sources/Analytics/GeneratedAnalyticsEvents.swift
• App/Analytics/GeneratedAnalyticsEvents.swift

The generated EventPanel.yaml will look like:

source: iOS
plugin:
  swiftgen:
    eventTypeName: AnalyticsEvent
    outputFilePath: DemoApp/Analytics/GeneratedAnalyticsEvents.swift
    shouldGenerateType: true
    namespace: AnalyticsEvents
    documentation: true
events: []

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

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
  - id: YOUR_EVENT_ID_2
    version: 2

Step 4: Configure Xcode Build Phase

Add a "Run Script" build phase to your Xcode project:

1. Open your project in Xcode
2. Select your target
3. Go to Build Phases tab
4. Click + and select New Run Script Phase
5. Name it "GenerateAnalytics"
6. Add the following script:

# Detect EventPanel CLI installation
if command -v eventpanel &> /dev/null; then
    eventpanel generate
else
    echo "Error: EventPanel CLI not found. Please install it using: brew install eventpanel"
    exit 1
fi

7. Move the script phase before "Compile Sources"
8. Ensure "For install builds only" is unchecked
9. Specify Input Files as $(SRCROOT)/EventPanel.yaml
10. Specify Output Files as $(DERIVED_FILE_DIR)/DemoApp/Analytics/GeneratedAnalyticsEvents.swift

Step 5: Generate Analytics Code

The code generation will run automatically during Xcode builds. You can also run it manually:

eventpanel generate

Usage

Basic Event Tracking

import Analytics

// Track a simple event
let event = AnalyticsEvents.ProfileScreen.profileScreenShown()
analytics.track(event)

// Track event with parameters
let onboardingEvent = AnalyticsEvents.onboardingScreenShown(origin: .facebook)
analytics.track(onboardingEvent)

// Track event with optional parameters
let loadingEvent = AnalyticsEvents.loadingScreenShown(cityId: "NYC")
analytics.track(loadingEvent)

Generated Code Structure

The CLI generates Swift code in the following structure:

DemoApp/
├── Analytics/
│   └── GeneratedAnalyticsEvents.swift # Generated event code

Example Generated Events

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

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

enum Origin {
    case facebook
    case google
    case email
}

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

Configuration Reference

EventPanel.yaml Structure

language: swift                     # Target language
plugin:
  swiftgen:
    documentation: true             # Include documentation comments
    generatedEventsPath: DemoApp/Analytics/GeneratedAnalyticsEvents.swift
    eventTypeName: AnalyticsEvent   # Base event type name
    namespace: AnalyticsEvents      # Namespace for generated code
events:
  - id: EVENT_ID                   # Event ID from EventPanel
    version: 1                      # Event schema version

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)

Example Configuration

After running eventpanel init, your EventPanel.yaml will be created. You can then add events:

language: swift
plugin:
  swiftgen:
    documentation: true
    generatedEventsPath: DemoApp/Analytics/GeneratedAnalyticsEvents.swift
    eventTypeName: AnalyticsEvent
    namespace: AnalyticsEvents
events:
  - id: 7MJ5DRg_a7xrf8ZzeKmDb  # Onboarding Screen Shown
    version: 3
  - id: iarZdDsKOfAmxMN3rfTtd  # Loading Screen Shown
    version: 4
  - id: akn-KX7E0Of8d2L_PLBbW  # Profile Screen Shown
    version: 1
  - id: Z0EhrWP91qyabKCziBJBQ  # Profile Screen Closed
    version: 1

Tip: You can also manage events through the EventPanel web interface, and they will be synced to your EventPanel.yaml file.

Project Structure Example

DemoApp/
├── Analytics/
│   ├── AnalyticsEvent.swift          # Base analytics event protocol
│   └── GeneratedAnalyticsEvents.swift # Generated event code
├── ContentView.swift                 # Main SwiftUI view
├── ContentViewModel.swift           # View model with analytics
└── DemoAppApp.swift                 # App entry point

Authentication

Setting API Token

The EventPanel CLI requires authentication to fetch event schemas from your workspace. After running eventpanel init, you must set your API token:

eventpanel set-token YOUR_API_TOKEN

How to get your API token:

1. Log in to EventPanel web interface
2. Navigate to your workspace settings
3. Go to the API tokens section
4. Create a new token
5. Copy the token and use it with the set-token command

The token is securely stored locally and will be used for all authenticated CLI operations.

Verifying Authentication

After setting the token, you can verify it works by running:

eventpanel generate

If authentication fails, you'll see an error message. Make sure:

• The token is valid and not expired
• The token has the necessary permissions for your workspace
• You're connected to the internet

Troubleshooting

CLI Not Found

If you get command not found: eventpanel:

1. Verify installation: eventpanel --version
2. Check Homebrew: brew list eventpanel
3. Check PATH: echo $PATH
4. Restart Xcode after installation

Build Phase Errors

• Script not running: Ensure the build phase is before "Compile Sources"
• Permission denied: Check script execution permissions
• Path issues: Verify generatedEventsPath exists and is writable

Generation Errors

• Invalid YAML: Check your EventPanel.yaml syntax
• Missing Events: Ensure event IDs exist in your EventPanel workspace
• Swift version: Verify compatibility with your Swift version

Xcode Issues

• Clean Build Folder: Product → Clean Build Folder (⇧⌘K)
• Derived Data: Delete derived data if issues persist
• Restart Xcode: Sometimes Xcode needs a restart after CLI installation

Best Practices

1. Version Control: Commit EventPanel.yaml but consider ignoring generated files
2. Build Integration: Use build phases for automatic generation
3. Code Review: Review generated code changes when event schemas update
4. Documentation: Use the documentation: true option for inline docs
5. Testing: Test analytics events in your test suite

Advanced Usage

Custom Event Types

The generated code supports custom types and enums:

// Events with custom enums
let event = AnalyticsEvents.onboardingScreenShown(origin: .facebook)

// Events with optional parameters
let loadingEvent = AnalyticsEvents.loadingScreenShown(cityId: nil)

Integration with Analytics SDKs

// Example with a custom analytics service
class AnalyticsService {
    func track(_ event: AnalyticsEvent) {
        // Convert to your analytics SDK format
        yourAnalyticsSDK.track(event.name, parameters: event.parameters)
    }
}

Learn More

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