chrome.alarms

ब्यौरा

chrome.alarms API का इस्तेमाल करके, कोड को समय-समय पर या भविष्य में किसी तय समय पर चलाने के लिए शेड्यूल किया जा सकता है.

अनुमतियां

alarms

chrome.alarms API का इस्तेमाल करने के लिए, "alarms" अनुमति का एलान मेनिफ़ेस्ट में करें:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

कॉन्सेप्ट और इस्तेमाल

एपीआई के भरोसेमंद तरीके से काम करने के लिए, यह समझना ज़रूरी है कि यह कैसे काम करता है.

डिवाइस स्लीप मोड में होने पर अलार्म बजना

डिवाइस स्लीप मोड में होने पर भी अलार्म बजते रहते हैं. हालांकि, अलार्म बजने पर डिवाइस स्लीप मोड से बाहर नहीं आता. डिवाइस के स्लीप मोड से बाहर आने पर, वे अलार्म बजेंगे जो स्लीप मोड में होने की वजह से नहीं बज पाए थे. बार-बार बजने वाले अलार्म, ज़्यादा से ज़्यादा एक बार बजेंगे. इसके बाद, उन्हें तय की गई अवधि के हिसाब से फिर से शेड्यूल किया जाएगा. यह अवधि, अलार्म के ओरिजनल तौर पर सेट किए गए समय से नहीं, बल्कि डिवाइस के स्लीप मोड से बाहर आने के समय से शुरू होगी.

स्थायी

अलार्म बनाते समय, persistAcrossSessions फ़्लैग का इस्तेमाल करके, यह तय किया जा सकता है कि अलार्म को स्थायी रखना है या नहीं. इसे true (एक्सटेंशन अपडेट होने तक अलार्म बना रहता है) या false (एक्सटेंशन रीलोड होने या ब्राउज़र रीस्टार्ट होने पर अलार्म मिट जाता है. साथ ही, एक्सटेंशन अपडेट होने पर भी अलार्म मिट जाता है) पर सेट किया जा सकता है.

अन्य ब्राउज़र और Chrome के पुराने वर्शन

इस प्रॉपर्टी का इस्तेमाल, अन्य ब्राउज़र (समस्या) या Chrome के उन वर्शन में नहीं किया जा सकता जो Chrome 150 से पहले के हैं. इनमें यह प्रॉपर्टी, अनुमान के मुताबिक काम नहीं करती. इसलिए, यह पक्का करना ज़रूरी है कि आपका सर्विस वर्कर हर बार शुरू होने पर, ज़रूरी अलार्म मौजूद हों. उदाहरण के लिए:

async function checkAlarmState() {
  const alarm = await chrome.alarms.get("my-alarm");

  if (!alarm) {
    await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

अगर आपका अलार्म, उपयोगकर्ता की कार्रवाई के आधार पर डाइनैमिक तरीके से बनाया गया है, तो आपको यह जानकारी कहीं सेव करनी चाहिए कि अलार्म बनाया गया था. इससे, ज़रूरत पड़ने पर उसे फिर से बनाया जा सकेगा.

उदाहरण

यहां दिए गए उदाहरणों में, अलार्म का इस्तेमाल करने और उसके बजने पर कार्रवाई करने का तरीका बताया गया है. इस एपीआई को आज़माने के लिए, Alarm API का उदाहरण chrome-extension-samples रिपॉज़िटरी से इंस्टॉल करें.

अलार्म सेट करें

यहां दिए गए उदाहरण में, एक्सटेंशन का नया वर्शन इंस्टॉल होने पर, सर्विस वर्कर में अलार्म सेट करने का तरीका बताया गया है:

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

अलार्म बजने पर कार्रवाई करना

यहां दिए गए उदाहरण में, अलार्म बजने पर ऐक्शन टूलबार आइकॉन सेट करने का तरीका बताया गया है. यह आइकॉन, अलार्म के नाम के आधार पर सेट किया जाता है.

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

टाइप

Alarm

प्रॉपर्टी

  • नाम

    स्ट्रिंग

    इस अलार्म का नाम.

  • periodInMinutes

    संख्या ज़रूरी नहीं

    अगर यह वैल्यू null नहीं है, तो अलार्म बार-बार बजेगा और periodInMinutes मिनट बाद फिर से बजेगा.

  • persistAcrossSessions

    बूलियन

    Chrome 150 और इसके बाद के वर्शन

    चुनें कि अलार्म को सेशन के बीच (ब्राउज़र रीस्टार्ट होने पर भी) स्थायी रखना है या नहीं.

  • scheduledTime

    संख्या

    वह समय जब इस अलार्म को बजने के लिए शेड्यूल किया गया था.यह समय, epoch के बाद के मिलीसेकंड में होता है. जैसे, Date.now() + n. परफ़ॉर्मेंस की वजह से, अलार्म को इससे ज़्यादा समय के लिए भी डिले किया जा सकता है.

AlarmCreateInfo

प्रॉपर्टी

  • delayInMinutes

    संख्या ज़रूरी नहीं

    वह समय (मिनटों में), जिसके बाद onAlarm इवेंट ट्रिगर होना चाहिए.

  • periodInMinutes

    संख्या ज़रूरी नहीं

    अगर यह वैल्यू सेट की जाती है, तो `onAlarm` इवेंट, when या delayInMinutes से तय किए गए शुरुआती इवेंट के बाद, हर periodInMinutes मिनट में ट्रिगर होना चाहिए. अगर यह वैल्यू सेट नहीं की जाती है, तो अलार्म सिर्फ़ एक बार बजेगा.

  • persistAcrossSessions

    बूलियन ज़रूरी नहीं

    Chrome 150 और इसके बाद के वर्शन

    चुनें कि अलार्म को सेशन के बीच (ब्राउज़र रीस्टार्ट होने पर भी) स्थायी रखना है या नहीं. Chrome में, यह वैल्यू डिफ़ॉल्ट तौर पर 'सही' पर सेट होती है, ताकि यह पुराने वर्शन के हिसाब से काम करे. हालांकि, आपको इसे साफ़ तौर पर सेट करना चाहिए, ताकि यह सभी ब्राउज़र पर काम करे.

  • when

    संख्या ज़रूरी नहीं

    वह समय जब अलार्म बजना चाहिए.यह समय, epoch के बाद के मिलीसेकंड में होता है. जैसे, 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

    AlarmCreateInfo

    यह बताता है कि अलार्म कब बजना चाहिए. शुरुआती समय, when या delayInMinutes में से किसी एक से तय किया जाना चाहिए. दोनों से नहीं. अगर periodInMinutes सेट किया जाता है, तो अलार्म, शुरुआती इवेंट के बाद हर periodInMinutes मिनट में बजेगा. अगर बार-बार बजने वाले अलार्म के लिए, when या delayInMinutes में से कोई भी वैल्यू सेट नहीं की जाती है, तो periodInMinutes को delayInMinutes के लिए डिफ़ॉल्ट वैल्यू के तौर पर इस्तेमाल किया जाता है.

रिटर्न

  • Promise<void>

    Chrome 111 और इसके बाद के वर्शन

    वह प्रॉमिस जो अलार्म सेट होने पर रिज़ॉल्व होता है.

get()

chrome.alarms.get(
  name?: string,
): Promise<Alarm | undefined>

चुने गए अलार्म के बारे में जानकारी वापस लाता है.

पैरामीटर

  • नाम

    स्ट्रिंग ज़रूरी नहीं

    वह अलार्म जिसके बारे में जानकारी चाहिए. डिफ़ॉल्ट तौर पर, यह खाली स्ट्रिंग होती है.

रिटर्न

  • Promise<Alarm | undefined>

    Chrome 91 और इसके बाद के वर्शन

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

सभी अलार्म की एक कलेक्शन वापस लाता है.

रिटर्न

  • Promise<Alarm[]>

    Chrome 91 और इसके बाद के वर्शन

इवेंट

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

अलार्म बजने पर ट्रिगर होता है. इवेंट पेजों के लिए काम का है.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर इस तरह दिखता है: 

    (alarm: Alarm) => void