Unity 가이드

Unity SDK 플러그인을 사용하면 Unity로 제작한 콘텐츠에 햅틱을 구현할 수 있습니다.

1. SDK 플러그인 가져오기
2. 햅틱 앱 연동하기
3. 초기화를 위한 프리팹 추가하기

---

요구 사항

• 개발 환경
  • OS: Windows 10/11 (x64), macOS (Apple Silicon) (현재 베타)
  • Unity 2019.4.0+
  • bHaptics Player 설치
  • 게임에 대응하는 배포된 햅틱 애플리케이션
    • 햅틱 앱의 앱 ID와 API 키
• 실행 환경
  • OS: Windows 10/11 (x64), Meta Horizon OS, PS5

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.

SDK 플러그인 가져오기

Unity Asset Store에서 bHaptics Haptic Plugin을 받아 Unity 프로젝트에 패키지를 가져옵니다.

Unity 패키지를 Unity 프로젝트로 가져오는 방법에 대한 자세한 내용은 공식 Unity 문서를 참고하세요.

햅틱 앱 연동하기

1. 툴바에서 "bHaptics" → "Developer Window"를 선택합니다.
2. Portal에서 발급받은 앱 ID와 API 키를 입력한 후 "LINK" 버튼을 클릭합니다.
   노트

   "Forgot your App ID & API Key?"를 눌러 Portal에 방문하여 해당 정보를 확인할 수 있습니다.

3. 인증에 성공하면 bHaptics Developer Window에 애플리케이션이 표시됩니다.

bHaptics Developer Window에서 앱 살펴보기

여러 탭을 살펴볼 수 있습니다.

• Home: 샘플 가이드와 애플리케이션 정보를 확인합니다.
• Events: bHaptics Developer Portal에서 배포한 최신 이벤트를 살펴보고 재생합니다.
• Documentation: SDK 관련 문서(이 사이트 포함!)를 살펴봅니다.
• Latest Deployed Version: 버전을 확인하거나 새로 고칩니다.
  노트

  Portal의 버전과 에디터의 버전이 일치하는지 확인하고, 일치하지 않으면 새로 고침 아이콘을 누르세요.

• Unlink: 게임과 햅틱 앱의 연결을 해제합니다.

초기화를 위한 프리팹 추가하기

햅틱 환경을 초기화하기 위한 "[bhaptics]"라는 이름의 프리팹이 있습니다. 햅틱 관련 함수를 사용하기 전에 인스턴스화되어야 합니다. 첫 번째 씬에 배치하는 것을 강력히 권장합니다.

1. 첫 번째 씬으로 이동합니다.
2. Project Window에서 "Assets" → "Bhaptics" → "SDK2" → "Prefabs"로 이동합니다.
3. "[bHaptics]" 프리팹을 씬에 추가합니다.

이 프리팹의 컴포넌트는 DontDestroyOnLoad와 함께 일반적인 Unity 싱글톤 패턴을 사용합니다. 첫 번째 씬에만 배치하면 되지만, 중복 인스턴스는 자동으로 제거되므로 여러 곳에 배치해도 괜찮습니다.

Android Manifest 업데이트

Android Target API Level이 30 이상인 경우, 게임에 bHaptics를 연동하려면 AndroidManifest.xml 파일을 업데이트해야 합니다.

노트

프로젝트의 Android Target API Level을 확인하려면 Project Settings → Player → Android settings(Android 아이콘) → Other Settings → Identification → Target API Level로 이동하세요. 자세한 내용은 Unity 매뉴얼을 참고하세요.

1. Android 앱 매니페스트 재정의를 활성화합니다. Project Settings → Player → Android settings(Android 아이콘) → Publishing Settings → Build → Custom Main Manifest로 이동한 후, 비활성화되어 있다면 활성화합니다. 매니페스트 파일의 디렉터리는 아래와 같습니다.
2. 일반적으로 Assets/Plugins/Android/ 디렉터리에 있는 AndroidManifest.xml 파일을 엽니다.
3. 매니페스트 파일에 queries 요소를 추가합니다.

   <queries>
       <package android:name="com.bhaptics.player" />
   </queries>

4. 매니페스트 파일의 권한을 업데이트하고 추가합니다.

   <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
   <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
   <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

과정이 완료되면 매니페스트 파일은 다음과 같은 모습이어야 합니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unity3d.player"
    xmlns:tools="http://schemas.android.com/tools">

    <application>
        <activity android:name="com.unity3d.player.UnityPlayerActivity"
            android:theme="@style/UnityThemeSelector">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
        </activity>
    </application>

    <queries>
        <package android:name="com.bhaptics.player" />
    </queries>

    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
</manifest>

노트

자세한 내용은 다음 자료를 참고하세요.

• Unity에서 Android 앱 매니페스트 재정의하기
• Android 앱 매니페스트 소개

위험

Minify 옵션을 활성화한 경우, Custom Proguard 파일(proguard-user.txt)에 예외를 추가해야 합니다.

더 읽어보기

이제 bHaptics 햅틱 기능을 사용할 준비가 되었습니다! 게임에서 햅틱을 재생하려면 Unity References 페이지를 방문하세요.

노트

지금 바로 햅틱을 느껴보고 싶다면, 플레이테스트할 수 있는 햅틱 이벤트를 살펴볼 수 있는 샘플 씬을 제공합니다. "Assets" → "Bhaptics" → "SDK2" → "Examples" → "Scenes"로 이동하여 "PlayParamSample" 씬을 여세요. 관련 파라미터를 조절하면서 모든 햅틱 이벤트를 재생해 볼 수 있습니다.

문제 해결

• Queries로 인한 빌드 실패
• Android 근처 기기 권한이 기본으로 요청되는 문제

마이그레이션 가이드

• 마이그레이션 가이드 (SDK1 → SDK2)
• 마이그레이션 가이드 (2.0.5 → 최신)