Troubleshooting

Troubleshooting

Common Issues

1. SDK Initialization Fails

Problem: Initialization throws an error (e.g., AlphynSDKError.invalidInterval)

// ❌ Common mistakes
// try await AlphynSDK.initialize(interval: 5)  // Interval too small (must be > 8)
// try await AlphynSDK.initialize(interval: -1) // Invalid interval
// try AlphynSDK.initialize(interval: 45)       // Missing `await` - initialize is async

Solution:

// ✅ Correct initialization (initialize is `async throws`)
Task {
    do {
        try await AlphynSDK.initialize(interval: 45)
        print("Alphyn SDK initialized successfully.")
    } catch {
        print("Alphyn SDK initialization failed: \(error)")
    }
}

2. XCFramework Linking Issues

Problem: App crashes with errors like “dyld: Library not loaded: @rpath/Alphyn.framework/Alphyn” or “Undefined symbols for architecture...”.

Solution:

• For a CLI or Swift Package Manager integration, the framework resolves from the Alphyn package registry through the generated Swift package. If it fails to resolve, confirm your ~/.netrc carries the registry entry (see SDK Registry Access) and re-resolve packages in Xcode (File > Packages > Resolve Package Versions), then rebuild.
• For a manual (offline) embed, ensure that Alphyn.xcframework is correctly linked in your target’s “Frameworks, Libraries, and Embedded Content” and set to “Embed & Sign”.
• Clean and rebuild your project (Product > Clean Build Folder Remove DerivedData then Product > Build).
• Verify that your project’s “Header Search Paths” and “Library Search Paths” are correctly configured if you are integrating manually outside of the standard Xcode drag-and-drop.

Debug Information

Enable Debug Logging:

import Alphyn
import Foundation

class DebugSecurityListener: AlphynSecurityListener {
    private let tag = "AlphynDebug"

    func onSuccess(_ result: AlphynCallbackResult) {
        print("\(tag) SUCCESS: \(result.operationType) | \(result.originalEventType) | \(result.message)")
    }

    func onFailure(_ result: AlphynCallbackResult) {
        print("\(tag) FAILURE: \(result.operationType) | \(result.originalEventType) | \(result.message) | \(result.details ?? "No details")")
    }

    func onThreatDetected(_ result: AlphynCallbackResult) {
        print("\(tag) THREAT: \(result.originalEventType) | \(result.message)")
    }
}