iOS Integration

iOS Integration

Adding Alphyn SDK to Your Project

Recommended: the Alphyn CLI. alphyn-cli integrate --ios-api-key <key> generates a local Swift package that resolves Alphyn.xcframework from the Alphyn package registry as a checksum-pinned binaryTarget, wires it into your Xcode project, merges the required Info.plist keys, adds the launch hook, and installs the archive post-action that registers each build. Swift Package Manager authenticates to the registry through your ~/.netrc; see SDK Registry Access:

machine packages.byterialab.com login x password <YOUR_APP_API_KEY>

Then add import Alphyn in any Swift file where you interact with the SDK.

Manual, from the registry (no CLI). If you would rather wire the project yourself but still let the registry serve the framework, add Alphyn.xcframework as a checksum-pinned Swift Package Manager binaryTarget instead of embedding a downloaded copy. Ask the registry for the latest version, its zip URL and its checksum in one call — GET https://packages.byterialab.com/spm/latest (Basic auth: user x, password your app API key) returns {"version","url","checksum"} — then put them in a local Package.swift your project references (File → Add Package Dependencies → Add Local), and add a ~/.netrc entry so Swift Package Manager can authenticate to the registry:

Package.swift

.binaryTarget(
    name: "Alphyn",
    url: "https://packages.byterialab.com/spm/<version>/Alphyn.xcframework.zip",
    checksum: "<checksum from /spm/latest>"
)

~/.netrc

machine packages.byterialab.com login x password <YOUR_APP_API_KEY>

Then add import Alphyn where you use the SDK, and continue with the SDK Initialization steps below. The Info.plist keys and the archive post-action are the same as for the CLI path.

Manual XCFramework installation (offline). If your build cannot reach the registry, embed the self-contained Alphyn.xcframework directly:

1. Download the XCFramework: get Alphyn.xcframework from your app’s SDK Downloads page in the Alphyn dashboard. The download is gated by your app API key.
2. Add to Xcode: drag and drop the Alphyn.xcframework into your Xcode project’s “Frameworks, Libraries, and Embedded Content” section.
3. Embed & Sign: in the General tab of your target settings, ensure the framework is set to “Embed & Sign”.
4. Import in Swift files: add import Alphyn in any Swift file where you interact with the SDK.

SDK Initialization

For security and technical reasons, the Alphyn SDK should be initialized as early as possible in your application’s lifecycle. Initialization has two steps:

1. AlphynSDK.register() - registers the SDK’s background tasks with iOS. Must be called synchronously in application(_:didFinishLaunchingWithOptions:).
2. AlphynSDK.initialize(interval:) - starts the SDK. This method is async throws, so call it with try await (e.g. inside a Task).

import Alphyn
import UIKit

@main
@objc class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication
            .LaunchOptionsKey: Any]?
    ) -> Bool {
        // 1. Register Alphyn background tasks (synchronous, must run at launch)
        do {
            try AlphynSDK.register()
        } catch {
            print("AlphynSDK.register() failed: \(error.localizedDescription)")
        }

        // 2. Initialize AlphynSDK as early as possible (async)
        Task {
            do {
                try await AlphynSDK.initialize(interval: 45.0)
            } catch {
                // If you prefer a hard-fail security posture, replace this
                // with `try!` so the app cannot run unprotected.
                print("AlphynSDK initialization failed: \(error)")
            }
        }

        return true
    }
}

Parameters:

• interval: Interval in seconds between security scans (default 45). Must be greater than 8 seconds - otherwise AlphynSDKError.invalidInterval is thrown.
• debugHash (optional): a development-only hash from the Alphyn Portal, used when a dev build’s runtime hash does not match the registered one. Never ship it in production builds.
• vmScannerConfig (optional): runtime hints for the VM scanner (appUsesJSContext, appUsesMonoRuntime).

Best Practices:

• Call register() before the app finishes launching; background task registration cannot be deferred.
• Initialize as early as possible in the application lifecycle (e.g., AppDelegate.application(_:didFinishLaunchingWithOptions:)) for comprehensive protection.
• Ensure the interval parameter is valid (greater than 8 seconds) to avoid initialization failure.
• For a security-critical app you may deliberately crash on initialization failure (try! inside the Task) so the app never runs unprotected.
• Check initialization status with AlphynSDK.isInitialized() if your app logic depends on it.
• Obj-C hosts (or code that cannot use Swift concurrency) can use the synchronous wrappers initializeSync(interval:debugHash:) and registerSync().

Security Listener Implementation

Complete Listener Implementation:

import Alphyn

class MySecurityListener: AlphynSecurityListener {
    func onSuccess(_ result: AlphynCallbackResult) {
        print("Alphyn Success: \(result.operationType) - \(result.originalEventType) - \(result.message)")
    }

    func onFailure(_ result: AlphynCallbackResult) {
        print("Alphyn Failure: \(result.operationType) - \(result.originalEventType) - \(result.message) - \(result.details ?? "No details")")
    }

    func onThreatDetected(_ result: AlphynCallbackResult) {
        print("Alphyn Threat detected: \(result.originalEventType) - \(result.message)")
    }
}

Handling Security Events

Event Processing Example:

import Alphyn

extension MySecurityListener {
    func handleInitializationSuccess(result: AlphynCallbackResult) {
        if result.originalEventType == .firstInit {
            print("Alphyn First time initialization completed")
        } else if result.originalEventType == .initComplete {
            print("Alphyn SDK ready for use")
        }
    }

    func handleScanSuccess(result: AlphynCallbackResult) {
        if result.isScanResponse {
            let scanResult = result.getScanResult()
            print("Alphyn Scan completed: \(scanResult.displayName)")

            switch scanResult {
            case .trusted:
                print("Alphyn Application is trusted ✅")
            case .flagged:
                print("Alphyn Application flagged for review ⚠️")
            case .untrusted:
                print("Alphyn Application is untrusted 🚨")
            case .unknown, .initializationError:
                break
            }
        }
    }
}

---