설명
chrome.alarms API를 사용하여 주기적으로 또는 향후 지정된 시간에 코드가 실행되도록 예약합니다.
권한
alarmschrome.alarms API를 사용하려면 manifest에서 "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 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
모든 알람을 삭제합니다.
매개변수
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(wasCleared: boolean) => void
-
wasCleared
부울
-
반환 값
-
Promise<boolean>
Chrome 91 이상Promise는 매니페스트 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
반환 값
-
Promise<void>
Chrome 111 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
지정된 알람에 대한 세부정보를 가져옵니다.
매개변수
반환 값
-
Promise<Alarm | undefined>
Chrome 91 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
getAll()
chrome.alarms.getAll(
callback?: function,
)
모든 알람 배열을 가져옵니다.
반환 값
-
Promise<Alarm[]>
Chrome 91 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.