सेंसर, फ़ाइलें और बैकग्राउंड जॉब

1दूसरे ऐप से फ़ाइलें, फ़ोटो, वीडियो और लिंक पाएँ#

विज़ार्ड में 'Receive Shares From Other Apps' चालू करें और टिक करें कि आपका ऐप क्या स्वीकार करेगा - टेक्स्ट और लिंक, डेटा फ़ाइलें (FIT, GPX, TCX, CSV, JSON, XML…), फ़ोटो, वीडियो, ऑडियो, डॉक्यूमेंट। आपका ऐप ठीक उन्हीं प्रकारों के लिए दो जगह दिखता है:

1. जब यूज़र किसी फ़ाइल पर टैप करता है तब दिखने वाली Android की 'Open with' शीट।
2. दूसरे ऐप की SHARE / EXPORT शीट - जिसमें वर्कआउट फ़ाइलें (.fit, .gpx, .tcx) एक्सपोर्ट करने वाले स्पोर्ट डिवाइस भी शामिल हैं। ज़्यादातर फ़िटनेस ऐप Share से एक्सपोर्ट करते हैं, इसीलिए जो ऐप सिर्फ़ 'Open with' रजिस्टर करते हैं वे वहाँ कभी नहीं दिखते।

फ़ाइल AppMint.getOpenedFile() से माँगें - यह आपका इंतज़ार करता है, चाहे आपका पेज कितनी भी देर से शुरू हो। f.kind image, video, audio, document या data होता है। टेक्स्ट फ़ॉर्मेट (gpx, tcx, csv, json, xml…) सीधे इस्तेमाल लायक f.text के रूप में आते हैं; छोटी बाइनरी (.fit) f.base64 के रूप में; हर डेटा फ़ाइल और डॉक्यूमेंट f.file में असली File के रूप में। फ़ोटो, वीडियो और ऑडियो f.url के रूप में आते हैं, जो <video src> / <img src> के लिए स्ट्रीम होने लायक पता है, और बाइट चाहिए तो f.getFile() है। आकार की कोई सीमा नहीं है। शेयर किया गया लिंक या कैप्शन WebToApk.getSharedText() से पढ़ा जाता है।

// Ask on startup — the file waits, however late your page mounts
const f = await AppMint.getOpenedFile();   // null if opened normally
if (f) {
  if (f.name.endsWith('.gpx') || f.name.endsWith('.tcx')) {
    const xml = new DOMParser().parseFromString(f.text, 'text/xml');
    const points = xml.querySelectorAll('trkpt, Trackpoint');
    console.log('workout with ' + points.length + ' points');
  } else if (f.name.endsWith('.fit')) {
    // .fit is binary — a real File; parse its bytes
    parseFit(new Uint8Array(await f.file.arrayBuffer())); // e.g. fit-file-parser
  } else if (f.kind === 'video') {
    document.querySelector('video').src = f.url;   // streams from disk, seekable
  }
}

// A shared link or caption
const shared = JSON.parse(WebToApk.getSharedText() || 'null');
if (shared) console.log('shared:', shared.url || shared.text);

2ब्लूटूथ फ़िटनेस सेंसर जोड़ें (हार्ट रेट, स्पीड, कैडेंस…)#

विज़ार्ड में ब्लूटूथ अनुमति चालू करें और आपका ऐप मानक BLE सेंसर पेयर कर सकता है - हर मानक चेस्ट स्ट्रैप और बाइक पॉड एक ही आधिकारिक ब्लूटूथ प्रोफ़ाइल इस्तेमाल करता है, इसलिए हर ब्रांड के लिए अलग कोड नहीं चाहिए:

• हार्ट रेट स्ट्रैप → bpm
• स्पीड/कैडेंस पॉड → km/h + पैडल rpm
• पावर मीटर → वॉट
• रनिंग फ़ुटपॉड → पेस + कदम/मिनट
• हर सेंसर की बैटरी का स्तर

प्रक्रिया: स्कैन (15 सेकंड) → यूज़र डिवाइस चुनता है → कनेक्ट। फिर डेटा इवेंट के रूप में स्ट्रीम होता है। स्पीड के लिए आपके पहिये का साइज़ चाहिए; इसे एक बार सेट करें (डिफ़ॉल्ट 2096mm = 700x23c रोड व्हील)।

// 1. Scan — each found sensor fires a 'device' event:
window.addEventListener('appmint:ble', function (e) {
  const m = e.detail;
  if (m.kind === 'device') {
    // {address, name, sensors:['heart_rate','speed_cadence',...], rssi}
    addToPickerUI(m);
  }
  if (m.kind === 'data') {
    if (m.type === 'heart_rate')     showBpm(m.data.bpm);
    if (m.type === 'speed_cadence') {
      if (m.data.speedKmh)   showSpeed(m.data.speedKmh.toFixed(1));
      if (m.data.cadenceRpm) showCadence(Math.round(m.data.cadenceRpm));
    }
    if (m.type === 'power')   showWatts(m.data.watts);
    if (m.type === 'battery') showBattery(m.data.percent);
  }
  if (m.kind === 'error') console.warn('BLE:', m.error);
});

WebToApk.bleSetWheelCircumference(2105); // your wheel, in mm
WebToApk.bleStartScan();

// 2. When the user taps a device from your picker:
WebToApk.bleConnect(device.address);

// 3. Done training:
WebToApk.bleDisconnect();

3बैकग्राउंड जॉब और टिकाऊ ऑटो-सेव (WorkManager)#

आपका ऐप बंद होने पर JavaScript नहीं चल सकता - यह Android का नियम है, AppMint का नहीं। जो चल सकता है वह है एक नेटिव डिलीवरी जॉब जो आपका पेज OS को सौंप देता है। दो टूल:

1. workEnqueueOnline - टिकाऊ एक-बार की डिलीवरी। बेहतरीन ऑटो-सेव: डेटा सौंप दें और नेटवर्क मिलते ही वह आपके सर्वर पर POST हो जाता है, बैकऑफ़ के साथ दोबारा कोशिश करते हुए, और ऐप बंद होने या रीबूट के बाद भी बचा रहता है। वही जॉब id दोबारा इस्तेमाल करने पर पेंडिंग सेव सबसे नई स्थिति से बदल जाता है।

1. workSchedulePeriodic - बार-बार होने वाली नेटिव HTTP कॉल (सिंक ट्रिगर, हार्टबीट)। Android का न्यूनतम अंतराल 15 मिनट है; इससे छोटे मान अपने-आप 15 मिनट कर दिए जाते हैं।

दोनों तरीके आपका पेलोड आपके URL पर पहुँचाते हैं - सर्वर की तरफ़ वही सामान्य एंडपॉइंट है जो आपके पास पहले से है (Supabase एज फ़ंक्शन, आपका API…)।

// Durable auto-save: call this on every important change.
function autoSave(state) {
  WebToApk.workEnqueueOnline(
    'autosave',                          // same id → newest state wins
    'https://api.example.com/save',
    'POST',
    JSON.stringify({ 'Authorization': 'Bearer ' + token }),
    JSON.stringify(state)
  );
}

// Recurring sync every 30 minutes, even if the app is closed:
WebToApk.workSchedulePeriodic(
  'sync', 'https://api.example.com/sync', 'POST', '{}', '', 30
);

// Manage jobs:
WebToApk.workCancel('sync');
WebToApk.workList('req1');
window.addEventListener('appmint:work', function (e) {
  // {id, status:'enqueued'|'scheduled'|'cancelled'|'failed', reason?, intervalMinutes?}
  // or, for workList: {requestId, jobs:[{id, periodic, url, createdAt, pendingDelivery}]}
  console.log('work:', e.detail);
});

4चेकलिस्ट और आम गलतियाँ#

• फ़ाइलें: बिल्ड के समय टॉगल ON होना ज़रूरी है - यह आपके ऐप को Android के मैनिफ़ेस्ट में रजिस्टर करता है, जो इंस्टॉल के बाद बदला नहीं जा सकता। चालू करने के बाद दोबारा बिल्ड करें।

• BLE: बिल्ड के समय ब्लूटूथ अनुमति का टॉगल ON होना ज़रूरी है। पहला स्कैन यूज़र से रनटाइम अनुमति माँगता है (Android 12+: 'Nearby devices'; पुराने में: Location - BLE स्कैन के लिए यह Android का नियम है, आपका ऐप लोकेशन नहीं पढ़ता)।

• BLE: पेयर करना आपके ऐप में करें, Android की ब्लूटूथ सेटिंग्स में नहीं - BLE फ़िटनेस सेंसर क्लासिक पेयर्ड डिवाइस नहीं होते।

• बैकग्राउंड जॉब: 'मेरा पेज कोड चलाओ' के लिए पीरियॉडिक जॉब शेड्यूल न करें - यह आपके सर्वर तक HTTP पहुँचाता है। अगर आपको ऐप बंद होने पर डिवाइस पर प्रोसेसिंग चाहिए, तो डिलीवरी एंडपॉइंट इसी के लिए है।

• ऑटो-सेव: हमेशा वही SAME जॉब id। अलग-अलग id से कई पुराने सेव कतार में लग जाते हैं।