설명
chrome.alarms API를 사용하여 코드가 주기적으로 또는 지정된 미래 시간에 실행되도록 예약합니다.
권한
alarmschrome.alarms API를 사용하려면 "alarms" 권2한을 매니페스트에서 선언하세요.
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
개념 및 사용
안정적인 동작을 보장하려면 API의 동작 방식을 이해하는 것이 좋습니다.
기기 절전 모드
기기가 절전 모드일 때도 알람은 계속 실행됩니다. 하지만 알람이 기기를 절전 모드에서 해제하지는 않습니다. 기기가 절전 모드에서 해제되면 누락된 알람이 실행됩니다. 반복 알람은 최대 한 번 실행된 후 기기가 절전 모드에서 해제된 시점부터 지정된 기간을 사용하여 다시 예약되며, 알람이 원래 실행되도록 설정된 후 이미 경과된 시간은 고려하지 않습니다.
지속성
알람은 일반적으로 확장 프로그램이 업데이트될 때까지 지속됩니다. 하지만 이는 보장되지 않으며 브라우저가 다시 시작될 때 알람이 삭제될 수 있습니다. 따라서 서비스 워커가 시작될 때마다 알람이 있는지 확인하세요. 예를 들면 다음과 같습니다.
async function checkAlarmState() {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
}
}
checkAlarmState();
예
다음 예에서는 알람을 사용하고 이에 응답하는 방법을 보여줍니다. 이 API를 사용해 보려면 알람 API 예시를 chrome-extension-samples 저장소에서 설치하세요.
알람 설정
다음 예에서는 확장 프로그램이 설치될 때 서비스 워커에서 알람을 설정합니다.
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분 후에 다시 실행됩니다. -
persistAcrossSessions
부울
대기 중알람이 세션 (브라우저 다시 시작) 간에 지속되어야 하는지 여부입니다.
-
scheduledTime
숫자
이 알람이 실행되도록 예약된 시간입니다 (에포크 이후 경과된 밀리초, 예:
Date.now() + n). 성능상의 이유로 알람이 이 시간을 지나 임의의 시간만큼 지연되었을 수 있습니다.
AlarmCreateInfo
속성
-
delayInMinutes
숫자 선택사항
onAlarm이벤트가 실행되어야 하는 시간(분)입니다. -
periodInMinutes
숫자 선택사항
설정된 경우 onAlarm 이벤트는
when또는delayInMinutes로 지정된 초기 이벤트 후periodInMinutes분마다 실행되어야 합니다. 설정되지 않은 경우 알람은 한 번만 실행됩니다. -
persistAcrossSessions
부울 선택사항
대기 중알람이 세션 (브라우저 다시 시작) 간에 지속되어야 하는지 여부입니다. Chrome에서는 이전 동작과 일치하도록 기본값이 true이지만 브라우저 간의 호환성을 극대화하려면 이 값을 명시적으로 설정해야 합니다.
-
언제
숫자 선택사항
알람이 실행되어야 하는 시간입니다 (에포크 이후 경과된 밀리초, 예:
Date.now() + n).
메서드
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
지정된 이름의 알람을 삭제합니다.
매개변수
-
이름
문자열 선택사항
삭제할 알람의 이름입니다. 기본값은 빈 문자열입니다.
반환 값
-
Promise<boolean>
Chrome 91 이상
clearAll()
chrome.alarms.clearAll(): Promise<boolean>
모든 알람을 삭제합니다.
반환 값
-
Promise<boolean>
Chrome 91 이상
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
알람을 만듭니다. alarmInfo로 지정된 시간에 onAlarm 이벤트가 실행됩니다. 이름이 같은 다른 알람이 있거나 이름이 지정되지 않은 경우 이름이 없는 다른 알람이 있으면 취소되고 이 알람으로 대체됩니다.
사용자 머신의 부하를 줄이기 위해 Chrome은 알람을 최대 30초에 한 번으로 제한하지만 임의의 시간만큼 더 지연시킬 수 있습니다. 즉, delayInMinutes 또는 periodInMinutes를 0.5보다 작은 값으로 설정해도 적용되지 않으며 경고가 발생합니다. when은 경고 없이 '지금'으로부터 30초 미만으로 설정할 수 있지만 실제로 알람이 실행되려면 최소 30초가 걸립니다.
앱 또는 확장 프로그램을 압축 해제된 상태로 로드한 경우 앱 또는 확장 프로그램을 디버그하는 데 도움이 되도록 알람이 실행될 수 있는 횟수에 제한이 없습니다.
매개변수
-
이름
문자열 선택사항
이 알람을 식별하는 데 사용할 수 있는 이름입니다. 기본값은 빈 문자열입니다.
-
alarmInfo
알람이 실행되어야 하는 시점을 설명합니다. 초기 시간은
when또는delayInMinutes로 지정해야 합니다 (둘 다 지정할 수는 없음).periodInMinutes가 설정된 경우 알람은 초기 이벤트 후periodInMinutes분마다 반복됩니다. 반복 알람에when또는delayInMinutes가 설정되지 않은 경우periodInMinutes가delayInMinutes의 기본값으로 사용됩니다.
반환 값
-
Promise<void>
Chrome 111 이상알람이 생성되면 확인되는 프로미스입니다.
매개변수
-
이름
문자열 선택사항
가져올 알람의 이름입니다. 기본값은 빈 문자열입니다.
반환 값
-
Promise<Alarm | undefined>
Chrome 91 이상
반환 값
-
Promise<Alarm[]>
Chrome 91 이상