Navigator API 주요 속성과 활용 정리

브라우저의 navigator 객체는 사용자 환경, 권한, 장치, 네트워크 상태 등 다양한 브라우저 기능에 접근할 수 있는 진입점입니다.

이 문서는 navigator에서 자주 확인할 수 있는 속성과, 실무에서 비교적 자주 사용하는 API를 중심으로 정리합니다.

1. navigator 주요 속성 요약

속성	설명	비고
appCodeName	브라우저 코드명입니다.	대부분 Mozilla로 고정되어 의미가 크지 않습니다.
appName	브라우저 이름입니다.	대부분 Netscape로 고정되어 의미가 크지 않습니다.
appVersion	브라우저 버전 문자열입니다.	User-Agent와 유사한 정보를 포함합니다.
bluetooth	Bluetooth 장치 연결을 위한 인터페이스입니다.	브라우저별 지원 여부 차이가 큽니다.
clipboard	클립보드 읽기/쓰기 기능을 제공합니다.	HTTPS 환경과 사용자 제스처가 중요합니다.
connection	네트워크 상태 정보를 제공합니다.	Firefox, Safari에서는 지원되지 않을 수 있습니다.
cookieEnabled	쿠키 사용 가능 여부를 반환합니다.	true 또는 false
credentials	Credential Management API 접근 객체입니다.	로그인, 인증 정보 관리와 관련됩니다.
deviceMemory	기기의 대략적인 메모리 용량을 GB 단위로 제공합니다.	Firefox, Safari에서는 지원되지 않을 수 있습니다.
devicePosture	폴더블 기기의 접힘 상태 정보를 제공합니다.	지원 브라우저가 제한적입니다.
geolocation	사용자의 현재 위치 정보를 가져옵니다.	명시적인 사용자 권한이 필요합니다.
gpu	WebGPU의 시작점입니다.	브라우저별 지원 여부 확인이 필요합니다.
hardwareConcurrency	사용 가능한 논리 CPU 코어 수를 반환합니다.	작업 분산이나 최적화 참고값으로 사용할 수 있습니다.
hid	특수 입력 장치와 연결하기 위한 WebHID API입니다.	Firefox, Safari에서는 지원되지 않을 수 있습니다.
ink	터치펜 입력 지연을 줄이기 위한 API입니다.	지원 브라우저가 제한적입니다.
keyboard	키보드 레이아웃 및 잠금 관련 기능을 제공합니다.	Firefox, Safari에서는 지원되지 않을 수 있습니다.
language	현재 브라우저의 주 언어를 반환합니다.	예: ko-KR
languages	사용자의 선호 언어 목록을 반환합니다.	예: ['ko-KR', 'ko', 'en-US', 'en']
locks	동일 출처 탭 간 동시성 제어 기능을 제공합니다.	Web Locks API
mediaDevices	카메라, 마이크, 화면 공유 장치에 접근합니다.	사용자 권한이 필요합니다.
onLine	브라우저의 온라인 상태 여부를 반환합니다.	정확한 서버 연결 보장은 아닙니다.
permissions	권한 허용 상태를 조회합니다.	Permissions API
platform	사용자 플랫폼 정보를 반환합니다.	예: MacIntel, Win32, iPhone
sendBeacon	페이지 종료 시점에도 데이터를 전송할 수 있게 도와줍니다.	분석 로그 전송 등에 사용됩니다.
serviceWorker	Service Worker 등록과 제어를 담당합니다.	오프라인 캐싱, 백그라운드 처리 등에 사용됩니다.
storage	브라우저 저장소 사용량과 남은 용량을 확인합니다.	estimate() 메서드 사용
userAgent	브라우저와 OS 정보를 담은 문자열입니다.	점점 신뢰도가 낮아지고 있습니다.
userAgentData	User-Agent를 대체하기 위한 최신 객체입니다.	Firefox, Safari에서는 지원되지 않을 수 있습니다.
wakeLock	화면 꺼짐을 방지하는 기능을 제공합니다.	사용자 환경에 따라 제한될 수 있습니다.

2. 주로 사용되는 속성

2-1. clipboard

과거에는 document.execCommand('copy')를 사용했지만, 현재는 Promise 기반의 비동기 방식인 Clipboard API가 표준입니다.

주요 메서드

메서드	설명
writeText(text)	클립보드에 텍스트를 씁니다.
readText()	클립보드에 있는 텍스트를 읽어옵니다.
write(data)	이미지, HTML 등 Blob 데이터를 씁니다.
read()	클립보드의 모든 데이터를 읽어옵니다.

텍스트 복사

버튼 클릭 시 특정 텍스트나 JSON 데이터를 복사할 때 사용할 수 있습니다.

const handleCopy = async (targetText: string) => {
  try {
    await navigator.clipboard.writeText(targetText);

    alert('클립보드에 복사되었습니다!');
  } catch (error) {
    console.error('복사 실패:', error);
  }
};

클립보드 데이터 읽기

외부 데이터를 앱 내부로 가져올 때 사용할 수 있습니다.

const handlePaste = async () => {
  try {
    const text = await navigator.clipboard.readText();

    console.log('가져온 내용:', text);
  } catch (error) {
    console.error('읽기 실패:', error);
  }
};

기타 정보

• HTTPS 환경에서만 동작합니다. 단, localhost는 예외적으로 허용됩니다.

• HTTP 환경에서는 navigator.clipboard 자체가 undefined일 수 있습니다.

• 보안을 위해 클릭, 키다운 같은 사용자 이벤트 핸들러 내부에서 호출하는 것이 안전합니다.

• writeText()는 보통 별도 팝업 없이 허용되지만, readText()는 권한 요청이 발생할 수 있습니다.

• 이미지 복사는 navigator.clipboard.write([new ClipboardItem({'image/png': blob})]) 방식으로 처리할 수 있습니다.

2-2. geolocation

geolocation은 사용자의 현재 위치, 즉 위도와 경도를 확인할 수 있는 API입니다. 사생활과 직접 연결되는 정보이므로 반드시 사용자의 명시적인 승인이 필요합니다.

주요 메서드

메서드	설명
getCurrentPosition()	현재 위치를 한 번 가져옵니다.
watchPosition()	위치가 바뀔 때마다 실시간으로 추적합니다.
clearWatch()	watchPosition()으로 시작한 추적을 중단합니다.

일회성 위치 정보 획득

const getXApiLocation = () => {
  const options = {
    enableHighAccuracy: true,
    timeout: 5000,
    maximumAge: 0
  };

  navigator.geolocation.getCurrentPosition(
    (position) => {
      const { latitude, longitude, accuracy } = position.coords;

      console.log(`위도: ${latitude}, 경도: ${longitude}, 오차범위: ${accuracy}m`);
    },
    (error) => {
      switch (error.code) {
        case error.PERMISSION_DENIED:
          console.error('사용자가 위치 정보 승인을 거부했습니다.');
          break;
        case error.POSITION_UNAVAILABLE:
          console.error('위치 정보를 사용할 수 없습니다.');
          break;
        case error.TIMEOUT:
          console.error('요청 시간이 초과되었습니다.');
          break;
      }
    },
    options
  );
};

기타 정보

• 사용자가 위치 권한을 거절했을 때 앱이 멈추지 않도록 반드시 에러 콜백을 작성해야 합니다.

• enableHighAccuracy: true는 GPS를 적극적으로 사용하므로 모바일 기기에서 배터리 소모가 커질 수 있습니다.

• 정확한 좌표가 꼭 필요하지 않다면 false로 두는 편이 효율적입니다.

• 위경도 정보를 수집한다면 개인정보 처리방침에 해당 내용을 명시해야 할 수 있습니다.

2-3. locks

navigator.locks는 여러 탭이 동시에 같은 작업을 하지 못하도록 뮤텍스 형태의 잠금 기능을 제공합니다.

주요 메서드

메서드	설명
request(name, options, callback)	특정 이름의 락을 요청합니다.

사용 예시

return navigator.locks.request(
  'lock입니다',
  { ifAvailable: true },
  async (lock) => {
    if (!lock) {
      return;
    }

    return await this.internalFlush(sendFn);
  }
);

기타 정보

• 콜백이 끝나면 락은 자동으로 해제됩니다. 직접 unlock할 필요가 없습니다.

• 동일 출처에서 잡은 락은 같은 origin의 다른 탭에만 적용됩니다.

• 사용자가 탭을 닫으면 해당 탭이 잡고 있던 락은 브라우저가 회수합니다.

2-4. mediaDevices

mediaDevices는 사용자의 카메라, 마이크, 화면 공유 같은 하드웨어 장치에 접근할 때 사용합니다. 사용자의 승인이 필수이며 비동기 방식으로 동작합니다.

주요 메서드

메서드	설명
getUserMedia()	카메라와 마이크의 실시간 스트림을 가져옵니다.
enumerateDevices()	연결된 카메라, 마이크, 스피커 목록을 가져옵니다.
getDisplayMedia()	화면 공유 스트림을 가져옵니다.

카메라/마이크 스트림 가져오기

const startVideoStreaming = async () => {
  const constraints = {
    video: { width: 1280, height: 720 },
    audio: true
  };

  try {
    const stream = await navigator.mediaDevices.getUserMedia(constraints);

    console.log('STREAM_ACQUIRED: 미디어 장치 연결에 성공했습니다.');

    const videoElement = document.querySelector('video');

    if (videoElement) {
      videoElement.srcObject = stream;
    }
  } catch (error: any) {
    switch (error.name) {
      case 'NotAllowedError':
        console.error('PERMISSION_DENIED: 사용자가 카메라/마이크 권한을 거부했습니다.');
        break;
      case 'NotFoundError':
        console.error('DEVICE_NOT_FOUND: 연결된 카메라나 마이크를 찾을 수 없습니다.');
        break;
      case 'NotReadableError':
        console.error('HARDWARE_ERROR: 장치가 이미 다른 앱에서 사용 중이거나 하드웨어 오류가 발생했습니다.');
        break;
      default:
        console.error('UNKNOWN_ERROR:', error.message);
    }
  }
};

장치 목록 확인

const getDeviceList = async () => {
  const devices = await navigator.mediaDevices.enumerateDevices();

  devices.forEach((device) => {
    console.log(`${device.kind}: ${device.label} (ID: ${device.deviceId})`);
  });
};

기타 정보

• HTTPS 환경에서만 동작합니다. 단, localhost는 예외적으로 허용됩니다.

• 권한을 한 번 거부하면 브라우저 설정에서 직접 풀기 전까지 권한 요청 팝업이 다시 나타나지 않을 수 있습니다.

• 사용자에게 권한 허용 방법을 안내하는 별도 UI가 필요할 수 있습니다.

• 사용이 끝나면 stream.getTracks().forEach(track => track.stop())을 호출해 스트림을 종료해야 합니다.

2-5. onLine

navigator.onLine은 브라우저의 온라인 상태 여부를 확인하는 속성입니다. 다른 권한 API와 달리 사용자 승인이 필요 없습니다.

관련 속성 및 이벤트

이름	설명
onLine	현재 브라우저의 온라인 상태 여부를 반환합니다.
online event	오프라인 상태에서 인터넷이 다시 연결된 순간 발생합니다.
offline event	인터넷 연결이 끊긴 순간 발생합니다.

인터넷 상태에 따라 전송 큐 제어하기

const checkNetworkStatus = () => {
  if (navigator.onLine) {
    console.log('NETWORK_ONLINE: 서버와 연결이 가능합니다. 큐 전송을 시작합니다.');
    processQueue();
  } else {
    console.warn('NETWORK_OFFLINE: 인터넷이 끊겼습니다. 데이터를 로컬에 보관합니다.');
  }
};

const initNetworkListeners = () => {
  window.addEventListener('online', () => {
    console.log('EVENT_ONLINE: 인터넷이 복구되었습니다! 밀린 로그를 전송합니다.');
    processQueue();
  });

  window.addEventListener('offline', () => {
    console.error('EVENT_OFFLINE: 인터넷 연결이 감지되지 않습니다. 전송을 중단합니다.');
  });
};

기타 정보

• navigator.onLine이 true라고 해서 반드시 서버와 통신 가능한 상태라는 뜻은 아닙니다.

• 랜선이 연결되어 있거나 Wi-Fi가 잡혀 있는 상태에 가깝게 판단될 수 있습니다.

• online 이벤트 발생 직후 바로 전송하기보다 setTimeout으로 1~2초 정도 지연한 뒤 재전송하는 편이 안정적입니다.

2-6. sendBeacon

sendBeacon은 브라우저 종료, 페이지 이동 같은 상황에서도 웹 서버에 데이터를 더 안정적으로 전송하기 위해 사용합니다.

주요 메서드

메서드	설명
sendBeacon(url, data)	전송할 데이터를 대기열에 성공적으로 추가하면 true를 반환합니다.

첨부 텍스트는 sendBeacon 섹션 설명이 중간에서 잘려 있어, 확인 가능한 범위까지만 반영했습니다.