설명
chrome.alarms API를 사용하여 코드가 주기적으로 또는 향후 특정 시간에 실행되도록 예약합니다.
권한
alarmschrome.alarms API를 사용하려면 매니페스트에서 "alarms" 권한을 선언합니다.
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
개념 및 사용법
안정적인 동작을 보장하기 위해서는 API의 동작을 이해하는 것이 도움이 됩니다.
기기 절전 모드
기기가 절전 모드인 동안에도 알람은 계속 실행됩니다. 하지만 알람이 울리지 않더라도 기기의 절전 모드를 해제합니다. 기기의 절전 모드가 해제되면 놓친 알람이 울립니다. 반복 알람은 최대 한 번 실행된 후 기기의 절전 모드가 해제된 시점부터 지정된 기간을 고려하며, 알람이 원래 실행되도록 설정한 이후 이미 경과된 시간입니다.
지속성
경보는 일반적으로 확장 프로그램이 업데이트될 때까지 지속됩니다. 하지만 반드시 그런 것은 아니며, 알람은 브라우저가 다시 시작되면 가 삭제될 수 있습니다. 따라서 스토리지에 값을 설정하는 것이 좋습니다. 사용할 수 있도록 하고 서비스 워커를 시작할 때마다 해당 알람이 존재하는지 확인하세요. 예를 들면 다음과 같습니다.
const STORAGE_KEY = "user-preference-alarm-enabled";
async function checkAlarmState() {
const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);
if (alarmEnabled) {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create({ periodInMinutes: 1 });
}
}
}
checkAlarmState();
예
다음 예는 알람을 사용하고 알람에 응답하는 방법을 보여줍니다. 이 API를 사용해 보려면 chrome-extension-samples에서 Alarm API 예 설치 저장소
알람 설정해 줘
다음 예에서는 확장 프로그램이 설치될 때 서비스 워커에 알람을 설정합니다.
service-worker.js:
chrome.runtime.onInstalled.addListener(async ({ reason }) => {
if (reason !== 'install') {
return;
}
// Create an alarm so we have something to look at in the demo
await chrome.alarms.create('demo-default-alarm', {
delayInMinutes: 1,
periodInMinutes: 1
});
});
알람에 응답하기
다음 예는 종료된 알람의 이름을 기반으로 작업 툴바 아이콘을 설정합니다.
service-worker.js:
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
유형
Alarm
속성
-
이름
문자열
이 알람의 이름입니다.
-
periodInMinutes
숫자 선택사항
null이 아닌 경우 알람은 반복 알람이며
periodInMinutes분 후에 다시 실행됩니다. -
scheduledTime
숫자
이 알람이 실행되도록 예약된 시간으로, 에포크 이후의 밀리초 단위로 표시됩니다 (예:
Date.now() + n). 성능상의 이유로 알람이 이 범위를 초과하는 임의의 시간만큼 지연되었을 수 있습니다.
AlarmCreateInfo
속성
-
delayInMinutes
숫자 선택사항
onAlarm이벤트가 실행되기까지 걸리는 시간(분)입니다. -
periodInMinutes
숫자 선택사항
설정된 경우 onAlarm 이벤트는
when또는delayInMinutes로 지정된 초기 이벤트 이후periodInMinutes분마다 실행되어야 합니다. 설정하지 않으면 알람이 한 번만 실행됩니다. -
언제
숫자 선택사항
알람이 실행되어야 하는 시간이며 에포크 이후의 밀리초 단위로 표시됩니다 (예:
Date.now() + n).
메서드
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
지정된 이름의 알람을 지웁니다.
매개변수
-
이름
문자열(선택사항)
삭제할 알람의 이름입니다. 기본값은 빈 문자열입니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(wasCleared: boolean) => void
-
wasCleared
부울
-
반환 값
-
Promise<boolean>
Chrome 91 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
모든 알람을 지웁니다.
매개변수
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(wasCleared: boolean) => void
-
wasCleared
부울
-
반환 값
-
Promise<boolean>
Chrome 91 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
알람을 생성합니다. alarmInfo에서 지정한 시간에 가까워지면 onAlarm 이벤트가 실행됩니다. 같은 이름의 다른 알람이 있는 경우 (또는 지정하지 않으면 이름이 없는 경우) 취소되고 이 알람으로 대체됩니다.
사용자 컴퓨터의 부하를 줄이기 위해 Chrome은 알람을 30초에 한 번 이하로 제한하지만, 임의의 시간만큼 지연할 수도 있습니다. 즉, delayInMinutes 또는 periodInMinutes를 0.5보다 작게 설정하면 적용되지 않으며 경고가 발생합니다. when는 '지금'을 기준으로 30초 미만으로 설정할 수 있습니다. 최소 30초 동안 경보가 실행되지 않습니다.
앱이나 확장 프로그램을 디버그하는 데 도움이 되도록, 압축을 해제한 상태로 로드하면 알람 실행 빈도에 제한이 없습니다.
매개변수
-
이름
문자열(선택사항)
이 알람을 식별하기 위한 이름입니다(선택사항). 기본값은 빈 문자열입니다.
-
alarmInfo
알람이 실행되는 시점을 설명합니다. 초기 시간은
when또는delayInMinutes중 하나로 지정해야 합니다. 둘 다 지정할 수는 없습니다.periodInMinutes가 설정되면 첫 이벤트 후periodInMinutes분마다 알람이 반복됩니다. 반복 알람에when와delayInMinutes가 모두 설정되어 있지 않으면periodInMinutes가delayInMinutes의 기본값으로 사용됩니다. -
콜백
함수 선택사항
Chrome 111 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.callback매개변수는 다음과 같습니다.() => void
반환 값
-
프로미스<void>
Chrome 111 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
지정된 알람에 대한 세부정보를 검색합니다.
매개변수
반환 값
-
Promise<Alarm | 정의되지 않음>
Chrome 91 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
getAll()
chrome.alarms.getAll(
callback?: function,
)
모든 알람의 배열을 가져옵니다.
반환 값
-
Promise<Alarm[]>
Chrome 91 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.