Stocker des données sur le téléphone : SecureStore, SQLite et mode hors ligne

Une application mobile range ses données locales à trois endroits selon leur nature : les secrets (jetons, clés) dans le stockage sécurisé du système avec expo-secure-store, les préférences dans un simple stockage clé-valeur, et les données structurées dans une base SQLite embarquée avec expo-sqlite. Ce chapitre explique où ranger quoi, écrit le coffre à jetons d'AppliFrais, crée sa base locale, puis construit le mode hors ligne : une file d'attente des frais saisis sans réseau, envoyée automatiquement au retour de la connexion.

Où ranger quoi

SecureStore : le trousseau du téléphone

expo-secure-store range des paires clé-valeur chiffrées :

• sur iOS, dans le trousseau (Keychain), le coffre du système qui garde aussi les mots de passe Wi-Fi ;
• sur Android, chiffrées avec une clé du Keystore, générée et conservée dans une zone matérielle protégée du téléphone, d'où elle ne peut pas être extraite.

npx expo install expo-secure-store

Le coffre à jetons d'AppliFrais, src/lib/jetons.ts, implémente l'interface CoffreJetons attendue par le client d'API :

import * as SecureStore from 'expo-secure-store';

import type { CoffreJetons } from './api';

const CLE = 'applifrais.rafraichissement';
const OPTIONS: SecureStore.SecureStoreOptions = {
  keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY, // iOS : jamais copié vers un autre appareil
};

export const coffreSecureStore: CoffreJetons = {
  lireRafraichissement: () => SecureStore.getItemAsync(CLE, OPTIONS),
  ecrireRafraichissement: (jeton) => SecureStore.setItemAsync(CLE, jeton, OPTIONS),
  effacer: () => SecureStore.deleteItemAsync(CLE, OPTIONS),
};

Trois fonctions suffisent : setItemAsync, getItemAsync (qui renvoie null si la clé n'existe pas) et deleteItemAsync. L'option keychainAccessible règle, sur iOS, quand la valeur est lisible : WHEN_UNLOCKED_THIS_DEVICE_ONLY la rend lisible seulement quand le téléphone est déverrouillé, et l'exclut des sauvegardes restaurées sur un autre appareil.

Les limites à connaître :

• La taille. Certaines versions d'iOS ont refusé des valeurs de plus de 2 048 octets environ. Un jeton tient sans peine ; un objet JSON de données, non.
• La désinstallation. Sur Android, les valeurs disparaissent avec l'application. Sur iOS, le trousseau peut les conserver après une désinstallation : une réinstallation retrouverait le jeton. Au premier lancement, une application soigneuse vérifie un indicateur dans le stockage ordinaire (effacé, lui, à la désinstallation) et vide SecureStore s'il est absent.
• La sauvegarde Android. Le module d'Expo configure la sauvegarde automatique d'Android pour exclure ses valeurs, qui seraient de toute façon indéchiffrables sur un autre téléphone (la clé du Keystore reste dans l'ancien).
• Le Web. SecureStore n'existe pas dans la version web de l'application.

Les préférences : un stockage clé-valeur

Pour une préférence sans enjeu de sécurité, comme le rappel de fin de mois activé ou non, un stockage clé-valeur simple suffit. expo-sqlite en fournit un, compatible avec l'API d'AsyncStorage, la bibliothèque historique de React Native :

import Storage from 'expo-sqlite/kv-store';

export async function memoriserRappels(actif: boolean) {
  await Storage.setItem('rappels', actif ? 'oui' : 'non');
}
export async function lireRappels(): Promise<boolean> {
  return (await Storage.getItem('rappels')) === 'oui';
}

Les valeurs sont des chaînes : pour un objet, JSON.stringify à l'écriture et JSON.parse à la lecture. @react-native-async-storage/async-storage fait la même chose avec la même API ; tu le croiseras dans beaucoup de projets existants.

SQLite : une vraie base dans l'application

SQLite est un moteur de base de données relationnelle sans serveur : toute la base tient dans un fichier, dans le dossier de l'application. C'est le SGBD le plus déployé au monde, présent dans chaque téléphone Android et iOS. Tu y écris le même SQL que sur MySQL, à quelques différences près (cours SQL).

npx expo install expo-sqlite

La base locale d'AppliFrais, src/lib/db.ts, a deux tables : la file d'attente des frais saisis hors ligne, et un journal des tentatives de déverrouillage biométrique (chapitre 9).

import * as SQLite from 'expo-sqlite';

import type { Frais } from './validation';

export type FraisEnAttente = Frais & { cle: string; idFiche: number; photo: string | null };

let base: SQLite.SQLiteDatabase | null = null;

export async function ouvrirBase(): Promise<SQLite.SQLiteDatabase> {
  if (base) return base;
  base = await SQLite.openDatabaseAsync('applifrais.db');
  await migrer(base);
  return base;
}

// PRAGMA user_version : un entier rangé dans le fichier, qui dit quelle version du schéma il contient.
async function migrer(db: SQLite.SQLiteDatabase) {
  const ligne = await db.getFirstAsync<{ user_version: number }>('PRAGMA user_version');
  const version = ligne?.user_version ?? 0;
  if (version < 1) {
    await db.execAsync(`
      CREATE TABLE IF NOT EXISTS frais_en_attente (
        cle      TEXT PRIMARY KEY,
        id_fiche INTEGER NOT NULL,
        date     TEXT NOT NULL,
        libelle  TEXT NOT NULL,
        montant  REAL NOT NULL CHECK (montant > 0),
        photo    TEXT,
        cree_le  TEXT NOT NULL DEFAULT (datetime('now'))
      );
      CREATE TABLE IF NOT EXISTS journal (
        id         INTEGER PRIMARY KEY AUTOINCREMENT,
        horodatage TEXT NOT NULL DEFAULT (datetime('now')),
        type       TEXT NOT NULL,
        resultat   TEXT NOT NULL,
        message    TEXT
      );
      PRAGMA user_version = 1;
    `);
  }
}

export async function mettreEnAttente(idFiche: number, frais: Frais, cle: string, photo: string | null) {
  const db = await ouvrirBase();
  await db.runAsync(
    'INSERT INTO frais_en_attente (cle, id_fiche, date, libelle, montant, photo) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (cle) DO NOTHING',
    [cle, idFiche, frais.date, frais.libelle, frais.montant, photo],
  );
}

export async function lireEnAttente(): Promise<FraisEnAttente[]> {
  const db = await ouvrirBase();
  return db.getAllAsync<FraisEnAttente>(
    'SELECT cle, id_fiche AS idFiche, date, libelle, montant, photo FROM frais_en_attente ORDER BY rowid',
  );
}

export async function retirerDeLAttente(cle: string) {
  const db = await ouvrirBase();
  await db.runAsync('DELETE FROM frais_en_attente WHERE cle = ?', [cle]);
}

export async function journaliser(type: string, resultat: 'Succes' | 'Echec', message: string) {
  const db = await ouvrirBase();
  await db.runAsync('INSERT INTO journal (type, resultat, message) VALUES (?, ?, ?)', [type, resultat, message]);
}

export async function viderDonneesLocales() {
  const db = await ouvrirBase();
  await db.execAsync('DELETE FROM frais_en_attente; DELETE FROM journal;');
}

Les fonctions d'expo-sqlite :

Ce qu'il faut retenir de ce fichier :

• Les requêtes sont préparées : les valeurs passent par des ? et un tableau de paramètres, jamais par concaténation. Une base locale s'injecte comme une base serveur, et le sujet de cybersécurité SLAM de 2024 (alors E6, aujourd'hui E7) demandait justement d'écrire une insertion paramétrée dans une table de journal SQLite sur Android (requêtes préparées). execAsync ne prend pas de paramètres : il est réservé au SQL fixe, comme le schéma.
• Le schéma est versionné. PRAGMA user_version est un entier stocké dans le fichier de base, 0 à la création. La migration crée les tables puis passe la version à 1. Pour ajouter une colonne dans une prochaine version de l'application, tu ajouteras un bloc if (version < 2) { … ALTER TABLE … ; PRAGMA user_version = 2; }. Les téléphones qui ont déjà la version 1 n'exécuteront que ce bloc, sans perdre leurs données.
• ON CONFLICT (cle) DO NOTHING ignore un frais déjà en attente avec la même clé d'idempotence. N'utilise pas INSERT OR IGNORE à la place : en SQLite, OR IGNORE ignore aussi les violations de CHECK et de NOT NULL. Un frais à montant nul serait silencieusement jeté au lieu de provoquer une erreur.
• ORDER BY rowid rend les frais dans l'ordre d'insertion. datetime('now') n'a qu'une précision d'une seconde, et deux frais saisis dans la même seconde n'auraient pas d'ordre garanti par cree_le. Ces dates sont d'ailleurs en UTC.
• SQLite est souple sur les types : une colonne REAL accepte une chaîne si on la lui donne. Les contraintes NOT NULL et CHECK et la validation de l'application compensent.

Le mode hors ligne : une file d'attente

Lucas saisit ses frais dans le train, en zone blanche. Sans précaution, chaque enregistrement échoue avec une ErreurReseau, et il doit tout ressaisir plus tard. L'application adopte une stratégie simple et robuste : la file d'attente.

1. Lucas enregistre un frais. L'application tente l'envoi à l'API.
2. En cas d'ErreurReseau, elle range le frais dans la table frais_en_attente, avec sa clé d'idempotence, et revient au détail de la fiche comme si de rien n'était.
3. Quand le réseau revient, ou quand l'application repasse au premier plan, elle envoie les frais en attente, dans l'ordre, chacun avec sa clé d'origine.
4. Chaque frais accepté (ou définitivement refusé) est retiré de la file ; au premier échec réseau, l'envoi s'arrête et reprendra plus tard.

La synchronisation, src/lib/synchro.ts, ne dépend ni de SQLite ni du réseau : elle reçoit le client d'API et un « dépôt » qui sait lire et retirer les frais en attente. On peut ainsi la tester avec des doublures (chapitre 11).

import { ErreurApi, type Api } from './api';
import type { FraisEnAttente } from './db';

type Depot = {
  lire: () => Promise<FraisEnAttente[]>;
  retirer: (cle: string) => Promise<void>;
};
type Bilan = { envoyes: number; refuses: { frais: FraisEnAttente; raison: string }[] };

// Renvoyer la même requête donnerait le même refus : inutile de réessayer.
const REFUS_DEFINITIFS = [400, 404, 409, 413, 415, 422];

// Envoie les frais saisis hors ligne, dans l'ordre, avec leur clé d'idempotence d'origine.
export async function synchroniser(
  api: Pick<Api, 'ajouterFrais' | 'envoyerJustificatif'>,
  depot: Depot,
  formulaire: (uri: string) => FormData,
): Promise<Bilan> {
  const bilan: Bilan = { envoyes: 0, refuses: [] };
  for (const f of await depot.lire()) {
    try {
      const cree = await api.ajouterFrais(f.idFiche, { date: f.date, libelle: f.libelle, montant: f.montant }, f.cle);
      if (f.photo) await api.envoyerJustificatif(cree.id, formulaire(f.photo));
      await depot.retirer(f.cle);
      bilan.envoyes++;
    } catch (e) {
      const definitif = e instanceof ErreurApi && REFUS_DEFINITIFS.includes(e.status)
        && !e.type.endsWith('/requete-en-cours'); // 409 de la clé d'idempotence : la 1re requête n'a pas fini
      if (!definitif) break; // réseau coupé, session expirée, serveur en panne : on réessaiera plus tard
      await depot.retirer(f.cle);
      bilan.refuses.push({ frais: f, raison: (e as Error).message }); // l'écran les affiche à l'utilisateur
    }
  }
  return bilan;
}

La distinction entre les erreurs est le cœur de l'algorithme :

Réessayer un refus définitif ne servirait à rien : la file resterait bloquée sur ce frais pour toujours. Le jeter en silence ferait perdre une dépense à Lucas : le bilan renvoie donc la liste des refus, que l'écran affiche. Et la clé d'idempotence couvre le cas le plus sournois : si le frais est arrivé à l'API mais que la réponse s'est perdue, le renvoi ne crée pas de doublon.

Détecter le retour du réseau

Le module expo-network donne l'état de la connexion, avec un hook qui se met à jour tout seul :

npx expo install expo-network

Le hook useSynchroAuto, dans src/lib/useSynchroAuto.ts, lance la synchronisation quand Internet redevient joignable et chaque fois que l'application repasse au premier plan :

import * as Network from 'expo-network';
import { useEffect } from 'react';
import { AppState } from 'react-native';

import { formulaireJustificatif } from './appareil';
import { api } from './client';
import { lireEnAttente, retirerDeLAttente } from './db';
import { synchroniser } from './synchro';

// Envoie la file d'attente quand le réseau revient et quand l'application repasse au premier plan.
export function useSynchroAuto(actif: boolean) {
  const reseau = Network.useNetworkState();

  useEffect(() => {
    if (!actif || !reseau.isInternetReachable) return;
    const envoyer = () =>
      synchroniser(api, { lire: lireEnAttente, retirer: retirerDeLAttente }, formulaireJustificatif).catch(() => undefined);
    envoyer();
    const abonnement = AppState.addEventListener('change', (etat) => {
      if (etat === 'active') envoyer();
    });
    return () => abonnement.remove();
  }, [actif, reseau.isInternetReachable]);
}

Il est appelé dans le composant Navigation du layout racine, avant le return null du chargement (un hook ne s'appelle jamais après un return conditionnel) :

const { etat } = useSession();
useSynchroAuto(etat === 'connecte'); // envoie les frais saisis hors ligne dès que possible

isInternetReachable est plus fiable que isConnected : un téléphone peut être connecté à un Wi-Fi d'hôtel qui attend une page de connexion, sans accès réel à Internet. AppState signale les passages entre premier plan ('active') et arrière-plan ('background'). Le profil affiche en plus le nombre de frais en attente et un bouton « Envoyer maintenant » qui appelle la même fonction.

Effacer les données à la déconnexion

Le téléphone d'un visiteur peut être perdu, prêté, ou remis à un collègue. À la déconnexion, l'application efface tout ce qu'elle a stocké : le jeton dans SecureStore (fait par api.deconnexion), et les tables locales.

async function seDeconnecter() {
  await viderDonneesLocales(); // rien ne doit rester sur un téléphone prêté ou perdu
  await deconnexion();
}

Avant d'effacer une file d'attente non vide, une application soignée prévient : « 2 frais n'ont pas encore été envoyés. Te déconnecter les supprimera. » C'est aussi une application concrète du principe de minimisation du RGPD : ne garder sur l'appareil que ce qui est nécessaire, et pas plus longtemps que nécessaire (les principes du RGPD).