Sensores, arquivos e tarefas em segundo plano

1Receba arquivos, fotos, vídeos e links de outros apps#

Ative 'Receber compartilhamentos de outros apps' no assistente e marque o que seu app aceita - textos e links, arquivos de dados (FIT, GPX, TCX, CSV, JSON, XML…), fotos, vídeos, áudios, documentos. Seu app aparece em DOIS lugares, exatamente para esses tipos:

1. A folha 'Abrir com' do Android quando o usuário toca em um arquivo.
2. A folha de COMPARTILHAR / EXPORTAR que outros apps mostram - incluindo dispositivos esportivos que exportam arquivos de treino (.fit, .gpx, .tcx). A maioria dos apps de fitness exporta por Compartilhar, e por isso apps que só registram 'Abrir com' nunca aparecem ali.

Peça o arquivo com AppMint.getOpenedFile() - ele espera por você, por mais tarde que sua página inicie. f.kind é image, video, audio, document ou data. Formatos de texto (gpx, tcx, csv, json, xml…) chegam como um f.text pronto para uso; binários pequenos (.fit) como f.base64; todo arquivo de dados e documento como um File real em f.file. Fotos, vídeos e áudios chegam como f.url, um endereço de streaming para <video src> / <img src>, com f.getFile() quando você precisar dos bytes. Não há limite de tamanho. Um link ou legenda compartilhado é lido com 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);

2Pareie sensores fitness Bluetooth (frequência cardíaca, velocidade, cadência…)#

Ative a permissão de Bluetooth no assistente e seu app poderá parear sensores BLE padrão - toda cinta torácica e sensor de bicicleta compatível usa os mesmos perfis Bluetooth oficiais, então não é preciso código por marca:

• Cintas de frequência cardíaca → bpm
• Sensores de velocidade/cadência → km/h + rpm do pedal
• Medidores de potência → watts
• Sensores de corrida (footpods) → ritmo + passos/min
• O nível de bateria de cada sensor

Fluxo: buscar (15 s) → o usuário escolhe um dispositivo → conectar. Os dados então chegam como eventos. A velocidade precisa do tamanho da sua roda; defina uma vez (padrão 2096 mm = roda de estrada 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();

3Tarefas em segundo plano e salvamento automático durável (WorkManager)#

O JavaScript não consegue rodar com o app fechado - isso é do Android, não do AppMint. O que PODE rodar é uma tarefa de entrega nativa que sua página entrega ao sistema. Duas ferramentas:

1. workEnqueueOnline - entrega única e durável. Salvamento automático perfeito: entregue os dados e ele faz o POST para o seu servidor quando houver rede, tentando de novo com espera crescente, sobrevivendo a encerramentos do app e reinicializações. Reutilizar o mesmo id de tarefa substitui o salvamento pendente pelo estado mais recente.

1. workSchedulePeriodic - uma chamada HTTP nativa recorrente (gatilho de sincronização, heartbeat). O intervalo mínimo do Android é de 15 minutos; valores menores são ajustados para esse mínimo.

Ambos entregam SEU conteúdo para a SUA URL - o lado do servidor é um endpoint normal que você já tem (função edge do Supabase, sua 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);
});

4Checklist e erros comuns#

• Arquivos: a opção precisa estar ATIVADA na hora do build - ela registra seu app no manifest do Android, que não pode mudar depois da instalação. Recompile depois de ativar.

• BLE: a permissão de Bluetooth precisa estar ATIVADA na hora do build. A PRIMEIRA busca pede ao usuário a permissão em tempo de execução (Android 12+: 'Dispositivos por perto'; anteriores: Localização - essa é uma regra do Android para busca BLE, seu app não lê a localização).

• BLE: pareie no SEU app, não nas configurações de Bluetooth do Android - sensores fitness BLE não são dispositivos pareados clássicos.

• Tarefas em segundo plano: não agende uma tarefa periódica para 'rodar o código da minha página' - ela entrega HTTP ao seu servidor. Se você precisa de processamento no dispositivo com o app fechado, é para isso que serve o endpoint de entrega.

• Salvamento automático: sempre o MESMO id de tarefa. Ids diferentes enfileiram vários salvamentos desatualizados.