> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API reference for the Swift SDK

## Methods

### Muta.configure()

Initializes the SDK with your API key.

```swift theme={null}
Muta.configure(apiKey: String)
```

#### Parameters

| Parameter | Type     | Required | Description       |
| --------- | -------- | -------- | ----------------- |
| `apiKey`  | `String` | Yes      | Your Muta API key |

### Muta.shared.displayPlacement()

Displays a placement in a modal overlay.

```swift theme={null}
// Using SwiftUI Color
func displayPlacement(
    placementId: String,
    backgroundColor: Color = .white,
    presentationType: PresentationType = .slide,
    loadingView: AnyView? = nil,
    injectedScreens: [InjectedScreen] = []
)

// Using hex color string
func displayPlacement(
    placementId: String,
    backgroundHexColor: String,
    presentationType: PresentationType = .slide,
    loadingView: AnyView? = nil,
    injectedScreens: [InjectedScreen] = []
)
```

#### Parameters

| Parameter            | Type               | Required | Description                                                                                                         |
| -------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `placementId`        | `String`           | Yes      | The ID of the placement to display                                                                                  |
| `backgroundColor`    | `Color`            | No       | Background color that matches your first placement screen. Defaults to white.                                       |
| `backgroundHexColor` | `String`           | No       | Background color as a hex string. Alternative to backgroundColor.                                                   |
| `presentationType`   | `PresentationType` | No       | Animation style when showing the placement. Defaults to .slide                                                      |
| `loadingView`        | `AnyView?`         | No       | A custom SwiftUI view to show while the placement is loading                                                        |
| `injectedScreens`    | `[InjectedScreen]` | No       | Array of native SwiftUI views to inject into code screens. See [Code Screens](/sdk/swift/code-screens) for details. |

### Muta.shared.on()

Subscribe to Muta events.

```swift theme={null}
// Subscribe to all events
func on(_ handler: @escaping (MutaEvent) -> Void) -> Subscription

// Subscribe to specific event type
func on<T: MutaEvent>(_ type: T.Type, handler: @escaping (T) -> Void) -> Subscription
```

#### Parameters

| Parameter | Type                  | Required | Description                                             |
| --------- | --------------------- | -------- | ------------------------------------------------------- |
| `handler` | `(MutaEvent) -> Void` | Yes      | The closure to be called when any event occurs          |
| `type`    | `T.Type`              | Yes      | The specific event type to listen for                   |
| `handler` | `(T) -> Void`         | Yes      | The closure to be called when the specific event occurs |

#### Returns

A `Subscription` object that can be used to unsubscribe from the event.

## Types

### MutaEvent

Base protocol for all Muta events.

```swift theme={null}
protocol MutaEvent {
    var timestamp: Int { get }
    var placementId: String { get }
    var flowName: String? { get }
}
```

### FlowStartedEvent

```swift theme={null}
struct FlowStartedEvent: MutaEvent {
    let timestamp: Int
    let placementId: String
    let flowName: String?
    let totalScreens: Int
}
```

### ScreenViewedEvent

```swift theme={null}
struct ScreenViewedEvent: MutaEvent {
    let timestamp: Int
    let placementId: String
    let flowName: String?
    let screenIndex: Int
    let totalScreens: Int
    let screenName: String?
}
```

### FlowCompletedEvent

```swift theme={null}
struct FlowCompletedEvent: MutaEvent {
    let timestamp: Int
    let placementId: String
    let flowName: String
    let screenIndex: Int
    let totalScreens: Int
    let screenName: String
    let eventData: [String: Any]?  // Contains variables collected during the flow
}
```

### FlowAbandonedEvent

```swift theme={null}
struct FlowAbandonedEvent: MutaEvent {
    let timestamp: Int
    let placementId: String
    let flowName: String?
    let screenIndex: Int
    let totalScreens: Int
    let lastScreenIndex: Int
    let screenName: String?
}
```

### CodeScreenDisplayedEvent

```swift theme={null}
struct CodeScreenDisplayedEvent {
    let screenId: String
    let screenName: String
    let timestamp: Int
}
```

### CodeScreenActionEvent

```swift theme={null}
struct CodeScreenActionEvent {
    let action: String         // "continue" or "back"
    let screenId: String
    let screenName: String
    let timestamp: Int
}
```

### CustomEvent

```swift theme={null}
struct CustomEvent: MutaEvent {
    let type: String           // Your custom event name
    let timestamp: Int
    let placementId: String
    let flowName: String?
    let screenIndex: Int?
    let eventData: [String: Any]?  // Custom data from the editor
}
```

#### Usage Example

```swift theme={null}
// Listen for custom events configured in the Muta editor
let subscription = Muta.shared.on(CustomEvent.self) { event in
    switch event.type {
    case "signup_started":
        // Handle signup button click
        navigateToSignup()
        
    case "plan_selected":
        // Handle plan selection with custom data
        if let planType = event.eventData?["planType"] as? String {
            selectPlan(planType)
        }
        
    case "survey_completed":
        // Handle survey completion
        if let answers = event.eventData?["answers"] as? [String: Any] {
            saveSurveyData(answers)
        }
        
    default:
        break
    }
}
```

### InjectedScreen

```swift theme={null}
struct InjectedScreen {
    let screenName: String                               // Must match name in Muta editor
    let view: (CodeScreenContext) -> AnyView             // Factory function for the view
}
```

### CodeScreenContext

```swift theme={null}
struct CodeScreenContext {
    let onContinue: () -> Void                           // Navigate to configured continue destination
    let onBack: () -> Void                               // Navigate to configured back destination
    let variables: [[String: Any]]                       // Current flow variables
    let screenId: String                                 // Unique screen ID
    let screenIndex: Int                                 // Screen position in flow
}
```

#### Usage Example

```swift theme={null}
// Inject a login screen into your flow
Muta.shared.displayPlacement(
    placementId: "onboarding",
    backgroundColor: .black,
    injectedScreens: [
        InjectedScreen(
            screenName: "Login Screen",
            view: { context in
                AnyView(LoginScreen(context: context))
            }
        )
    ]
)
```

### ErrorEvent

```swift theme={null}
enum ErrorEvent {
    case network(message: String, timestamp: Int)
    case placement(message: String, code: String, timestamp: Int, placementId: String)
}
```

## Example Usage

```swift theme={null}
import SwiftUI
import MutaSDK

@main
struct YourApp: App {
    init() {
        Muta.configure(apiKey: "your-api-key")
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

struct ContentView: View {
    var body: some View {
        Button("Show Placement") {
            Muta.shared.displayPlacement(
                placementId: "your-placement-id",
                backgroundColor: .white,
                presentationType: .fade,
                loadingView: AnyView(
                    VStack {
                        ProgressView()
                        Text("Loading...")
                    }
                )
            )
        }
    }
} 
```