Swift SDK

Installation

Add the FeedbackKit Swift SDK to your project using Swift Package Manager.

Xcode

1. 1 Open your project in Xcode
2. 2 Go to File → Add Package Dependencies
3. 3 Enter the repository URL: https://github.com/Swiftly-Developed/SwiftlyFeedbackKit-Swift-SDK.git
4. 4 Select version 1.3.0 (Up to Next Major). Code written for 1.1.1 or earlier needs the migration notes, or pin Up to Next Minor from 1.1.1.
5. 5 Add the SwiftlyFeedbackKit product. Trust the string-catalog build plugin when Xcode asks. CI passes -skipPackagePluginValidation.

Package.swift

dependencies: [
    .package(
        url: "https://github.com/Swiftly-Developed/SwiftlyFeedbackKit-Swift-SDK.git",
        from: "1.3.0"
    )
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "SwiftlyFeedbackKit", package: "SwiftlyFeedbackKit")
        ]
    )
]

Quick Start

Initialize the SDK with your project API key in your app's entry point and start using the pre-built SwiftUI views.

import SwiftUI
import SwiftlyFeedbackKit

@main
struct MyApp: App {
    init() {
        // Configure SDK per build environment
        #if DEBUG
        SwiftlyFeedback.configure(
            environment: .development,
            key: "your-dev-api-key"
        )
        #elseif TESTFLIGHT
        SwiftlyFeedback.configure(
            environment: .testflight,
            key: "your-staging-api-key"
        )
        #else
        SwiftlyFeedback.configure(
            environment: .production,
            key: "your-prod-api-key"
        )
        #endif
    }

    var body: some Scene {
        WindowGroup {
            FeedbackListView()
        }
    }
}

Auto-Detection Configuration

Alternatively, use configureAuto to automatically detect the build environment and select the appropriate API key.

import SwiftlyFeedbackKit

@main
struct MyApp: App {
    init() {
        // Auto-detect environment and use appropriate key
        SwiftlyFeedback.configureAuto(keys: EnvironmentAPIKeys(
            debug: "your-dev-key",         // Development API. Nil uses the testflight key.
            testflight: "your-staging-key",  // Staging server
            production: "your-prod-key"      // App Store
        ))
    }

    var body: some Scene {
        WindowGroup {
            FeedbackListView()
        }
    }
}

Configuration

configure(environment:key:) picks the server. configureAuto(keys:) picks the key from the build type. A DEBUG build talks to the development API. Localhost is only .local.

Settings live on SwiftlyFeedback.configuration. Set them on the main actor.

Configuration Example

// Main-actor settings. Call from App.init or a SwiftUI view.
SwiftlyFeedback.configuration.loggingEnabled = false
SwiftlyFeedback.configuration.userEmail = "user@example.com"
SwiftlyFeedback.configuration.allowFeedbackSubmission = false
SwiftlyFeedback.configuration.feedbackSubmissionDisabledMessage = "Coming soon!"
SwiftlyFeedback.configuration.showVoteEmailField = false
SwiftlyFeedback.configuration.voteNotificationDefaultOptIn = true

config, theme, and shared still compile. They are deprecated shims for configuration, appearance, and current. New code uses the new names. current stays nil until configure finishes resolving a user id.

Views

The SDK provides pre-built SwiftUI views that can be easily integrated into your app.

import SwiftUI
import SwiftlyFeedbackKit

struct ContentView: View {
    var body: some View {
        // Use default instance
        FeedbackListView()

        // Or pass a custom instance
        FeedbackListView(swiftlyFeedback: SwiftlyFeedback.current)
    }
}

import SwiftUI
import SwiftlyFeedbackKit

struct ContentView: View {
    @State private var showingSubmitForm = false

    var body: some View {
        Button("Submit Feedback") {
            showingSubmitForm = true
        }
        .sheet(isPresented: $showingSubmitForm) {
            SubmitFeedbackView {
                showingSubmitForm = false
            }
        }
    }
}

import SwiftUI
import SwiftlyFeedbackKit

struct FeedbackRow: View {
    let feedback: Feedback

    var body: some View {
        NavigationLink {
            FeedbackDetailView(feedback: feedback)
        } label: {
            Text(feedback.title)
        }
    }
}

API Reference

Instance methods run on SwiftlyFeedback.current, which is nil until configure finishes. view is static.

import SwiftlyFeedbackKit

guard let client = SwiftlyFeedback.current else { return }

// Get all feedback
let feedbacks = try await client.getFeedback()

// Submit feedback
let feedback = try await client.submitFeedback(
    title: "Add dark mode",
    description: "Please add dark mode support",
    category: .featureRequest,
    email: "user@example.com"
)

// Vote for feedback
let result = try await client.vote(
    for: feedback.id,
    email: "user@example.com",
    notifyStatusChange: true
)

// Remove a vote
try await client.unvote(for: feedback.id)

// Get comments
let comments = try await client.getComments(for: feedback.id)

// Add comment
let comment = try await client.addComment(
    to: feedback.id,
    content: "Great idea!"
)

// Track an event. view is static. Property values are strings.
SwiftlyFeedback.view("onboarding_completed", properties: [
    "steps": "5"
])

Models

User ID

The SDK picks an id in this order: a custom id from updateUser(customID:), a Keychain id, an iCloud record name (prefix icloud_, 3 second timeout), then a generated UUID (prefix local_). A custom id updates the live client. updateUser(email:) is a deprecated no-op.

SwiftlyFeedback.updateUser(customID: "user_12345")
SwiftlyFeedback.updateUser(payment: .monthly(9.99))
UserIdentifier.clearUserId()

Theming

Set colors on SwiftlyFeedback.appearance on the main actor. Buttons and highlights read primaryColor. There is no accent color property. .default resolves to the system accent color.

ThemeColor

Theme Customization

import SwiftUI
import SwiftlyFeedbackKit

// Primary color for buttons and highlights
SwiftlyFeedback.appearance.primaryColor = .color(.purple)

// Light and dark values
SwiftlyFeedback.appearance.primaryColor = .adaptive(
    light: .blue,
    dark: .cyan
)

// Status and category colors are ThemeColor, not Color
SwiftlyFeedback.appearance.statusColors.pending = .color(.gray)
SwiftlyFeedback.appearance.statusColors.testflight = .color(.cyan)
SwiftlyFeedback.appearance.statusColors.completed = .color(.green)
SwiftlyFeedback.appearance.categoryColors.bugReport = .color(.red)

Events

Opening a list, detail, or submit screen records feedback_list, feedback_detail, or submit_feedback when enableAutomaticViewTracking is true. view is a static method. Property values are strings.

SwiftlyFeedback.view("checkout_completed", properties: [
    "plan": "pro"
])
SwiftlyFeedback.configuration.enableAutomaticViewTracking = false

Plan limits

The server enforces these numbers. The SDK does not. The Free feedback cap saves the row, marks isHiddenOverLimit, and omits it from list reads. That write is HTTP 2xx, not 402.

Platforms

Package.swift declares iOS 26, macOS 26, and visionOS 26. It does not declare watchOS or tvOS. The package compiles in Swift 6 language mode.

• iOS uses a form for submit and pull-to-refresh on the list. iPhone and iPad use a navigation split view.
• macOS uses a grid submit form, a 400 by 350 point minimum for submit, and Command-Return to submit. Command-R refreshes the list and the detail comments.
• visionOS runs the same list, submit, detail, and vote dialog. On-device translation is absent. There is no disabled control in its place.

Error Handling

The SDK uses the SwiftlyFeedbackError enum for error handling.

Error Handling Example

import SwiftlyFeedbackKit

do {
    let feedbacks = try await SwiftlyFeedback.current?.getFeedback()
} catch let error as SwiftlyFeedbackError {
    switch error {
    case .invalidApiKey:
        break
    case .feedbackLimitReached:
        break
    default:
        break
    }
}