Skip to main content

​
Overview

This guide covers complete installation of the Stringboot iOS SDK, including analytics integration for A/B testing. Follow all steps to unlock the full capabilities of dynamic strings, translations, and experiments.
A/B Testing Setup is Included: This guide includes analytics handler and device ID configuration required for experiments. These are core features, not optional add-ons.

​
Step 1: Add Swift Package Dependency

In Xcode, navigate to File → Add Packages and enter the repository URL: 
https://github.com/Stringboot-SDK/stringboot-ios-sdk.git
Select: Up to next major version = 1.2.0

​
Alternative: Package.swift

Add to your Package.swift:
Package.swift
dependencies: [
    .package(
        url: "https://github.com/Stringboot-SDK/stringboot-ios-sdk.git",
        from: "1.2.0"
    )
]

targets: [
    .target(
        name: "YourApp",
        dependencies: ["StringbootSDK"]
    )
]

​
Step 2: Import SDK

In files where you use Stringboot: 
import StringbootSDK

​
Step 3: Analytics Handler (Required for A/B Testing)

​
Why Analytics Integration is Required

The analytics handler enables:
  • Experiment tracking: Know which users see which variants
  • Results analysis: Measure impact of string changes
  • Data-driven decisions: Use analytics platforms for statistical analysis
  • Firebase Analytics
  • Mixpanel
  • Amplitude
  • Custom Analytics

​
Add Firebase Package

In Xcode: File → Add Packages → Add Firebase:
https://github.com/firebase/firebase-ios-sdk.git
Select: FirebaseAnalytics product

​
Implement Analytics Handler

App.swift
import SwiftUI
import StringbootSDK
import FirebaseCore
import FirebaseAnalytics

// Define analytics handler
class FirebaseAnalyticsHandler: StringbootAnalyticsHandler {
    func onExperimentsAssigned(experiments: [String: ExperimentAssignment]) {
        for (key, assignment) in experiments {
            // Set user property in Firebase
            Analytics.setUserProperty(
                assignment.variantName,
                forName: "stringboot_exp_\(key)"
            )

            print("📊 Experiment: \(key) → \(assignment.variantName)")
        }
    }
}

@main
struct MyApp: App {

    init() {
        // Initialize Firebase
        FirebaseApp.configure()

        // Configure logging
        StringbootLogger.isLoggingEnabled = true
        StringbootLogger.logLevel = .debug

        // Initialize Stringboot with analytics
        StringProvider.shared.initialize(
            cacheSize: 1000,
            apiToken: "YOUR_API_TOKEN",
            baseURL: "https://api.stringboot.com",
            autoSync: true,
            analyticsHandler: FirebaseAnalyticsHandler()
        )

        // Set language
        let currentLang = UserDefaults.standard.string(forKey: "com.stringboot.currentLanguage")
            ?? StringProvider.shared.deviceLocale()
        StringProvider.shared.setLocale(currentLang)
    }

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

​
Step 4: Device ID Configuration (Required for A/B Testing)

​
Why Device ID is Required

  • Consistent assignments: Same device always gets same variant
  • Cross-session persistence: Experiments persist across app restarts
  • Accurate results: Users don’t switch between variants randomly
  • Auto-Generated (Default)
  • Firebase Installation ID
  • Custom Device ID
By default, the SDK generates a persistent UUID per app installation:
App.swift
@main
struct MyApp: App {

    init() {
        // SDK automatically generates and persists a UUID
        StringProvider.shared.initialize(
            cacheSize: 1000,
            apiToken: "YOUR_API_TOKEN",
            baseURL: "https://api.stringboot.com",
            autoSync: true,
            analyticsHandler: YourAnalyticsHandler()
            // providedDeviceId not specified - SDK generates UUID
        )
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
Characteristics:
  • Persists across app launches
  • Unique per app installation
  • Automatically managed by SDK
  • Use this unless you have a specific reason to use custom ID

​
Step 5: Configure Logger (Optional)

Control SDK logging for debugging:
App.swift
@main
struct MyApp: App {

    init() {
        // Enable detailed logging for development
        StringbootLogger.isLoggingEnabled = true
        StringbootLogger.logLevel = .debug  // Options: .debug, .info, .warning, .error

        // Initialize SDK...
    }
}
For production builds: 
// Disable logging
StringbootLogger.isLoggingEnabled = false

​
Complete Setup Example

Here’s a complete SwiftUI app with all components:
App.swift
import SwiftUI
import StringbootSDK
import FirebaseCore
import FirebaseAnalytics
import FirebaseInstallations

// Analytics handler for experiments
class FirebaseAnalyticsHandler: StringbootAnalyticsHandler {
    func onExperimentsAssigned(experiments: [String: ExperimentAssignment]) {
        for (key, assignment) in experiments {
            Analytics.setUserProperty(
                assignment.variantName,
                forName: "stringboot_exp_\(key)"
            )
            print("📊 Experiment: \(key) → \(assignment.variantName)")
        }
    }
}

@main
struct MyApp: App {

    init() {
        // Initialize Firebase
        FirebaseApp.configure()

        // Configure Stringboot logging (disable in production)
        StringbootLogger.isLoggingEnabled = true
        StringbootLogger.logLevel = .debug

        // Get device ID asynchronously
        Task {
            let deviceId = await getFirebaseInstallationId()

            // Initialize Stringboot with all features
            StringProvider.shared.initialize(
                cacheSize: 1000,
                apiToken: "YOUR_API_TOKEN",
                baseURL: "https://api.stringboot.com",
                autoSync: true,
                providedDeviceId: deviceId,
                analyticsHandler: FirebaseAnalyticsHandler()
            )

            print("✅ Stringboot initialized")

            // Set saved language or use device locale
            let currentLang = UserDefaults.standard.string(forKey: "com.stringboot.currentLanguage")
                ?? StringProvider.shared.deviceLocale()
            StringProvider.shared.setLocale(currentLang)

            print("🌍 Language set to: \(currentLang)")
        }
    }

    private func getFirebaseInstallationId() async -> String? {
        do {
            return try await Installations.installations().installationID()
        } catch {
            print("⚠️ Failed to get Firebase Installation ID: \(error)")
            return nil // SDK will generate UUID
        }
    }

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

​
Step 6: Verify Setup

​
Test SDK Initialization

  1. Run your app with debug logging enabled
  2. Check Console for Stringboot initialization messages:
✅ Stringboot initialized
🌍 Language set to: en

​
Test String Retrieval

Add a test in your ContentView:
ContentView.swift
struct ContentView: View {
    @State private var testString = ""

    var body: some View {
        Text(testString)
            .task {
                testString = await StringProvider.shared.get("welcome_message", lang: "en")
                print("String value: \(testString)")
                // Should NOT see "??welcome_message??" (means string loaded)
            }
    }
}

​
Test Experiment Assignment

If you have experiments running: 
// Check device ID
if let deviceId = StringProvider.shared.getDeviceId() {
    print("Device ID: \(deviceId)")
}

// Look for experiment logs
// 📊 Experiment: cta-test → variant-a

​
Verify Analytics Integration

  1. Check your analytics platform (Firebase/Mixpanel/Amplitude)
  2. Look for user properties like stringboot_exp_cta_test
  3. Value should be variant name: control, variant-a, etc.

​
Common Setup Issues

Cause: Package dependency conflict or incorrect versionSolution:
  1. File → Packages → Reset Package Caches
  2. Clean build folder (Cmd+Shift+K)
  3. Rebuild project
  4. Verify version is 1.2.0 or higher
Possible causes:
  1. No experiments running in dashboard
  2. Analytics handler not passed to initialize()
  3. Device not assigned to any experiments
Solutions:
  • Create test experiment in dashboard
  • Verify analyticsHandler parameter is set
  • Check device ID is being sent with requests
Causes:
  1. API token invalid
  2. No network connectivity
  3. Strings not created in dashboard
  4. SDK not initialized yet
Solutions:
  • Verify API token in dashboard
  • Check network permissions
  • Ensure strings exist for your app
  • Wait for SDK isReady before fetching
Cause: Using non-persistent ID or regenerating UUIDSolution:
  • Use default SDK-generated UUID (it persists automatically)
  • If using custom ID, store it in UserDefaults
  • Don’t generate new UUID on each launch
Cause: Package not properly linkedSolution:
  1. File → Packages → Resolve Package Versions
  2. Check target has StringbootSDK in Frameworks
  3. Clean and rebuild

​
Platform Requirements

RequirementVersion
Minimum iOS14.0+
Minimum macOS11.0+
Swift5.9+
Xcode15.0+
SDK Version1.2.0

​
Next Steps

Now that setup is complete, learn how to use the three core features:

Dynamic Strings

Update app copy without releases

Translations

Multi-language support and switching

A/B Testing

Run experiments to optimize messaging

​
Additional Resources

Best Practices

Production-ready patterns

Advanced Usage

Advanced patterns and optimization

Core Concepts

Architecture and offline behavior

Troubleshooting

Common issues and solutions
Questions? Contact [email protected]