अग्रभूमि सेवा स्वास्थ्य

एंड्रॉइड पर, एक सतत अग्रभूमि सेवा वह है जो पृष्ठभूमि स्थान रखती है जीवित ट्रैकिंग. लेकिन (Tracelet.start()) को ट्रैक करने के लिए पूछना वैसा नहीं है ओएस एक चालू अग्रभूमि सेवा प्रदान कर रहा है। Android 12+ पर a अग्रभूमि-सेवा प्रारंभ को स्थगित या अस्वीकृत किया जा सकता है - तब भी जब आपका ऐप विश्वास है कि ट्रैकिंग सक्षम है.

Tracelet.getForegroundServiceHealth() उस अंतर को ख़त्म करता है। यह रिपोर्ट करता है अग्रभूमि सेवा की आधिकारिक मूल स्थिति ताकि आप बता सकें “ट्रैकिंग का अनुरोध किया गया था” और “ट्रैकिंग वास्तव में है” के बीच अंतर चल रहा है” - और जब वे अलग हो जाएं तो प्रतिक्रिया करें।

3.6.6 में नया। यह अग्रभूमि-सेवा विश्वसनीयता सुधारों का पूरक है 3.6.5 (#253 ) और 3.6.6 (#254 ) सेवा बनाकर डार्ट से देखने योग्य वास्तविक स्थिति।

`enabled` पर्याप्त क्यों नहीं है?

Tracelet.getState().enabled वांछित स्थिति है - निरंतर इरादा रास्ता। यह उत्तर देता है “क्या ऐप ने ट्रैक करने के लिए कहा है?”, नहीं “वास्तव में ओएस है अभी अग्रभूमि सेवा चल रही है?”।

वे भिन्न हो सकते हैं, विशेष रूप से एंड्रॉइड 12+ (एपीआई 31+) पर, जहां से शुरू होता है पृष्ठभूमि से location अग्रभूमि सेवा प्रतिबंधित है:

शुरुआत को स्थगित किया जा सकता है - ऐप चालू होने पर एंड्रॉइड इसे अस्वीकार कर देता है पृष्ठभूमि में, और जब ऐप अगली बार वापस आता है तो ट्रैसलेट स्वचालित रूप से पुनः प्रयास करता है अग्रभूमि.
शुरुआत पूरी तरह विफल हो सकती है - उदाहरण के लिए। अनुपलब्ध अनुमति, या a देर से अनुवाद न करें.
सिस्टम द्वारा सेवा को प्रचारित किया जा सकता है, फिर रोका** जा सकता है।

इन सभी मामलों में enabled true ही रहता है, लेकिन बैकग्राउंड ट्रैकिंग नहीं होती है परिचालन. एक स्थान-टाइमस्टैम्प निगरानीकर्ता अंततः स्थिरता को नोटिस कर सकता है, लेकिन यह आपको यह नहीं बता सकता कि क्यों - क्या पदोन्नति विफल रही, सेवा रोक दी गई, या प्रदाता बस नए समाधान की प्रतीक्षा कर रहा है। नोटट्रांस0देर से आपको वास्तविक, आधिकारिक कारण देता है।

एपीआई


final health = await Tracelet.getForegroundServiceHealth();

निम्नलिखित कुंजियों के साथ Map<String, Object?> लौटाता है:

कुंजी	प्रकार	मतलब
`desiredEnabled`	`bool`	कायम वांछित ट्रैकिंग स्थिति (`getState().enabled` के समान)।
`foregroundServiceEnabled`	`bool`	क्या सक्रिय कॉन्फिग बिल्कुल अग्रभूमि सेवा चलाता है।
`serviceRunning`	`bool`	क्या मूल स्थान सेवा प्रक्रिया जीवित है.
`serviceForeground`	`bool`	क्या सेवा को वर्तमान में अग्रभूमि में प्रचारित किया गया है (अंतिम `startForeground()` सफल हुआ और उसके बाद से इसे पदावनत/रोका नहीं गया है)।
`foregroundNotificationId`	`int?`	प्रचारित होने पर अधिसूचना आईडी; अन्यथा `null`।
`lastForegroundPromotionResult`	`String?`	`success`, `deferred`, या `failed` - सबसे हालिया प्रचार प्रयास का परिणाम (किसी भी प्रयास से पहले `null`)।
`lastForegroundPromotionFailureClass`	`String?`	अंतिम असफल/स्थगित पदोन्नति का अपवाद वर्ग (उदा. `ForegroundServiceStartNotAllowedException`)।
`lastForegroundPromotionFailureMessage`	`String?`	अपवाद संदेश.
`lastForegroundTransitionAt`	`int?`	अंतिम पदोन्नति संक्रमण का युग-मिलीसेकंड.
`platform`	`String`	`android`, `ios`, या `web`।

मानचित्र का आकार जानबूझकर हर प्लेटफ़ॉर्म पर समान है इसलिए क्रॉस-प्लेटफ़ॉर्म कोड इसे समान रूप से पढ़ सकते हैं. केवल मान प्रति प्लेटफ़ॉर्म भिन्न होते हैं (नीचे देखें)।

पदोन्नति परिणाम पढ़ना

serviceForeground lastForegroundPromotionResult के साथ मिलकर आपको बताता है सारा वृत्तांत:

`desiredEnabled`	`serviceForeground`	`lastForegroundPromotionResult`	व्याख्या
`false`	`false`	कोई भी	ट्रैकिंग बंद है - चिंता की कोई बात नहीं।
`true`	`true`	`success`	✅ स्वस्थ - अग्रभूमि सेवा चल रही है और प्रचारित है।
`true`	`false`	`deferred`	⏳ स्थगित - पृष्ठभूमि के दौरान एंड्रॉइड ने प्रारंभ से इनकार कर दिया; जब ऐप अग्रभूमि पर वापस आएगा तो ट्रेसलेट पुनः प्रयास करेगा।
`true`	`false`	`failed`	❌ विफल — पदोन्नति विफल; पृष्ठभूमि ट्रैकिंग चालू नहीं है। विफलता वर्ग/संदेश का निरीक्षण करें.
`true`	`false`	`null`	⌛ अनुरोध किया गया है लेकिन अभी तक पुष्टि नहीं हुई है (क्षणिक - शीघ्र ही फिर से मतदान)।

एक ट्रैकिंग-स्वास्थ्य संकेतक

सबसे आम उपयोग: उपयोगकर्ता (या आपकी टेलीमेट्री) को एक ईमानदार स्थिति प्रदान करना enabled पर आंख मूंदकर भरोसा करने के बजाय।


Future<String> describeTrackingHealth() async {
  final h = await Tracelet.getForegroundServiceHealth();
 
  if (h['desiredEnabled'] != true) return 'Tracking off';
 
  // iOS/web have no foreground service — enabled tracking is as good as it gets.
  if (h['platform'] != 'android') return 'Tracking active';
 
  if (h['serviceForeground'] == true) return 'Tracking active';
 
  switch (h['lastForegroundPromotionResult']) {
    case 'deferred':
      return 'Waiting to start — reopen the app to resume background tracking';
    case 'failed':
      final reason = h['lastForegroundPromotionFailureMessage'] ?? 'unknown';
      return 'Background tracking failed to start: $reason';
    default:
      return 'Starting…';
  }
}

एक पुनर्प्राप्ति प्रहरी

किसी विफलता का पता लगाने और उससे उबरने के लिए स्वास्थ्य जांच को एक आवधिक टाइमर के साथ जोड़ें प्रमोशन - उदाहरण के लिए, उपयोगकर्ता को ऐप को फिर से खोलने के लिए प्रेरित करें, या फिर से अनुरोध करें अनुपलब्ध अनुमति.


Timer.periodic(const Duration(minutes: 1), (_) async {
  final h = await Tracelet.getForegroundServiceHealth();
 
  final desired = h['desiredEnabled'] == true;
  final foreground = h['serviceForeground'] == true;
  final result = h['lastForegroundPromotionResult'];
 
  if (desired && !foreground && result == 'failed') {
    // Background tracking is not operational. Log it, alert your backend,
    // or guide the user to fix permissions / battery settings.
    await reportTrackingDegraded(
      failureClass: h['lastForegroundPromotionFailureClass'],
      failureMessage: h['lastForegroundPromotionFailureMessage'],
    );
  }
});

serviceForeground अंतिम पदोन्नति परिणाम को दर्शाता है, लाइव पोल को नहीं ओएस हर मिलीसेकेंड। start() के तुरंत बाद, प्रमोशन रुक जाता है बाद में - यदि आपको ताज़ा मूल्य की आवश्यकता है तो थोड़े विलंब (1-2 सेकंड) के बाद फिर से मतदान करें।

मंच व्यवहार

प्लेटफार्म	व्यवहार
एंड्रॉइड	लाइव अग्रभूमि-सेवा स्थिति और प्रचार इतिहास से पूरी तरह भरा हुआ।
आईओएस	ऐसी कोई अग्रभूमि सेवा नहीं है जो इस तथ्य के बाद विफल हो सकती है, इसलिए `serviceForeground` `false` है, `foregroundServiceEnabled` `false` है, और प्रचार फ़ील्ड `null` हैं। `desiredEnabled` और `serviceRunning` दर्शाते हैं कि ट्रैकिंग सक्रिय है या नहीं। `platform` `ios` है।
वेब	कोई अग्रभूमि सेवा नहीं. वांछित स्थिति को प्रतिबिंबित करने वाला न्यूनतम मानचित्र लौटाता है; `platform` `web` है।

यही कारण है कि आईओएस अग्रभूमि-सेवा प्रचार दौड़ से अप्रभावित है #253 और में Android के लिए तय किया गया #254 : iOS का कोई अलग नहीं है अग्रभूमि-सेवा प्रक्रिया जिसे बढ़ावा दिया जा सकता है और फिर नष्ट किया जा सकता है।

ट्रैसलेट डॉक्टर में

इसे देखने के लिए आपको इसे स्वयं बनाने की आवश्यकता नहीं है। tracelet_doctor ओवरले में अब फोरग्राउंड शामिल है सेवा कार्ड जो बिल्कुल यही जानकारी प्रस्तुत करता है - वांछित बनाम वास्तविक, पदोन्नति परिणाम, और कोई भी विफलता वर्ग/संदेश - रंग-कोडित स्थिति के साथ (स्वस्थ/विलंबित/असफल/निष्क्रिय)।

tracelet_doctor एक देव निर्भरता (flutter pub add dev:tracelet_doctor) है, इसलिए इसे kDebugMode से सुरक्षित रखें:


import 'package:flutter/foundation.dart' show kDebugMode;
import 'package:tracelet_doctor/tracelet_doctor.dart';
 
if (kDebugMode) {
  TraceletDoctor.show(context); // includes the Foreground Service card
}

वही फ़ील्ड बग रिपोर्ट (TraceletBugReport.build()) में भी कैप्चर की जाती हैं, इसलिए चिपकाई गई रिपोर्ट से पता चलता है कि अग्रभूमि सेवा वास्तव में चल रही थी या नहीं मुद्दे का समय - अक्सर “ट्रैकिंग स्टॉप” में गायब सुराग पृष्ठभूमि” रिपोर्ट।

जानकर अच्छा लगा

केवल-पढ़ने के लिए और सस्ता। कॉल केवल मेमोरी में मूल स्थिति पढ़ता है; यह कभी नहीं ट्रैकिंग शुरू करता है, रोकता है या परिवर्तित करता है।
ready() से पहले सुरक्षित। इसके बजाय यह एक समझदार डिफ़ॉल्ट स्नैपशॉट लौटाता है यदि SDK प्रारंभ नहीं किया गया है तो फेंकना।
वांछित बनाम वास्तविक ही संपूर्ण मुद्दा है। इसके लिए getState().enabled का उपयोग करते रहें आपके ऐप का इरादा; OS सत्यापित करने के लिए getForegroundServiceHealth() का उपयोग करें उस इरादे का सम्मान करते हुए.