디바이스 (`device`)

🚀 추가된 버전 : v1.0.0 v1.0.0 v1.0.0
🔔 최신화 일자: 2025-10-22

개요

device 네임스페이스는 디바이스의 주요 정보 및 상태를 조회하는 기능을 제공합니다.

디바이스의 모델명, OS 버전, 네트워크 연결 상태, 배터리 정보, 언어 정보 등을 확인할 수 있으며,
현재 디바이스가 Android인지 iOS인지 판별할 수도 있습니다.

타입 정의

`DeviceType`

since : v1.0.0

디바이스 유형을 나타내는 열거형(enum)입니다.

export declare const DEVICE_TYPES = {
  ANDROID: 'Android',
  IOS: 'iOS',
  UNKNOWN: 'Unknown',
} as const;

export declare type DeviceType =
  (typeof DEVICE_TYPES)[keyof typeof DEVICE_TYPES];

값	설명
`Android`	안드로이드 디바이스
`iOS`	iOS 디바이스
`Unknown`	알 수 없는 디바이스 또는 PC

`NetworkConnectionType`

since : v1.3.0

네트워크 연결 유형을 나타내는 열거형(enum)입니다.

export declare const NETWORK_CONNECTION_TYPES = {
  WIFI: 'Wi-Fi',
  CELLULAR: 'Cellular',
  ETHERNET: 'Ethernet',
  UNKNOWN: 'No Internet Connection',
} as const;

export declare type NetworkConnectionType =
  (typeof NETWORK_CONNECTION_TYPES)[keyof typeof NETWORK_CONNECTION_TYPES];

값	설명
`Wi-Fi`	Wi-Fi 네트워크
`Cellular`	셀룰러(모바일) 네트워크
`Ethernet`	유선 네트워크(Ethernet)
`No Internet Connection`	인터넷 연결이 끊어짐 또는 알 수 없음

`SafeAreaInsets`

since : v1.8.0

디바이스의 Safe Area Insets 정보를 나타내는 타입입니다.

export declare type SafeAreaInsets = {
  top: number;
  bottom: number;
  left: number;
  right: number;
};

필드	타입	설명
`top`	`number`	상단 여백 (pt)
`bottom`	`number`	하단 여백 (pt)
`left`	`number`	좌측 여백 (pt)
`right`	`number`	우측 여백 (pt)

`GetSafeAreaInsetsResult`

since : v1.8.0

Safe Area Insets 조회 결과를 나타내는 타입입니다.

export declare type GetSafeAreaInsetsSuccessResult = {
  isError: false;
} & SafeAreaInsets;

export declare type GetSafeAreaInsetsErrorResult = {
  isError: true;
  errorMessage: string;
};

export declare type GetSafeAreaInsetsResult =
  | GetSafeAreaInsetsSuccessResult
  | GetSafeAreaInsetsErrorResult;

성공 시 반환 값

필드	타입	설명
`isError`	`false`	오류 발생 여부 (성공 시 false)
`top`	`number`	상단 여백 (pt)
`bottom`	`number`	하단 여백 (pt)
`left`	`number`	좌측 여백 (pt)
`right`	`number`	우측 여백 (pt)

실패 시 반환 값

필드	타입	설명
`isError`	`true`	오류 발생 여부 (실패 시 true)
`errorMessage`	`string`	오류 메시지

메서드 목록

메서드	설명	추가된 버전
`getCurrentLanguage(callback)`	디바이스의 현재 언어 코드를 반환합니다.	v1.4.0
`getBatteryLevel(callback)`	디바이스의 배터리 상태를 반환합니다.	v1.3.0
`getDeviceModel()`	디바이스의 모델명을 반환합니다.	v1.3.0
`getDeviceOS()`	디바이스의 OS 유형과 버전을 반환합니다.	v1.3.0
`getNetworkStatus(callback)`	네트워크 연결 상태를 반환합니다.	v1.3.0
`getSafeAreaInsets()`	디바이스의 안전 영역 크기를 반환합니다.	v1.8.0
`getType()`	현재 디바이스의 유형을 반환합니다.	v1.0.0
`isAndroid()`	현재 디바이스가 Android인지 확인합니다.	v1.0.0
`isIOS()`	현재 디바이스가 iOS인지 확인합니다.	v1.0.0

메서드 상세

`getCurrentLanguage(callback: (language: string) => void): void`

since : v1.4.0

설명

디바이스의 현재 언어 코드 를 BCP 47 규격 (en-US, ko-KR, ja-JP 등)으로 반환합니다.
콜백 함수로 언어 코드 값이 전달됩니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(language: string) => void`	✅	언어 코드 반환 함수

반환 값

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

사용 예제

// 디바이스의 현재 언어 코드를 불러옵니다.
Nachocode.device.getCurrentLanguage(language => {
  const message = `현재 디바이스 언어: ${language}`;
  alert(message); // ex. 'ko-KR'
});

`getBatteryLevel(callback: (status: { batteryLevel: number, isCharging: boolean }) => void): void`

since : v1.3.0

설명

디바이스의 배터리 잔량 및 충전 상태를 조회합니다.
콜백 함수로 batteryLevel(배터리 잔량)과 isCharging(충전 여부)을 전달합니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(status: { batteryLevel: number, isCharging: boolean }) => void`	✅	배터리 상태 정보를 전달하는 콜백 함수

batterLevel: number : 배터리의 현재 충전 비율 (0 ~ 100)
isCharging: boolean : 디바이스가 충전 중인지 여부 (true/false)

반환 값

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

사용 예제

// 디바이스의 배터리 상태를 불러옵니다.
Nachocode.device.getBatteryLevel(status => {
  const message =
    `충전 여부: ${status.isCharging ? '충전 중' : '충전 중 아님'}\n` +
    `배터리 잔량: ${status.batteryLevel ?? '알 수 없음'}`;

  alert(message);
});

`getDeviceModel(): string`

since : v1.3.0

설명

현재 디바이스의 모델명을 반환합니다.
nachocode에서는 자주 사용되는 디바이스 모델명을 JSON 형태로 제공합니다.

자주 사용되는 디바이스 모델명 리스트

➡️ Android 삼성 기기 모델 리스트
➡️ iOS 기기 모델 리스트

지원되는 전체 모델 확인

➡️ 구글 공식 문서에서 Android에서 지원되는 전체 모델 목록을 확인할 수 있습니다.

반환 값

타입	설명
`string`	디바이스 모델명을 반환합니다.

사용 예제

// 디바이스의 모델명을 불러옵니다.
const deviceModel = Nachocode.device.getDeviceModel();
console.log(`디바이스 모델명: ${deviceModel}`); // ex. 'SM-S928N'

`getDeviceOS(): { os: DeviceType, version: string }`

since : v1.3.0

설명

디바이스의 운영체제(OS) (Android/iOS) 유형 및 버전 정보를 포함한 객체를 반환합니다.

반환 값

타입	설명
`{ os: DeviceType, version: string }`	OS 유형 및 버전을 포함한 객체

사용 예제

// 디바이스의 OS 정보를 불러옵니다.
const deviceOS = Nachocode.device.getDeviceOS();
console.log(`OS: ${deviceOS.os}, 버전: ${deviceOS.version}`); // ex. { os: 'Android', version: '34(14)' }

`getNetworkStatus(callback: (status: { isConnected: boolean, connectionType: NetworkConnectionType }) => void): void`

since : v1.3.0

설명

현재 디바이스의 네트워크 연결 상태 및 연결 유형(Wi-Fi, 셀룰러 등) 을 콜백 함수에 전달합니다.

매개변수

이름	타입	필수 여부	설명
`callback`	`(status: { isConnected: boolean, connectionType: NetworkConnectionType }) => void`	✅	네트워크 상태 정보를 전달하는 콜백 함수

isConnected: 네트워크 연결 여부 (true/false).
connectionType: 연결 유형 (Wi-Fi, Cellular, Ethernet 등).

반환 값

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

사용 예제

Nachocode.device.getNetworkStatus(status => {
  const connectionInfo = `네트워크 상태: ${status.isConnected ? '연결됨' : '연결되지 않음'}\n연결 유형: ${status.connectionType}`;
  alert(connectionInfo);
});

`getSafeAreaInsets(): Promise<GetSafeAreaInsetsResult>`

since : v1.8.0

설명

디바이스의 Safe Area Insets 정보를 비동기적으로 조회합니다.

Safe Area는 디바이스의 노치, 홈 인디케이터 등으로 인해 가려지지 않는 안전한 영역을 나타냅니다. 이 정보를 활용하여 UI 요소가 가려지지 않도록 레이아웃을 조정할 수 있습니다.

반환되는 값은 포인트(pt) 단위로 제공되며, CSS padding 속성에 바로 적용할 수 있습니다.

iOS 전용 기능

현재 이 기능은 iPhone X 이상의 iOS 기기에서만 지원됩니다.

지원 플랫폼

플랫폼	지원 여부	비고
	❌	지원하지 않음
	✅	iPhone X 이상
	❌	지원하지 않음

반환 값

타입	설명
`Promise<GetSafeAreaInsetsResult>`	Safe Area Insets 조회 결과

사용 예제

기본 사용법

// Safe Area Insets 조회
const safeAreaInsets = await Nachocode.device.getSafeAreaInsets();

if (!safeAreaInsets.isError) {
  console.log(`Top: ${safeAreaInsets.top}pt`);
  console.log(`Bottom: ${safeAreaInsets.bottom}pt`);
  console.log(`Left: ${safeAreaInsets.left}pt`);
  console.log(`Right: ${safeAreaInsets.right}pt`);
} else {
  console.error(`Safe Area Insets 조회 실패: ${safeAreaInsets.errorMessage}`);
}

CSS 변수로 설정

// Safe Area Insets 정보를 CSS 변수로 설정하여 레이아웃에 활용
async function applySafeAreaInsets() {
  const safeAreaInsets = await Nachocode.device.getSafeAreaInsets();

  if (!safeAreaInsets.isError) {
    const root = document.documentElement;
    root.style.setProperty('--safe-area-inset-top', `${safeAreaInsets.top}pt`);
    root.style.setProperty(
      '--safe-area-inset-bottom',
      `${safeAreaInsets.bottom}pt`
    );
    root.style.setProperty(
      '--safe-area-inset-left',
      `${safeAreaInsets.left}pt`
    );
    root.style.setProperty(
      '--safe-area-inset-right',
      `${safeAreaInsets.right}pt`
    );
  }
}

/* CSS에서 사용 */
.header {
  padding-top: var(--safe-area-inset-top);
}

.footer {
  padding-bottom: var(--safe-area-inset-bottom);
}

.bottom-nav {
  padding-bottom: var(--safe-area-inset-bottom);
}

레이아웃 동적 조정

// Safe Area Insets를 고려한 레이아웃 동적 조정
async function adjustLayoutForSafeAreaInsets() {
  const safeAreaInsets = await Nachocode.device.getSafeAreaInsets();

  if (!safeAreaInsets.isError) {
    // 헤더 영역에 상단 Safe Area Insets 적용
    const header = document.querySelector('.header');
    header.style.paddingTop = `${safeAreaInsets.top}pt`;

    // 하단 네비게이션에 하단 Safe Area Insets 적용
    const bottomNav = document.querySelector('.bottom-nav');
    bottomNav.style.paddingBottom = `${safeAreaInsets.bottom}pt`;

    // 전체 컨테이너에 좌우 Safe Area Insets 적용
    const container = document.querySelector('.container');
    container.style.paddingLeft = `${safeAreaInsets.left}pt`;
    container.style.paddingRight = `${safeAreaInsets.right}pt`;
  }
}

CSS에 적용하기

Safe Area Insets 값은 포인트(pt) 단위로 제공되고, 별도의 변환 없이 CSS padding 속성에 포인트(pt) 단위로 바로 적용할 수 있습니다.

`getType(): DeviceType`

since : v1.0.0

설명

현재 디바이스의 유형(Android, iOS, Unknown) 을 탐지 및 반환합니다.

반환 값

타입	설명
`DeviceType`	디바이스 유형을 반환합니다.

사용 예제

// 유저 디바이스 유형을 확인합니다.
const deviceType = Nachocode.device.getType();
console.log(`디바이스 유형: ${deviceType}`); // 'Android' | 'iOS' | 'Unknown'

// 유저 디바이스 별로 로직을 다르게 처리하는 예시입니다.
switch (deviceType) {
  case 'Android': // Android 디바이스를 의미합니다.
    // Android 디바이스에서만 동작할 로직을 작성합니다.
    break;
  case 'iOS': // iPad, iPhone 등 iOS 디바이스를 의미합니다.
    // iOS 디바이스에서만 동작할 로직을 작성합니다.
    break;
  case 'Unknown': // PC 및 기타 장치를 의미합니다.
  default:
    // 모바일이 아닌 PC 및 기타 환경에서 동작할 로직을 작성합니다.
    break;
}

`isAndroid(): boolean`

since : v1.0.0

설명

현재 디바이스가 Android인지 여부를 반환합니다.

반환 값

타입	설명
`boolean`	Android 여부 반환 (`true` / `false`)

사용 예제

if (Nachocode.device.isAndroid()) {
  console.log('현재 디바이스는 Android입니다.');
  // Android 디바이스에서만 동작할 로직을 작성합니다.
}

`isIOS(): boolean`

since : v1.0.0

설명

현재 디바이스가 iOS인지 여부를 반환합니다.

반환 값

타입	설명
`boolean`	iOS 여부 반환 (`true` / `false`)

사용 예제

if (Nachocode.device.isIOS()) {
  console.log('현재 디바이스는 iOS입니다.');
  // iOS 디바이스에서만 동작할 로직을 작성합니다.
}

개요​

타입 정의​

DeviceType​

NetworkConnectionType​

SafeAreaInsets​

GetSafeAreaInsetsResult​

성공 시 반환 값​

실패 시 반환 값​

메서드 목록​

메서드 상세​

getCurrentLanguage(callback: (language: string) => void): void​

설명​

매개변수​

반환 값​

사용 예제​

getBatteryLevel(callback: (status: { batteryLevel: number, isCharging: boolean }) => void): void​

설명​

매개변수​

반환 값​

사용 예제​

getDeviceModel(): string​

설명​

반환 값​

사용 예제​

getDeviceOS(): { os: DeviceType, version: string }​

설명​

반환 값​

사용 예제​

getNetworkStatus(callback: (status: { isConnected: boolean, connectionType: NetworkConnectionType }) => void): void​

설명​

매개변수​

반환 값​

사용 예제​

getSafeAreaInsets(): Promise<GetSafeAreaInsetsResult>​

설명​

지원 플랫폼​

반환 값​

사용 예제​

기본 사용법​

CSS 변수로 설정​

레이아웃 동적 조정​

getType(): DeviceType​

설명​

반환 값​

사용 예제​

isAndroid(): boolean​

설명​

반환 값​

사용 예제​

isIOS(): boolean​

설명​

반환 값​

사용 예제​

개요

타입 정의

`DeviceType`

`NetworkConnectionType`

`SafeAreaInsets`

`GetSafeAreaInsetsResult`

성공 시 반환 값

실패 시 반환 값

메서드 목록

메서드 상세

`getCurrentLanguage(callback: (language: string) => void): void`

설명

매개변수

반환 값

사용 예제

`getBatteryLevel(callback: (status: { batteryLevel: number, isCharging: boolean }) => void): void`

설명

매개변수

반환 값

사용 예제

`getDeviceModel(): string`

설명

반환 값

사용 예제

`getDeviceOS(): { os: DeviceType, version: string }`

설명

반환 값

사용 예제

`getNetworkStatus(callback: (status: { isConnected: boolean, connectionType: NetworkConnectionType }) => void): void`

설명

매개변수

반환 값

사용 예제

`getSafeAreaInsets(): Promise<GetSafeAreaInsetsResult>`

설명

지원 플랫폼

반환 값

사용 예제

기본 사용법

CSS 변수로 설정

레이아웃 동적 조정

`getType(): DeviceType`

설명

반환 값

사용 예제

`isAndroid(): boolean`

설명

반환 값

사용 예제

`isIOS(): boolean`

설명

반환 값

사용 예제