Leitfaden für Swift

Mit unserem Swift SDK können Sie Haptik in Ihre iOS-, visionOS- und macOS-Apps integrieren.

1. Paket installieren
2. Haptik-Umgebung einrichten
3. Geräte verbinden

---

Voraussetzungen

• Xcode 16 oder neuer
• OS: iOS 13.0+, visionOS 2.0+, macOS 10.15+
• Internetverbindung, um die haptischen Events bei der Initialisierung herunterzuladen
• Nur macOS: bHaptics Player installiert und gestartet
• Eine bereitgestellte haptische Anwendung, die zu Ihrem Projekt passt
  • App ID und API Key der haptischen App

Wie Geräte verbunden werden

• iOS / visionOS: Das SDK verbindet sich direkt über Bluetooth LE mit den Haptikgeräten. Eine Begleit-App ist nicht erforderlich.
• macOS: Das SDK verbindet sich mit dem bHaptics Player, und der bHaptics Player verwaltet die Haptikgeräte. Koppeln Sie Ihre Geräte im bHaptics Player.

Sie verwenden auf jeder Plattform dieselbe API.

About haptic application

You can create and manage haptic apps in Developer Portal, a web-based tool.

If you're unfamiliar with haptic apps or haven't created one yet, please follow the Portal guide before proceeding.

Before linking a haptic app to your game project, make sure the haptic app meets the following requirements:

• At least one haptic event must be created.
• API Key must be generated.
  • There is no API Key by default. To generate one, go to the "API Key" tab and click "New" button.
• Haptic app must be deployed
  • If you see "Deploy Now" button in the upper right corner, click it to deploy your haptic app. Otherwise, if you can see "Up to date", it means that the latest haptic app has already been deployed.

Also, link process requires App ID and API Key. Go to the "Settings" tab, and check the App ID and API Key.

Installation

Installieren Sie das bHaptics Swift SDK mit dem Swift Package Manager.

1. Wählen Sie in Xcode File > Add Package Dependencies....
2. Geben Sie die Paket-URL ein: https://github.com/bhaptics/bhaptics-ios
3. Setzen Sie Dependency Rule auf Up to Next Major Version ab 1.0.1.
4. Fügen Sie die Bibliothek Bhaptics zu Ihrem App-Target hinzu.

Wenn Sie Abhängigkeiten in Package.swift verwalten, fügen Sie das Paket wie folgt hinzu:

Package.swift

dependencies: [
    .package(url: "https://github.com/bhaptics/bhaptics-ios", .upToNextMajor(from: "1.0.1"))
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [.product(name: "Bhaptics", package: "bhaptics-ios")]
    )
]

Pakete importieren

import BhapticsPlugin

Bluetooth-Berechtigung

iOS / visionOS: Fügen Sie NSBluetoothAlwaysUsageDescription (Privacy - Bluetooth Always Usage Description) zu den Info-Einstellungen Ihres App-Targets hinzu, zusammen mit einer Nachricht, die erklärt, warum Ihre App Bluetooth verwendet. Die Berechtigungsabfrage erscheint, wenn Sie BhapticsKit erstellen. Ohne diesen Schlüssel stürzt die App ab, sobald das SDK auf Bluetooth zugreift.

macOS: Wenn App Sandbox aktiviert ist, gehen Sie zu Signing & Capabilities > App Sandbox und aktivieren Sie Outgoing Connections (Client), damit sich das SDK mit dem bHaptics Player verbinden kann.

Haptik-Umgebung einrichten

Bevor Sie haptikbezogene Funktionen verwenden, müssen Sie die haptische App mit Ihrem Projekt verknüpfen und die Haptik-Umgebung initialisieren.

Dazu benötigen Sie die App ID und den API Key Ihrer haptischen App. Diese erhalten Sie im bHaptics Developer Portal.

Initialisieren

• Ersetzen Sie "your_app_id" und "your_api_key" durch Ihre App ID und Ihren API Key.
• Erstellen Sie eine einzige BhapticsKit-Instanz und behalten Sie sie während der gesamten Laufzeit Ihrer App bei.

import BhapticsPlugin

let kit = BhapticsKit()

Task {
    let result = await kit.initialize(appId: "your_app_id", apiKey: "your_api_key", defaultSetting: "")
    print("Initialization result: \(result)")

    // Example: Play a haptic event
    let requestId = kit.play(eventId: "your_event_name")
    print("Request ID: \(requestId)")
}

Unter iOS und visionOS lädt initialize die haptischen Events Ihrer haptischen App vom Server herunter. Unter macOS verbindet es sich mit dem bHaptics Player; starten Sie den bHaptics Player, bevor Sie initialize aufrufen.

Geräte verbinden

hinweis

Dieser Schritt gilt nur für iOS und visionOS. Koppeln Sie die Geräte unter macOS im bHaptics Player.

Das SDK findet bHaptics-Geräte in der Nähe über Bluetooth LE. Sobald Sie ein Gerät gekoppelt haben, merkt sich das SDK dieses und verbindet es automatisch erneut, wenn es bei einem späteren Scan gefunden wird.

1. Warten Sie, bis Bluetooth bereit ist, und rufen Sie dann scan() auf.
2. Zeigen Sie dem Benutzer die gefundenen Geräte an und rufen Sie pair(device:) für das vom Benutzer ausgewählte Gerät auf.
3. Rufen Sie stopScan() auf, wenn Sie fertig sind.

Implementieren Sie BhapticsKitDelegate, um benachrichtigt zu werden, wenn Bluetooth bereit ist und sich die Geräteliste ändert.

import BhapticsPlugin

final class HapticManager: BhapticsKitDelegate {
    private var kit: BhapticsKit!
    private(set) var devices: [BhapticsDevice] = []

    init() {
        kit = BhapticsKit(delegate: self)
    }

    func pair(_ device: BhapticsDevice) {
        kit.pair(device: device)
    }

    // Bluetooth is ready. Start scanning.
    func bHapticsKit(_ kit: BhapticsKit, bleStateChange state: Bool) {
        if state {
            kit.scan()
        }
    }

    // Found, paired, connected, or disconnected devices.
    func bHapticsKit(_ kit: BhapticsKit, deviceStateUpdated devices: [BhapticsDevice]) {
        self.devices = devices
    }

    func bHapticsKit(_ kit: BhapticsKit, didConnect device: BhapticsDevice) {
        print("Connected: \(device.name)")
    }

    func bHapticsKit(_ kit: BhapticsKit, didDisconnect device: BhapticsDevice) {
        print("Disconnected: \(device.name)")
    }
}

tipp

Bluetooth funktioniert nicht im iOS Simulator und im visionOS Simulator. Verwenden Sie ein echtes Gerät, um Haptikgeräte zu testen.

Über die Position

Funktionen, die Haptik ohne Events abspielen, erwarten position als Int. Der Wert wird mit den anderen bHaptics SDKs geteilt. Verwenden Sie BhapticsPosition.index, um ihn zu erhalten.

BhapticsPosition	index	Gerät	Anzahl Motoren
.Vest	0	TactSuit Pro	32
.ForearmL	1	TactSleeve(Left)	3
.ForearmR	2	TactSleeve(Right)	3
.Head	3	TactVisor	4
.HandL	4	Tactosy for Hands(Left)	3
.HandR	5	Tactosy for Hands(Right)	3
.FootL	6	Tactosy for Feet(Left)	3
.FootR	7	Tactosy for Feet(Right)	3
.GloveL	8	TactGlove(Left)	8
.GloveR	9	TactGlove(Right)	8

let motorsCount = 32  // TactSuit Pro has 32 motors
let strength = 50     // 50% strength
let duration = 400    // 400 milliseconds

kit.playDot(position: BhapticsPosition.Vest.index, durationMillis: duration, arr: [Int](repeating: strength, count: motorsCount))

Weiterführende Lektüre

Sie sind nun bereit, die haptische Funktion von bHaptics zu nutzen! Besuchen Sie unsere Swift-Referenz, um Haptik in Ihrem Projekt abzuspielen, oder sehen Sie sich den vollständigen Beispielcode unten an.

Wenn Sie Probleme bei der Verwendung dieser Bibliothek haben, lesen Sie die Fehlerbehebung.

Vollständiger Beispielcode

Das folgende Beispiel ist eine SwiftUI-App, die das SDK initialisiert, Geräte in der Nähe zum Koppeln auflistet und Haptik abspielt.

Das Beispiel verwendet SwiftUI .task und Section und erfordert daher iOS 15 / macOS 12 oder neuer; das SDK selbst unterstützt iOS 13 und neuer.

ContentView.swift

import SwiftUI
import BhapticsPlugin

final class HapticViewModel: ObservableObject, BhapticsKitDelegate {
    // Replace with your App ID and API Key from the bHaptics Developer Portal.
    private let appId = "your_app_id"
    private let apiKey = "your_api_key"

    private var kit: BhapticsKit!

    @Published var status = "Not initialized"
    @Published var devices: [BhapticsDevice] = []
    @Published var events: [String] = []

    init() {
        kit = BhapticsKit(delegate: self)
        devices = kit.getDevices()
    }

    // 1. Initialize
    @MainActor
    func initialize() async {
        status = "Initializing..."
        let result = await kit.initialize(appId: appId, apiKey: apiKey, defaultSetting: "")
        status = result ? "Initialized" : "Initialization failed"
        events = kit.getEventList().sorted()
        devices = kit.getDevices()
    }

    // 2. Pair devices
    func togglePair(_ device: BhapticsDevice) {
        if device.paired {
            kit.unpair(device: device)
        } else {
            kit.pair(device: device)
        }
    }

    // 3. Play haptics
    func play(_ event: String) {
        _ = kit.play(eventId: event)
    }

    func playDot() {
        // First 16 of the TactSuit Pro's 32 motors.
        let motors = [Int](repeating: 50, count: 16) + [Int](repeating: 0, count: 16)
        kit.playDot(position: BhapticsPosition.Vest.index, durationMillis: 1000, arr: motors)
    }

    func stopAll() {
        kit.stopAll()
    }

    // BhapticsKitDelegate
    func bHapticsKit(_ kit: BhapticsKit, bleStateChange state: Bool) {
        if state { kit.scan() }
    }

    func bHapticsKit(_ kit: BhapticsKit, deviceStateUpdated devices: [BhapticsDevice]) {
        self.devices = devices
    }

    func bHapticsKit(_ kit: BhapticsKit, didConnect device: BhapticsDevice) {
        devices = kit.getDevices()
    }

    func bHapticsKit(_ kit: BhapticsKit, didDisconnect device: BhapticsDevice) {
        devices = kit.getDevices()
    }
}

struct ContentView: View {
    @StateObject private var viewModel = HapticViewModel()

    var body: some View {
        List {
            Section("Status") {
                Text(viewModel.status)
            }
            Section("Devices") {
                ForEach(viewModel.devices) { device in
                    Button {
                        viewModel.togglePair(device)
                    } label: {
                        HStack {
                            Text(device.name)
                            Spacer()
                            Text(device.connected ? "Connected" : device.paired ? "Paired" : "Tap to pair")
                        }
                    }
                }
            }
            Section("Events") {
                ForEach(viewModel.events, id: \.self) { event in
                    Button(event) { viewModel.play(event) }
                }
            }
            Section {
                Button("Play dot") { viewModel.playDot() }
                Button("Stop all") { viewModel.stopAll() }
            }
        }
        .task { await viewModel.initialize() }
    }
}

Wenn Sie weitere Beispiele erkunden möchten, sehen Sie sich die Beispiel-App in unserem offiziellen GitHub-Repository an.