진동 (`vibration`)

🚀 추가된 버전 : v1.1.0 v1.1.0 v1.1.0
🔔 최신화 일자: 2026-03-25

개요

vibration 네임스페이스는 디바이스 진동 및 햅틱 피드백을 제어하는 기능을 제공합니다.

이를 통해 햅틱 피드백(Light, Medium, Heavy 등)과 짧은 진동 패턴을 트리거하거나, 사용자 설정에 따라 진동 기능을 활성화 또는 비활성화할 수 있습니다.

햅틱 기술을 활용하면 사람들의 촉각을 자극하고 물리적 세계에 대한 친숙함을 앱에 접목할 수 있습니다.

정보

SDK Version 1.8.0부터 iOS 전용 햅틱 피드백(Impact, Notification, Selection)과 Android 전용 햅틱 효과가 추가되어 플랫폼별 세밀한 햅틱 제어가 가능합니다.

타입 정의

`HapticsType`

since : v1.1.0
last updated : v1.8.0

기본 햅틱 피드백 유형을 나타내는 열거형(enum)입니다.

export declare const HAPTICS_TYPES = {
  LIGHT: 0,
  MEDIUM: 1,
  HEAVY: 2,
} as const;

export declare type HapticsType =
  (typeof HAPTICS_TYPES)[keyof typeof HAPTICS_TYPES];

값	타입	설명
`0`	`LIGHT`	가벼운 햅틱 피드백
`1`	`MEDIUM`	중간 강도 햅틱 피드백
`2`	`HEAVY`	무거운 햅틱 피드백

`HapticsImpactType`

since : v1.8.0

iOS 전용 Impact 햅틱 피드백 유형을 나타내는 열거형입니다.

export declare const HAPTICS_IMPACT_TYPES = {
  LIGHT: 0, // iOS 10.0+
  MEDIUM: 1, // iOS 10.0+
  HEAVY: 2, // iOS 10.0+
  SOFT: 3, // iOS 13.0+
  RIGID: 4, // iOS 13.0+
} as const;

export declare type HapticsImpactType =
  (typeof HAPTICS_IMPACT_TYPES)[keyof typeof HAPTICS_IMPACT_TYPES];

값	타입	설명
`0`	`LIGHT`	가벼운 Impact 피드백
`1`	`MEDIUM`	중간 강도 Impact 피드백
`2`	`HEAVY`	무거운 Impact 피드백
`3`	`SOFT`	부드러운 Impact 피드백
`4`	`RIGID`	견고하고 날카로운 Impact 피드백

`HapticsNotificationType`

since : v1.8.0

iOS 전용 햅틱 알림(Notification) 피드백 유형을 나타내는 열거형입니다.

export declare const HAPTICS_NOTIFICATION_TYPES = {
  SUCCESS: 0,
  WARNING: 1,
  ERROR: 2,
} as const;

export declare type HapticsNotificationType =
  (typeof HAPTICS_NOTIFICATION_TYPES)[keyof typeof HAPTICS_NOTIFICATION_TYPES];

값	타입	설명
`0`	`SUCCESS`	성공 시 알림 피드백
`1`	`WARNING`	경고 시 알림 피드백
`2`	`ERROR`	오류 또는 실패 시 알림 피드백

`HapticsEffectType`

since : v1.8.0

Android 전용 햅틱 효과(VibrationEffect) 유형을 나타내는 열거형입니다.

export declare const HAPTICS_EFFECT_TYPES = {
  EFFECT_CLICK: 0,
  EFFECT_DOUBLE_CLICK: 1,
  EFFECT_TICK: 2,
  EFFECT_HEAVY_CLICK: 5,
} as const;

export declare type HapticsEffectType =
  (typeof HAPTICS_EFFECT_TYPES)[keyof typeof HAPTICS_EFFECT_TYPES];

값	타입	설명
`0`	`EFFECT_CLICK`	클릭 효과 피드백
`1`	`EFFECT_DOUBLE_CLICK`	더블 클릭 효과 피드백
`2`	`EFFECT_TICK`	틱(Tick) 효과 피드백
`5`	`EFFECT_HEAVY_CLICK`	무거운 클릭 효과 피드백

메서드 목록

설정 관련

메서드	설명	추가된 버전
`setVibration(enable)`	진동 사용 여부를 설정합니다.	v1.1.0
`getVibration(callback)`	진동 사용 여부를 반환합니다.	v1.1.0
`setHaptics(enable)`	햅틱 피드백 사용 여부를 설정합니다.	v1.1.0
`getHaptics(callback)`	햅틱 피드백 사용 여부를 반환합니다.	v1.1.0

진동

메서드	설명	추가된 버전
`vibrate()`	짧은 진동 패턴을 트리거합니다.	v1.1.0

기본 햅틱 피드백

메서드	설명	추가된 버전
`haptics(hapticsType?)`	햅틱 피드백을 트리거합니다.	v1.1.0

iOS 전용 햅틱 피드백

메서드	설명	추가된 버전
`hapticsImpact(hapticsType?)`	iOS 햅틱 Impact 피드백을 트리거합니다.	v1.8.0
`hapticsNotification(hapticsType?)`	iOS 햅틱 Notification 피드백을 트리거합니다.	v1.8.0
`hapticsSelection()`	iOS 햅틱 Selection 피드백을 트리거합니다.	v1.8.0

Android 전용 햅틱 효과

메서드	설명	지원 플랫폼	추가된 버전
`hapticsEffect(hapticsType?)`	Android 햅틱 효과를 트리거합니다.		v1.8.0

메서드 상세

`setVibration(enable)`

since : v1.1.0

타입 정의

function setVibration(enable: boolean): void;

설명

앱 사용자의 진동 사용 여부를 설정합니다.
진동 사용 여부를 false로 설정할 경우 진동 트리거 메서드를 호출하여도 진동이 울리지 않게됩니다.

스토어 정책

스토어 정책에서는 진동 기능을 사용할 경우, 앱 사용자가 직접 진동을 비활성화할 수 있는 옵션을 제공하는 것을 권장하고 있습니다.

지원 플랫폼

setVibration 메서드는 Android, iOS 모든 App 환경을 지원합니다.

플랫폼	지원 여부
	✅
	✅
	❌

매개변수

이름	타입	필수 여부	설명
`enable`	`boolean`	✅	진동 사용 여부 (`true`/`false`)

사용 예제

// 앱이 진동을 사용하도록 설정합니다.
Nachocode.vibration.setVibration(true);

// 사용자의 선택에 따라 진동 사용을 중지합니다.
Nachocode.vibration.setVibration(false);

// 메서드를 호출해도 진동이 울리지 않습니다.
Nachocode.vibration.vibrate(); // 진동 ❌

// ex. 진동 토글 UI 변경 시 호출 될 함수
function onVibrationToggleChange(enable) {
  Nachocode.vibration.setVibration(enable);
}

`getVibration(callback)`

since : v1.1.0

타입 정의

function getVibration(callback: (enable: boolean) => void): void;

설명

현재 앱 사용자의 진동 사용 여부를 반환합니다.
콜백 함수로 true 또는 false 값을 전달받습니다.

지원 플랫폼

getVibration 메서드는 Android, iOS 모든 App 환경을 지원합니다.

플랫폼	지원 여부
	✅
	✅
	❌

매개변수

이름	타입	필수 여부	설명
`callback`	`(enable: boolean) => void`	✅	진동 사용 여부 반환

반환 값

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

사용 예제

// ex. Native Layer에서 진동 사용유무를 받아와 input의 checked 값을 변경합니다.
Nachocode.vibration.getVibration(enable => {
  console.log(`진동 사용 여부: ${enable ? '사용 중' : '비활성화'}`);

  document.querySelector(`input[name="useVibration"]`).checked = enable;
});

`vibrate()`

since : v1.1.0

타입 정의

function vibrate(): void;

설명

짧은 패턴의 진동을 트리거합니다.

지원 플랫폼

vibrate 메서드는 Android, iOS 모든 App 환경을 지원합니다.

플랫폼	지원 여부
	✅
	✅
	❌

반환 값

해당 메서드는 반환 값을 가지지 않습니다.

사용 예제

// DOM 요소의 click 이벤트에 진동 트리거를 바인드 합니다.
document.getElementById('vibrateButton').addEventListener('click', function () {
  // 진동 호출
  Nachocode.vibration.vibrate();
});

`setHaptics(enable)`

since : v1.1.0

타입 정의

function setHaptics(enable: boolean): void;

설명

앱 사용자의 햅틱 피드백 사용 여부를 설정합니다.
햅틱 피드백 사용 여부를 false로 설정할 경우 햅틱 피드백 트리거 메서드를 호출하여도 햅틱 피드백이 발생하지 않게됩니다.

스토어 정책

스토어 정책에서는 진동 기능을 사용할 경우, 앱 사용자가 직접 진동을 비활성화할 수 있는 옵션을 제공하는 것을 권장하고 있습니다.

지원 플랫폼

setHaptics 메서드는 Android, iOS 모든 App 환경을 지원합니다.

플랫폼	지원 여부
	✅
	✅
	❌

매개변수

이름	타입	필수 여부	설명
`enable`	`boolean`	✅	햅틱 피드백 사용 여부 (`true` = 사용, `false` = 사용 안 함)

반환 값

해당 메서드는 반환 값을 가지지 않습니다.

사용 예제

// 앱이 햅틱 피드백을 사용하도록 설정합니다.
Nachocode.vibration.setHaptics(true);

// 사용자의 선택에 따라 햅틱 피드백 사용을 중지합니다.
Nachocode.vibration.setHaptics(false);

// 메서드를 호출해도 햅틱이 발생하지 않습니다.
Nachocode.vibration.haptics(); // 햅틱 피드백 ❌

// ex. 햅틱 피드백 토글 UI 변경 시 호출 될 함수
function onHapticsToggleChange(enable) {
  Nachocode.vibration.setHaptics(enable);
}

`getHaptics(callback)`

since : v1.1.0

타입 정의

function getHaptics(callback: (enable: boolean) => void): void;

설명

현재 앱 사용자의 햅틱 피드백 사용 여부를 반환합니다.
콜백 함수로 true 또는 false 값을 전달받습니다.

지원 플랫폼

getHaptics 메서드는 Android, iOS 모든 App 환경을 지원합니다.

플랫폼	지원 여부
	✅
	✅
	❌

매개변수

이름	타입	필수 여부	설명
`callback`	`(enable: boolean) => void`	✅	햅틱 피드백 사용 여부 반환

반환 값

해당 메서드는 반환 값을 가지지 않으며, 결과는 callback을 통해 비동기적으로 제공됩니다.

사용 예제

// ex. Native Layer에서 햅틱 피드백 사용유무를 받아와 input의 checked 값을 변경합니다.
Nachocode.vibration.getHaptics(enable => {
  console.log(`햅틱 피드백 사용 여부: ${enable ? '사용 중' : '비활성화'}`);

  document.querySelector(`input[name="useHaptics"]`).checked = enable;
});

`haptics(hapticsType?)`

since : v1.1.0
last updated : v1.8.0 - 햅틱 타입 변경

타입 정의

function haptics(hapticsType?: HapticsType): void;

설명

햅틱 피드백을 트리거합니다. LIGHT = 0 | MEDIUM = 1 | HEAVY = 2 중 하나를 선택할 수 있습니다.
기본적으로 LIGHT 피드백을 사용하며, 선택적으로 다른 강도를 지정할 수 있습니다.

지원 플랫폼

haptics 메서드는 Android, iOS 모든 App 환경을 지원합니다.

플랫폼	지원 여부
	✅
	✅
	❌

매개변수

이름	타입	필수 여부	설명
`hapticsType`	`HapticsType`	❌	트리거할 햅틱 피드백 유형 (기본값: `0` - LIGHT)

사용 예제

// 기본 햅틱 피드백 (LIGHT)
// DOM 요소의 touchstart 이벤트에 햅틱 피드백 트리거를 바인드 합니다.
document
  .getElementById('hapticsButton')
  .addEventListener('touchstart', function () {
    // 기본적으로 HapticsType.LIGHT(=0)를 옵션으로 가집니다.
    Nachocode.vibration.haptics();
  });

document
  .getElementById('hapticsButton2')
  .addEventListener('touchstart', function () {
    // 0은 HapticsType.LIGHT를 의미합니다.
    Nachocode.vibration.haptics(0);
  });

// 중간 강도 햅틱 피드백 (MEDIUM)
document
  .getElementById('hapticsButton')
  .addEventListener('touchstart', function () {
    // 1은 HapticsType.MEDIUM을 의미합니다.
    Nachocode.vibration.haptics(1);
  });

// 무거운 햅틱 피드백 (HEAVY)
document
  .getElementById('hapticsButton')
  .addEventListener('touchstart', function () {
    // 2는 HapticsType.HEAVY를 의미합니다.
    Nachocode.vibration.haptics(2);
  });

`hapticsImpact(hapticsType?)`

since : v1.8.0

타입 정의

function hapticsImpact(hapticsType?: HapticsImpactType): void;

설명

iOS 전용 햅틱 Impact 피드백을 트리거합니다.

물리적 Impact를 시뮬레이션하는 피드백으로, 충돌이나 무게감을 표현할 때 사용합니다.
LIGHT = 0 | MEDIUM = 1 | HEAVY = 2 | SOFT = 3 | RIGID = 4 중 하나를 선택할 수 있습니다.

iOS 전용

이 메서드는 iOS에서만 동작합니다. Android에서는 동작하지 않습니다.

지원 플랫폼

플랫폼	지원 여부
	❌
	✅
	❌

매개변수

이름	타입	필수 여부	설명
`hapticsType`	`HapticsImpactType`	❌	트리거할 햅틱 Impact 유형 (기본값: `0` - LIGHT)

반환 값

해당 메서드는 반환 값을 가지지 않습니다.

사용 예제

기본 Impact 피드백 (LIGHT)

// 가벼운 Impact 피드백 (기본값)
// iOS 10.0+ 디바이스에서만 지원됩니다.
document
  .getElementById('lightButton')
  .addEventListener('touchstart', function () {
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsImpact(); // 기본값 LIGHT
    }
  });

강도별 Impact 피드백

// 중간 강도 Impact 피드백
// iOS 10.0+ 디바이스에서만 지원됩니다.
document
  .getElementById('mediumButton')
  .addEventListener('touchstart', function () {
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsImpact(1); // MEDIUM
    }
  });

// 무거운 Impact 피드백
// iOS 10.0+ 디바이스에서만 지원됩니다.
document
  .getElementById('heavyButton')
  .addEventListener('touchstart', function () {
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsImpact(2); // HEAVY
    }
  });

특수 Impact 피드백

// 부드러운 Impact 피드백
// iOS 13.0+ 디바이스에서만 지원됩니다.
document
  .getElementById('softButton')
  .addEventListener('touchstart', function () {
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsImpact(3); // SOFT
    }
  });

// 견고한 Impact 피드백
// iOS 13.0+ 디바이스에서만 지원됩니다.
document
  .getElementById('rigidButton')
  .addEventListener('touchstart', function () {
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsImpact(4); // RIGID
    }
  });

`hapticsNotification(hapticsType?)`

since : v1.8.0

타입 정의

function hapticsNotification(hapticsType?: HapticsNotificationType): void;

설명

iOS 전용 햅틱 Notification 피드백을 트리거합니다.

작업의 성공, 경고, 실패를 알리는 피드백으로, 사용자에게 결과를 직관적으로 전달할 때 사용합니다.
SUCCESS = 0 | WARNING = 1 | ERROR = 2 중 하나를 선택할 수 있습니다.

iOS 전용

이 메서드는 iOS에서만 동작합니다. Android에서는 동작하지 않습니다.

지원 플랫폼

플랫폼	지원 여부
	❌
	✅
	❌

매개변수

이름	타입	필수 여부	설명
`hapticsType`	`HapticsNotificationType`	❌	트리거할 햅틱 Notification 유형 (기본값: `0` - SUCCESS)

반환 값

해당 메서드는 반환 값을 가지지 않습니다.

사용 예제

성공 Notification

// 작업 성공 시 Notification 피드백
async function saveData() {
  try {
    await uploadData();

    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsNotification(0); // SUCCESS
    }

    alert('저장되었습니다!');
  } catch (error) {
    console.error(error);
  }
}

경고 Notification

// 경고 상황에서 Notification 피드백
function validateForm() {
  const email = document.getElementById('email').value;

  if (!email.includes('@')) {
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsNotification(1); // WARNING
    }

    alert('올바른 이메일 형식이 아닙니다.');
    return false;
  }

  return true;
}

오류 Notification

// 작업 실패 시 Notification 피드백
async function processPayment() {
  try {
    await submitPayment();
  } catch (error) {
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsNotification(2); // ERROR
    }

    alert('결제에 실패했습니다.');
  }
}

`hapticsSelection()`

since : v1.8.0

타입 정의

function hapticsSelection(): void;

설명

iOS 전용 햅틱 Selection 피드백을 트리거합니다.

선택 항목이 변경될 때 사용하는 가벼운 피드백으로, 피커(Picker), 스크롤 선택, 토글 스위치 등에 사용합니다.

iOS 전용

이 메서드는 iOS에서만 동작합니다. Android에서는 동작하지 않습니다.

지원 플랫폼

플랫폼	지원 여부
	❌
	✅
	❌

반환 값

해당 메서드는 반환 값을 가지지 않습니다.

사용 예제

목록 선택 시 피드백

// 목록 항목 선택 시 피드백
document.querySelectorAll('.list-item').forEach(item => {
  item.addEventListener('touchstart', function () {
    // 선택된 항목 표시
    document
      .querySelectorAll('.list-item')
      .forEach(i => i.classList.remove('selected'));
    this.classList.add('selected');

    // Selection 피드백
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsSelection();
    }
  });
});

토글 스위치 변경 시 피드백

// 토글 스위치 변경 시 피드백
document
  .getElementById('toggleSwitch')
  .addEventListener('change', function (e) {
    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsSelection();
    }

    console.log('Toggle state:', e.target.checked);
  });

스크롤 선택 시 피드백

// 스크롤 가능한 피커에서 항목 변경 시 피드백
let currentIndex = 0;

function onScrollChange(newIndex) {
  if (newIndex !== currentIndex) {
    currentIndex = newIndex;

    if (Nachocode.device.isIOS()) {
      Nachocode.vibration.hapticsSelection();
    }
  }
}

`hapticsEffect(hapticsType?)`

since : v1.8.0

타입 정의

function hapticsEffect(hapticsType?: HapticsEffectType): void;

설명

Android 전용 햅틱 효과(VibrationEffect)를 트리거합니다.

Android의 시스템 정의 햅틱 효과를 사용하여 클릭, 더블 클릭, 틱 등의 피드백을 제공합니다.
EFFECT_CLICK = 0 | EFFECT_DOUBLE_CLICK = 1 | EFFECT_TICK = 2 | EFFECT_HEAVY_CLICK = 5 중 하나를 선택할 수 있습니다.

Android 전용

이 메서드는 Android에서만 동작합니다. iOS에서는 동작하지 않습니다.

지원 플랫폼

플랫폼	지원 여부
	✅
	❌
	❌

매개변수

이름	타입	필수 여부	설명
`hapticsType`	`HapticsEffectType`	❌	트리거할 햅틱 효과 유형 (기본값: `0` - EFFECT_CLICK)

반환 값

해당 메서드는 반환 값을 가지지 않습니다.

사용 예제

클릭 효과

// 기본 클릭 효과 (EFFECT_CLICK)
document
  .getElementById('clickButton')
  .addEventListener('touchstart', function () {
    if (Nachocode.device.isAndroid()) {
      Nachocode.vibration.hapticsEffect(); // 기본값 EFFECT_CLICK
    }
  });

// 또는 명시적으로 지정
document
  .getElementById('clickButton2')
  .addEventListener('touchstart', function () {
    if (Nachocode.device.isAndroid()) {
      Nachocode.vibration.hapticsEffect(0); // EFFECT_CLICK
    }
  });

틱 효과

// 틱 효과 - 작은 단위 변경 시
document
  .getElementById('incrementButton')
  .addEventListener('click', function () {
    let count = parseInt(document.getElementById('counter').textContent);
    count++;
    document.getElementById('counter').textContent = count;

    if (Nachocode.device.isAndroid()) {
      Nachocode.vibration.hapticsEffect(2); // EFFECT_TICK
    }
  });

무거운 클릭 효과

// 무거운 클릭 효과 - 중요한 동작 시
document
  .getElementById('confirmButton')
  .addEventListener('touchstart', function () {
    if (Nachocode.device.isAndroid()) {
      Nachocode.vibration.hapticsEffect(5); // EFFECT_HEAVY_CLICK
    }

    // 중요한 작업 수행
    confirmAction();
  });

개요​

타입 정의​

HapticsType​

HapticsImpactType​

HapticsNotificationType​

HapticsEffectType​

메서드 목록​

설정 관련​

진동​

기본 햅틱 피드백​

iOS 전용 햅틱 피드백​

Android 전용 햅틱 효과​

메서드 상세​

setVibration(enable)​

타입 정의​

설명​

지원 플랫폼​

매개변수​

사용 예제​

getVibration(callback)​

타입 정의​

설명​

지원 플랫폼​

매개변수​

반환 값​

사용 예제​

vibrate()​

타입 정의​

설명​

지원 플랫폼​

반환 값​

사용 예제​

setHaptics(enable)​

타입 정의​

설명​

지원 플랫폼​

매개변수​

반환 값​

사용 예제​

getHaptics(callback)​

타입 정의​

설명​

지원 플랫폼​

매개변수​

반환 값​

사용 예제​

haptics(hapticsType?)​

타입 정의​

설명​

지원 플랫폼​

매개변수​

사용 예제​

hapticsImpact(hapticsType?)​

타입 정의​

설명​

지원 플랫폼​

매개변수​

반환 값​

사용 예제​

기본 Impact 피드백 (LIGHT)​

강도별 Impact 피드백​

특수 Impact 피드백​

hapticsNotification(hapticsType?)​

타입 정의​

설명​

지원 플랫폼​

매개변수​

반환 값​

사용 예제​

성공 Notification​

경고 Notification​

오류 Notification​

hapticsSelection()​

타입 정의​

설명​

지원 플랫폼​

반환 값​

사용 예제​

목록 선택 시 피드백​

토글 스위치 변경 시 피드백​

개요

타입 정의

`HapticsType`

`HapticsImpactType`

`HapticsNotificationType`

`HapticsEffectType`

메서드 목록

설정 관련

진동

기본 햅틱 피드백

iOS 전용 햅틱 피드백

Android 전용 햅틱 효과

메서드 상세

`setVibration(enable)`

타입 정의

설명

지원 플랫폼

매개변수

사용 예제

`getVibration(callback)`

타입 정의

설명

지원 플랫폼

매개변수

반환 값

사용 예제

`vibrate()`

타입 정의

설명

지원 플랫폼

반환 값

사용 예제

`setHaptics(enable)`

타입 정의

설명

지원 플랫폼

매개변수

반환 값

사용 예제

`getHaptics(callback)`

타입 정의

설명

지원 플랫폼

매개변수

반환 값

사용 예제

`haptics(hapticsType?)`

타입 정의

설명

지원 플랫폼

매개변수

사용 예제

`hapticsImpact(hapticsType?)`

타입 정의

설명

지원 플랫폼

매개변수

반환 값

사용 예제

기본 Impact 피드백 (LIGHT)

강도별 Impact 피드백

특수 Impact 피드백

`hapticsNotification(hapticsType?)`

타입 정의

설명

지원 플랫폼

매개변수

반환 값

사용 예제

성공 Notification

경고 Notification

오류 Notification

`hapticsSelection()`

타입 정의

설명

지원 플랫폼

반환 값

사용 예제

목록 선택 시 피드백

토글 스위치 변경 시 피드백