​

Swift Troubleshooting Guide

This guide addresses common issues you might encounter when integrating Capsule with your Swift iOS application. It provides solutions and best practices to ensure a smooth integration.

​

General Troubleshooting Steps

Before diving into specific issues, try these general troubleshooting steps:

1. Clean the build folder: In Xcode, go to Product > Clean Build Folder

2. Update dependencies: If you’re using CocoaPods:

   pod update
   

   If you’re using Swift Package Manager, update packages in Xcode.

3. Ensure Capsule SDK is up to date: Check your Podfile or Swift Package Manager configuration and update to the latest version if necessary.

4. Rebuild the project: In Xcode, go to Product > Build

​

Common Issues and Solutions

​

1. Package Integration Issues

Problem: Xcode can’t find the Capsule package or there are integration errors.

Solution: Ensure the Capsule SDK is properly integrated into your project.

For Swift Package Manager:

1. In Xcode, go to File > Swift Packages > Add Package Dependency
2. Enter the Capsule SDK repository URL
3. Select the version you want to use

For CocoaPods:

1. Ensure your Podfile includes:

   pod 'CapsuleSwift'
   

2. Run pod install in your terminal
3. Use the .xcworkspace file to open your project

​

2. Minimum iOS Version Incompatibility

Problem: Compiler errors due to unsupported iOS version.

Solution: Ensure your project’s minimum deployment target is compatible with Capsule SDK.

1. In Xcode, select your project in the navigator
2. Go to the “General” tab
3. Under “Deployment Info”, set “Minimum Deployments” to iOS 13.0 or later (or the minimum version required by Capsule)

​

3. Initialization Errors

Problem: Capsule fails to initialize or throws errors on startup.

Solution: Ensure proper initialization in your AppDelegate or SceneDelegate:

import CapsuleSwift

class AppDelegate: UIResponder, UIApplicationDelegate {
    let capsule = CapsuleSwift.Capsule(environment: .beta(jsBridgeUrl: nil), apiKey: "YOUR_API_KEY")

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        return true
    }

    // ... other AppDelegate methods
}

​

4. Asynchronous Operation Errors

Problem: Errors when performing asynchronous operations with Capsule.

Solution: Ensure proper use of Swift concurrency (async/await) and error handling:

func createUser(email: String) async {
    do {
        try await capsule.createUser(email: email)
        // Handle successful user creation
    } catch {
        print("Error creating user: \(error)")
        // Handle error appropriately
    }
}

​

5. UI Thread Blocking

Problem: Capsule operations blocking the main thread.

Solution: Ensure all Capsule operations are performed on background threads:

DispatchQueue.global(qos: .userInitiated).async {
    Task {
        do {
            let wallet = try await self.capsule.createWallet()
            // Handle wallet creation
            DispatchQueue.main.async {
                // Update UI
            }
        } catch {
            print("Error: \(error)")
        }
    }
}

​

6. Keychain Access Issues

Problem: Errors related to keychain access for storing sensitive data.

Solution: Ensure proper keychain access and entitlements:

1. In your project’s Capabilities tab, enable “Keychain Sharing”
2. If necessary, add a keychain access group in your entitlements file

​

7. Network-Related Issues

Problem: Network calls failing or timing out.

Solution: Ensure proper network permissions and handling:

1. Add the following to your Info.plist:

   <key>NSAppTransportSecurity</key>
   <dict>
       <key>NSAllowsArbitraryLoads</key>
       <true/>
   </dict>
   

2. Implement proper network reachability checks and error handling

​

Best Practices

1. Use the Latest Versions: Always use the latest versions of Xcode, Swift, and Capsule SDK to ensure compatibility and access to the latest features.

2. Error Handling: Implement robust error handling for all Capsule operations. Use Swift’s do-catch blocks and custom error types if necessary.

3. Secure Storage: Use Keychain Services for storing sensitive data related to Capsule operations.

4. Concurrency: Leverage Swift’s concurrency features (async/await) for cleaner asynchronous code.

5. Memory Management: Be mindful of retain cycles, especially when using closures with Capsule operations.

6. Testing: Write unit and integration tests for your Capsule integration to catch issues early. Use XCTest framework for testing.

7. Localization: If your app supports multiple languages, ensure all user-facing strings related to Capsule are properly localized.

8. App Transport Security: Ensure your app’s ATS settings are configured correctly for Capsule’s network communications.

​

Debugging Tips

1. Enable Verbose Logging: If available, enable verbose logging for Capsule operations to get more detailed information.

2. Use Breakpoints: Set breakpoints in your Capsule integration code to step through and identify issues.

3. Network Debugging: Use tools like Charles Proxy or Xcode’s network debugger to inspect network calls made by Capsule.

4. Memory Debugging: Use Xcode’s Memory Graph Debugger to identify any memory leaks or retain cycles involving Capsule objects.

5. Simulator vs Real Device: Test your Capsule integration on both the iOS Simulator and real devices, as some issues may only appear on physical devices.

By following these troubleshooting steps and best practices, you should be able to resolve most common issues when integrating Capsule with your Swift iOS application.

​

Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your request:

1. 1

   A detailed description of the problem you’re encountering.

2. 2

   Any relevant error messages or logs.

3. 3

   Steps to reproduce the issue.

4. 4

   Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.