Capteurs, fichiers et tâches en arrière-plan

1Recevoir des fichiers, photos, vidéos et liens d'autres applications#

Activez « Recevoir les partages d'autres applications » dans l'assistant et cochez ce que votre application accepte : texte et liens, fichiers de données (FIT, GPX, TCX, CSV, JSON, XML…), photos, vidéos, audio, documents. Votre application apparaît à DEUX endroits, pour exactement ces types :

1. La feuille « Ouvrir avec » d'Android quand un utilisateur appuie sur un fichier.
2. La feuille PARTAGER / EXPORTER que d'autres applications affichent, y compris les appareils de sport qui exportent des fichiers d'entraînement (.fit, .gpx, .tcx). La plupart des applications de fitness exportent via Partager, c'est pourquoi les applications qui n'enregistrent que « Ouvrir avec » n'y apparaissent jamais.

Demandez le fichier avec AppMint.getOpenedFile() : il vous attend, même si votre page démarre tard. f.kind vaut image, video, audio, document ou data. Les formats texte (gpx, tcx, csv, json, xml…) arrivent sous forme de f.text prêt à l'emploi ; les petits binaires (.fit) sous forme de f.base64 ; chaque fichier de données et document sous forme de vrai File dans f.file. Les photos, vidéos et audio arrivent sous forme de f.url, une adresse diffusable pour <video src> / <img src>, avec f.getFile() quand vous avez besoin des octets. Il n'y a pas de limite de taille. Un lien ou une légende partagés se lisent avec 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);

2Associez des capteurs de fitness Bluetooth (fréquence cardiaque, vitesse, cadence…)#

Activez l'autorisation Bluetooth dans l'assistant et votre application peut associer des capteurs BLE standard : toutes les ceintures cardiaques et capteurs de vélo conformes utilisent les mêmes profils Bluetooth officiels, donc aucun code par marque n'est nécessaire :

• Ceintures cardiaques → bpm
• Capteurs de vitesse/cadence → km/h + tr/min de pédalage
• Capteurs de puissance → watts
• Capteurs de course à pied → allure + pas/min
• Le niveau de batterie de chaque capteur

Déroulement : recherche (15 s) → l'utilisateur choisit un appareil → connexion. Les données arrivent ensuite en flux d'événements. La vitesse a besoin de la taille de votre roue ; réglez-la une fois (par défaut 2096 mm = roue de route 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();

3Tâches en arrière-plan et sauvegarde automatique durable (WorkManager)#

JavaScript ne peut pas s'exécuter quand votre application est fermée : c'est Android, pas AppMint. Ce qui PEUT s'exécuter, c'est une tâche d'envoi native que votre page confie au système. Deux outils :

1. workEnqueueOnline : envoi unique durable. Sauvegarde automatique parfaite : confiez les données et elles sont envoyées en POST à votre serveur quand il y a du réseau, avec nouvelles tentatives espacées, et survivent aux arrêts de l'application et aux redémarrages. Réutiliser le même id de tâche remplace la sauvegarde en attente par l'état le plus récent.

1. workSchedulePeriodic : un appel HTTP natif récurrent (déclencheur de synchronisation, signal de vie). L'intervalle minimal d'Android est de 15 minutes ; les valeurs plus courtes sont ramenées à cette limite.

Les deux envoient VOTRE charge utile à VOTRE URL : le côté serveur est un point de terminaison ordinaire que vous avez déjà (fonction edge Supabase, votre 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);
});

4Liste de contrôle et erreurs courantes#

• Fichiers : l'option doit être ACTIVÉE à la compilation : elle enregistre votre application dans le manifeste d'Android, qui ne peut plus changer après l'installation. Recompilez après l'avoir activée.

• BLE : l'option d'autorisation Bluetooth doit être ACTIVÉE à la compilation. La PREMIÈRE recherche demande à l'utilisateur l'autorisation d'exécution (Android 12+ : « Appareils à proximité » ; avant : Localisation, c'est une règle d'Android pour la recherche BLE, votre application ne lit pas la localisation).

• BLE : associez dans VOTRE application, pas dans les paramètres Bluetooth d'Android : les capteurs de fitness BLE ne sont pas des appareils Bluetooth classiques associés.

• Tâches en arrière-plan : ne programmez pas une tâche périodique pour « exécuter le code de ma page » : elle envoie du HTTP à votre serveur. Si vous avez besoin d'un traitement sur l'appareil application fermée, c'est le rôle du point de terminaison d'envoi.

• Sauvegarde automatique : toujours le MÊME id de tâche. Des ids différents empilent plusieurs sauvegardes périmées.