Guide pour Swift

Grâce à notre SDK Swift, vous pouvez intégrer les haptiques dans vos apps iOS, visionOS et macOS.

1. Installer le package
2. Configurer l'environnement haptique
3. Connecter les appareils

---

Prérequis

• Xcode 16 ou version ultérieure
• OS : iOS 13.0+, visionOS 2.0+, macOS 10.15+
• Connexion Internet, pour télécharger les événements haptiques lors de l'initialisation
• macOS uniquement : bHaptics Player installé et en cours d'exécution
• Application haptique déployée correspondant à votre projet
  • App ID et API Key de l'application haptique

Comment les appareils sont connectés

• iOS / visionOS : Le SDK se connecte directement aux appareils haptiques via Bluetooth LE. Aucune application compagnon n'est requise.
• macOS : Le SDK se connecte à bHaptics Player, et bHaptics Player gère les appareils haptiques. Appairez vos appareils dans bHaptics Player.

Vous utilisez la même API sur toutes les plateformes.

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

Installez le bHaptics Swift SDK avec Swift Package Manager.

1. Dans Xcode, sélectionnez File > Add Package Dependencies....
2. Saisissez l'URL du package : https://github.com/bhaptics/bhaptics-ios
3. Définissez Dependency Rule sur Up to Next Major Version à partir de 1.0.1.
4. Ajoutez la bibliothèque Bhaptics à la cible de votre app.

Si vous gérez les dépendances dans Package.swift, ajoutez le package comme ci-dessous :

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")]
    )
]

Importer les packages

import BhapticsPlugin

Autorisation Bluetooth

iOS / visionOS : Ajoutez NSBluetoothAlwaysUsageDescription (Privacy - Bluetooth Always Usage Description) aux paramètres Info de la cible de votre app, avec un message expliquant pourquoi votre app utilise le Bluetooth. La demande d'autorisation s'affiche lorsque vous créez BhapticsKit. Sans cette clé, l'app plante lorsque le SDK accède au Bluetooth.

macOS : Si App Sandbox est activé, accédez à Signing & Capabilities > App Sandbox, puis cochez Outgoing Connections (Client) afin que le SDK puisse se connecter à bHaptics Player.

Configurer l'environnement haptique

Avant d'utiliser des fonctions liées aux haptiques, vous devez lier l'application haptique à votre projet et initialiser l'environnement haptique.

Pour ce faire, vous avez besoin de l'App ID et de l'API Key de votre application haptique. Vous pouvez les obtenir depuis le bHaptics Developer Portal.

Initialiser

• Remplacez "your_app_id" et "your_api_key" par votre App ID et votre API Key.
• Créez une seule instance de BhapticsKit et conservez-la pendant toute la durée de vie de votre app.

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)")
}

Sur iOS et visionOS, initialize télécharge depuis le serveur les événements haptiques de votre application haptique. Sur macOS, elle se connecte à bHaptics Player ; lancez bHaptics Player avant d'appeler initialize.

Connecter les appareils

remarque

Cette étape concerne uniquement iOS et visionOS. Sur macOS, appairez les appareils dans bHaptics Player.

Le SDK détecte les appareils bHaptics à proximité via Bluetooth LE. Une fois un appareil appairé, le SDK le mémorise et le reconnecte automatiquement lorsqu'il est détecté lors d'un scan ultérieur.

1. Attendez que le Bluetooth soit prêt, puis appelez scan().
2. Affichez les appareils détectés à l'utilisateur, et appelez pair(device:) sur celui qu'il sélectionne.
3. Appelez stopScan() lorsque vous avez terminé.

Implémentez BhapticsKitDelegate pour être notifié lorsque le Bluetooth devient prêt et lorsque la liste des appareils change.

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)")
    }
}

astuce

Le Bluetooth ne fonctionne pas dans iOS Simulator ni dans visionOS Simulator. Utilisez un appareil réel pour tester les appareils haptiques.

À propos de la position

Les fonctions qui lisent des haptiques sans événements prennent position sous forme d'Int. Cette valeur est partagée avec les autres SDK bHaptics. Utilisez BhapticsPosition.index pour l'obtenir.

BhapticsPosition	index	Appareil	Nombre de moteurs
.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))

Pour aller plus loin

Vous êtes maintenant prêt à utiliser la fonctionnalité haptique de bHaptics ! Consultez notre Référence Swift pour jouer des haptiques dans votre projet, ou référez-vous au code d'exemple complet ci-dessous.

Si vous rencontrez des problèmes lors de l'utilisation de cette bibliothèque, consultez le Dépannage.

Code d'exemple complet

L'exemple ci-dessous est une app SwiftUI qui initialise le SDK, liste les appareils à proximité à appairer et lit des haptiques.

L'exemple utilise .task et Section de SwiftUI ; il nécessite donc iOS 15 / macOS 12 ou une version ultérieure (le SDK lui-même prend en charge iOS 13 et les versions ultérieures).

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() }
    }
}

Si vous souhaitez explorer davantage d'exemples, consultez l'app d'exemple dans notre dépôt GitHub officiel.