O que um código pode fazer
- Preencher um endereço e o segredo dele. Nas seções que você permitir: Saúde, Tempo de tela ou as duas. O usuário ainda pode desativar uma seção na página de pareamento.
- Nunca escolher tipos de dados nem uma agenda. Quais dados são enviados, e com que frequência, continua sendo escolha do usuário no celular. Um código não consegue começar a enviar a frequência cardíaca de alguém para algum lugar sem que a pessoa perceba.
- Nunca mexer em outros receptores. Todos os outros endereços mantêm o próprio segredo e os próprios cabeçalhos, e um endereço adicionado por pareamento começa sem cabeçalhos personalizados.
- Não salvar nada antes de Parear. A página de pareamento mostra o seu nome e o host para onde os dados vão, tirado do próprio endereço.
O link
Um código é um link https com tudo depois do #:
https://owen282000.github.io/life-dashboard-companion-app/pair#v=1&url=<address>&secret=<secret>&name=<name>
| Campo | Valor |
|---|---|
v | 1, a versão do formato. Obrigatório. |
url | O endereço do seu webhook, com no máximo 2048 caracteres, sem espaços e sem vírgula. Obrigatório. |
secret | O segredo de assinatura HMAC deste usuário, com no máximo 512 caracteres, sem espaços. Obrigatório. |
name | Como a página de pareamento chama o seu serviço, com até 64 caracteres. Opcional. |
sources | health_connect, screen_time ou os dois, separados por vírgula. Deixe de fora para aceitar os dois. |
Aplique a codificação por porcentagem em cada valor por inteiro, com o espaço como %20. O quote(value, safe="") do Python e o encodeURIComponent do JavaScript fazem isso; a codificação de formulário, que escreve o espaço como +, não faz. O segredo fica no fragmento de propósito: um navegador nunca envia a um servidor a parte depois do #, então, quando alguém escaneia o código sem ter o app instalado, a página de destino carrega, mas o segredo continua no celular da pessoa.
Monte um código em Python
import secrets
from urllib.parse import quote, urlencode
import segno
PAIR_PAGE = "https://owen282000.github.io/life-dashboard-companion-app/pair"
def pairing_link(webhook_url, secret, name=None, sources=None):
fields = {"v": "1", "url": webhook_url, "secret": secret}
if name:
fields["name"] = name
if sources:
fields["sources"] = ",".join(sources)
return PAIR_PAGE + "#" + urlencode(fields, quote_via=quote, safe="")
secret = secrets.token_urlsafe(32) # store this with the user
link = pairing_link("https://health.example.com/webhook/u/42", secret, name="Example Health")
segno.make(link, error="m").save("pairing.svg", scale=6, border=4)
Monte um código em Node.js
import crypto from "node:crypto";
import QRCode from "qrcode";
const PAIR_PAGE = "https://owen282000.github.io/life-dashboard-companion-app/pair";
function pairingLink(webhookUrl, secret, { name, sources } = {}) {
const fields = [["v", "1"], ["url", webhookUrl], ["secret", secret]];
if (name) fields.push(["name", name]);
if (sources) fields.push(["sources", sources.join(",")]);
return PAIR_PAGE + "#" + fields.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&");
}
const secret = crypto.randomBytes(32).toString("base64url"); // store this with the user
const link = pairingLink("https://health.example.com/webhook/u/42", secret, { name: "Example Health" });
const dataUrl = await QRCode.toDataURL(link, { errorCorrectionLevel: "M", margin: 4 });
Os dois produzem exatamente o vetor de teste conhecido que os testes do próprio app conferem, e que está na referência de pareamento. Use-o como teste unitário do seu gerador.
O que o usuário vê
Ele escaneia o seu código no app, em Escanear um código de pareamento, ou com a câmera do celular, que no Android abre o app direto. Uma página diz “Example Health quer receber seus dados em health.example.com”, com uma chave para cada seção e os outros endereços, que mantêm o próprio segredo. Nada é salvo até ele tocar em Parear.
O ping de teste depois de Parear
Logo depois de Parear, o app envia um ping de teste para o seu endereço, assinado com o segredo do código:
POST /webhook/u/42
Content-Type: application/json; charset=utf-8
X-Signature: sha256=<hex of HMAC-SHA256(secret, raw body)>
{
"test": true,
"message": "Test ping from Life Dashboard",
"timestamp": "2026-10-04T12:00:00Z",
"app_version": "1.29.0",
"source": "health_connect"
}
Confira a assinatura sobre o corpo bruto antes de interpretá-lo e responda com qualquer 2xx: o usuário vê “Conectado.” na página depois de Parear, ou uma mensagem curta que diz “ping de teste entregue” durante a configuração inicial do app. Responda 401 a uma assinatura errada, como em toda requisição depois dele. Um ping não traz dados, então é um bom momento para marcar o usuário como conectado, não algo para guardar. Toda sincronização depois dele usa o mesmo segredo e o mesmo payload, descrito no guia do webhook.
iPhone
O Life Dashboard para iPhone lê os mesmos códigos. Ele envia só o Apple Health, então um código precisa aceitar health_connect ou deixar sources de fora. O http:// sem criptografia só funciona ali para um endereço da rede de casa, então use https. A câmera do iPhone abre primeiro a página de destino, que passa o código para o app com um botão Open in the app.
Mantenha seguro
- Um segredo por usuário, vindo de um gerador aleatório criptográfico, com pelo menos 32 bytes.
- Mostre o código só para aquele usuário, depois que ele fizer login. Quem vê o código consegue assinar dados em nome dele.
- Nunca registre o link em logs. Ele contém o segredo.
- Deixe os usuários trocarem o segredo. Um segredo novo significa um código novo; ao escaneá-lo, o segredo antigo é substituído no celular.
Life Dashboard
Gere um código para um usuário de teste e escaneie com o app. A referência de pareamento traz todas as regras, o vetor de teste e as diferenças no iPhone.
€ 4,99 uma única vez no Google Play: o jeito fácil, com atualizações automáticas, e ainda apoia o desenvolvimento.
Ou de graça, o mesmo app com a mesma chave de assinatura: APK no GitHub · Obtainium · F‑Droid
Referência de pareamento Referência do payload
Os apps de código aberto que este guia usa, para Android e iPhone. Sem conta e sem nuvem. Mais sobre o app para Android e para iPhone.
Perguntas frequentes
Meus usuários precisam de uma conta no Life Dashboard?
Não. Não existe servidor nem conta do Life Dashboard. O celular envia direto para o endereço que está no seu código.
Um código pode escolher quais dados de saúde o meu serviço recebe?
Não. Um código só preenche o endereço e o segredo. O usuário escolhe os tipos de dados e a agenda no celular, e assim o consentimento continua com ele.
Posso receber o payload no meu próprio formato?
Não. Todo receptor recebe o mesmo JSON assinado, descrito por um JSON Schema, e o seu serviço o converte para o próprio modelo. É ter um único formato documentado que permite a qualquer receptor funcionar sem plugin.
E se o usuário escanear sem ter o app instalado?
O link abre uma página que diz onde baixar o app, para Android ou iPhone. O segredo do link nunca chega ao servidor dessa página.
