Page Visibility API

Sckroll·2024년 10월 6일

개요

Page Visibility API는 현재 보고 있는 브라우저 탭이 화면에 보여지거나, 숨겨질 때를 감지할 수 있는 웹 API다.

이 API를 사용하면 현재 탭을 사용하고 있지 않을 때, 즉 다른 탭으로 전환하거나 웹페이지를 최소화했을 때 리소스를 절약하거나 성능 최적화 동작을 수행할 수 있다. 실제로 유튜브 같은 사이트는 탭이 비활성화될 때 동영상 화질을 낮추거나, 음성만 재생하거나, 자동 재생을 막아 데이터 전송량을 줄인다고 한다.

데스크탑 뿐만 아니라 모바일 기기에서도 감지가 가능하기 때문에, 보고 있는 앱(브라우저)에서 다른 앱으로 전환할 때에도 이 이벤트가 발생한다.

Page Visibility API caniuse.com

업로드일 기준으로 사실상 모든 브라우저에서 사용 가능하다. 궁금하다면 직접 보자.

API

`visibilitychange` & `document.visibilityState`

대표적으로는 visibilitychange 이벤트가 있지만, visibilitychange 이벤트 자체로는 탭 활성화 상태를 알 수 없기 때문에 document.visibilityState와 같이 사용해야 한다. document.visibilityState는 다음 두 개 중 하나의 값을 가진다.

visible
- 현재 탭을 보고 있을 때 설정되는 값 (최소화 되지 않은 창(브라우저)의 선택된 탭)
hidden
- 탭이 바뀌거나 탭을 닫을 때, 브라우저를 닫거나 최소화할 때, 모바일 기기에서 다른 앱으로 전환하거나 OS 화면 잠금 상태일 때 설정되는 값

`document.hidden`

탭 비활성화 여부를 boolean 값으로 알려준다. document.visibilityState === hidden과 동일하다.

Page Visibility API vs. `blur` & `focus`

Page Visibility API 외에도 window의 blur와 focus 이벤트를 사용해서 탭 활성화 감지 기능을 구현할 수 있지만, Page Visibility API보다 직관적이고 정밀하지 못하다는 단점이 있다. 애초에 blur와 focus는 페이지 전체보다는 요소(<input> 등)에 초점을 둔 느낌이다.

참고: Page Visibility API는 document의 이벤트를 사용한다.

아래와 같이 모바일 브라우저에서 탭 전환 화면으로 들어가면, visibilitychange 이벤트는 탭이 아직 활성화 되어 있다고 판단하지만, blur와 focus는 비활성화 되었다고 처리한다는 차이점도 있다.

Mobile browser tab list

그리고 iframe 사용 시 visibilitychange 이벤트를 사용하면 부모 프레임과 자식 프레임이 같은 상태를 공유하지만, blur와 focus 이벤트를 사용하면 두 프레임이 서로 같은 상태를 공유하지 않는다는 점도 있다. 즉, 부모 프레임에서는 탭이 비활성화 상태라고 판단하지만, 자식 프레임에서는 탭이 활성화 상태라고 판단할 수도 있는 것이다.

사용법

이벤트 등록 & 탭 숨김 상태 확인

// 이벤트 등록
document.addEventListener("visibilitychange", () => {
	// visible이면 현재 탭, hidden이면 다른 탭으로 전환되었다는 의미
  	if (document.visibilityState === 'hidden') {
		// 탭이 숨겨질 때 로직 처리
  	} else {
	  	// 탭이 보여질 때 로직 처리
  	}

	// 다른 탭 전환 여부를 boolean 값으로 확인하는 방법
	console.log(document.hidden);
});

이벤트 등록 여부 확인 방법

console.log(getEventListeners(document).visibilitychange);

사용 예시

탭이 비활성화 되었을 때 음악 일시정지

// 음악을 재생하는 오디오 DOM 요소
const audio = document.querySelector("audio");

// 탭 활성화 여부에 따라 오디오 일시정지/재생
document.addEventListener("visibilitychange", () => {
    if (document.hidden) {
      	audio.pause();
    } else {
      	audio.play();
    }
});