Pont JavaScript : les fonctions natives depuis votre site

Ce qui marche où

Les badges d'onglets, la navigation et les achats in-app viennent avec Shell V2, la coque native (en-tête, barre d'onglets, menu latéral) que vous activez dans le Shell Designer de votre projet ; les plugins de la bibliothèque marchent avec ou sans (sur iOS, la barre d'état seulement dans les apps plein écran). La biométrie aussi, sauf que dans une app iOS sans Shell V2 elle demande en plus l'un de ces plugins : Retour haptique, Avis dans l'app, Partage natif, Contrôle de l'écran, Stockage sécurisé, Infos de l'app, Navigateur intégré, Barre d'état ou Orientation de l'écran. Les fonctions natives sont ajoutées au moment du build : après en avoir activé une, lancez un nouveau build. Les changements de votre site apparaissent tout de suite dans l'app ; les changements natifs, non. Rien de tout cela n'existe dans l'Android Build (Web) (TWA), qui ouvre votre site dans Chrome : choisissez l'Android Build (Native) ou le build Android TV.

Déverrouillage biométrique

Demande à la personne qui tient le téléphone de prouver que c'est bien elle : empreinte, visage, ou code du téléphone en repli. Cela ne connecte personne : servez-vous-en pour déverrouiller une session que votre site a déjà, ou pour confirmer une action sensible. Activez Déverrouillage biométrique dans la bibliothèque de plugins de votre projet (activé par défaut), puis relancez un build. Sur iOS, il marche aussi sans Shell V2, à condition d'ajouter aussi l'un de ces plugins : Retour haptique, Avis dans l'app, Partage natif, Contrôle de l'écran, Stockage sécurisé, Infos de l'app, Navigateur intégré, Barre d'état ou Orientation de l'écran. L'app l'obtient à son prochain build.

• isAvailable()

  Une empreinte ou un visage est-il enregistré sur ce téléphone ? type vaut fingerprint, face, iris ou biometric sur Android, faceid ou touchid sur iOS.await window.saastostore.biometric.isAvailable(); // → { available: true, type: "fingerprint" } // → { available: false, type: "none" }

• authenticate(reason)

  Ouvre la fenêtre du système avec votre motif sous le nom de l'app. error contient le message du système quand la personne annule. Sur Android, il peut aussi valoir not_available (ni biométrie ni verrouillage d'écran) ou busy (une fenêtre est déjà ouverte).await window.saastostore.biometric.authenticate("Unlock your account"); // → { success: true, error: null } // → { success: false, error: "Authentication canceled" }

• Exemple

  const bio = await whenSaasToStore("biometric"); const check = await bio?.isAvailable(); if (check?.available) { const result = await bio.authenticate("Unlock your account"); if (result?.success) showAccount(); }

Plugins de la bibliothèque

Les plugins ci-dessous sont éteints tant que vous ne les ajoutez pas dans la bibliothèque de plugins de votre projet ; lancez ensuite un nouveau build. Ils marchent dans les builds Android natifs (Android Build (Native), Android TV) et dans les apps iOS, avec ou sans Shell V2 (sur iOS, la barre d'état seulement dans les apps plein écran). Ils ne sont pas dans l'Android Build (Web) (TWA) : window.saastostore n'y existe pas.

• Prêts dès la première ligne

  Leur API est posée avant le premier script de votre page, sur le domaine de l'app et ses sous-domaines, dans le cadre principal seulement : jamais dans une iframe ni sur un autre site.

• Des promesses qui ne rejettent jamais

  Chaque méthode renvoie une Promise qui ne rejette jamais. Quand l'appel échoue, elle vaut un objet avec un champ error : not_available, not_supported, invalid_argument, busy, timeout ou failed ; et null si l'app ne peut pas répondre. Hors de l'app, ou dans une app construite avant l'ajout du plugin, le plugin est simplement absent : vérifiez-le avant de l'appeler.const haptics = window.saastostore?.haptics; // undefined: normal browser, plugin not added, or app built before you added it if (haptics) { const r = await haptics.impact({ style: "light" }); if (r?.error) console.warn("haptics:", r.error); // never throws }

Retour haptique

De courtes vibrations qui confirment une touche, une réussite ou une erreur. Ce que ressent la personne dépend de son téléphone et de son réglage de retour haptique.

• impact, notification, selection, vibrate

  impact prend un style (light, medium par défaut, heavy), notification un type (success par défaut, warning, error) ; selection est un léger tic, pour un sélecteur. vibrate prend une duration de 1 à 1000 ms (300 par défaut) ; iOS ne sait pas régler la durée et joue un impact fort à la place. Une duration qui n'est pas un nombre de 1 à 1000 répond invalid_argument. Sur Android, impact, notification, selection et vibrate répondent not_available quand l'appareil ne joue rien (pas de vibreur, comme la plupart des tablettes et des TV, ou retour haptique désactivé) ; iOS répond ok: true dans ce cas.const haptics = window.saastostore?.haptics; await haptics?.impact({ style: "medium" }); // light | medium | heavy await haptics?.notification({ type: "success" }); // success | warning | error await haptics?.selection(); // a light tick await haptics?.vibrate({ duration: 200 }); // ms, 1 to 1000 // → { ok: true } // → { ok: false, error: "invalid_argument" } e.g. duration: 5000 // → { ok: false, error: "not_available" } Android: the device plays nothing

Avis dans l'app

Ouvre la fenêtre de notation du store sans quitter l'app. Le store décide si elle s'affiche et en limite la fréquence ; votre code ne sait jamais si un avis a été laissé. Elle n'apparaît que dans une app installée depuis Google Play ou l'App Store, jamais dans TestFlight.

• request()

  Appelez-la après une réussite (une commande livrée, un objectif atteint), pas comme seule action d'un bouton « Notez-nous » : la fenêtre peut ne pas s'afficher. error peut valoir not_available (pas de Google Play sur l'appareil), busy (une demande est déjà en cours), timeout ou failed. requested: true revient dès que la demande est passée au store, sans attendre la fermeture de la fenêtre. Sur Android, une deuxième demande pendant que la première fenêtre est encore ouverte répond busy.// after a success, never as the only action of a button const r = await window.saastostore?.appReview?.request(); // → { requested: true } handed to the store, which decides whether to show it // → { requested: false, error: "not_available" } // → { requested: false, error: "busy" } Android: a review window is still open

Partage natif

Ouvre le menu de partage du téléphone avec un texte, un lien, ou les deux. Texte et liens seulement, pas de fichier. Ce n'est pas Recevoir un partage, qui permet aux autres apps d'envoyer du contenu à la vôtre.

• share({ title, text, url })

  share est une fonction, pas un objet. Sans text ni url, il partage l'adresse de la page affichée. url doit être un lien http ou https : tout autre lien (file:, mailto:, javascript:…) répond invalid_argument. title est facultatif (l'objet d'un e-mail, le titre du menu quand le système en affiche un). shared: true signifie que le menu s'est ouvert, pas que quelque chose a été envoyé.const r = await window.saastostore?.share?.({ title: "Trip to Lisbon", // optional text: "Here is our itinerary", url: "https://example.com/trips/42", }); // → { shared: true } the share sheet opened // → { shared: false, error: "invalid_argument" } url not http or https // share() with neither text nor url shares the page shown // in a normal browser: navigator.share?.({ title, text, url })

Contrôle de l'écran

Gardez l'écran allumé et réglez sa luminosité, pour une recette, une carte d'embarquement ou un QR code à présenter. Les réglages valent tant que l'app est ouverte.

• keepAwake(on)

  true garde l'écran allumé tant que l'app est au premier plan ; false rend la main au téléphone.

• setBrightness(value), getBrightness()

  value va de 0 à 1 ; null revient à la luminosité du système. Sur Android, seule la fenêtre de l'app change. Sur iOS, c'est tout l'écran : l'app remet la luminosité d'origine quand elle passe en arrière-plan, et réapplique la vôtre à son retour. Les valeurs sont vérifiées, jamais converties : setBrightness prend null ou un nombre de 0 à 1, keepAwake un booléen (sans argument : true) ; tout le reste répond invalid_argument. Sur Android, tant que l'app n'a pas réglé la luminosité, getBrightness renvoie une approximation du réglage système.const screen = window.saastostore?.screen; await screen?.keepAwake(true); // → { ok: true } await screen?.setBrightness(1); // 0 to 1, e.g. to show a QR code await screen?.getBrightness(); // → { brightness: 1 } await screen?.setBrightness(null); // back to the system brightness await screen?.keepAwake(false); await screen?.setBrightness("1"); // → { ok: false, error: "invalid_argument" }

Stockage sécurisé

Un petit stockage clé-valeur chiffré par le téléphone, pour un jeton ou un secret dont votre site a besoin d'un lancement à l'autre. Sur Android, les valeurs sont chiffrées en AES-256-GCM avec une clé de l'Android Keystore qui ne quitte jamais l'appareil. Sur iOS, elles vont dans le Keychain, lisibles par cette app seulement, sur cet appareil seulement, après son premier déverrouillage.

• get, set, remove, keys, clear

  Les clés utilisent lettres, chiffres, point, tiret bas et tiret (1 à 128 caractères) ; les valeurs sont des chaînes de 64 Ko au plus : enregistrez un objet avec JSON.stringify. Rien n'est converti à votre place : une clé dans un autre format (comme auth:token), une valeur qui n'est pas une chaîne (undefined, un nombre, un objet) ou trop longue répond invalid_argument, et rien n'est enregistré.const vault = window.saastostore?.secureStorage; await vault?.set("refresh_token", token); // → { ok: true } const saved = await vault?.get("refresh_token"); // → { value: "…" }, or { value: null } when the key is missing await vault?.keys(); // → { keys: ["refresh_token"] } await vault?.remove("refresh_token"); // → { ok: true } await vault?.clear(); // e.g. at sign-out await vault?.set("session", JSON.stringify({ id, exp })); // objects: JSON.stringify await vault?.set("auth:token", undefined); // → { ok: false, error: "invalid_argument" } ":" in the key, value not a string

• Limites à connaître

  Sur iOS, le Keychain survit à la désinstallation de l'app : une réinstallation retrouve les anciennes valeurs. Appelez clear() à la déconnexion, et ne prenez pas un stockage vide pour une première installation. Sur Android, tout est effacé avec l'app et rien n'est jamais sauvegardé : une réinstallation, ou un nouveau téléphone, repart d'un stockage vide. Chaque site a son propre stockage, comme localStorage : www.exemple.com et exemple.com partagent le même, aide.exemple.com a le sien, et keys() / clear() ne voient que les clés du site qui appelle. Le JavaScript de votre page peut lire les valeurs : elles sont protégées sur le téléphone, pas contre un script injecté dans votre site.

Infos de l'app

La version et le numéro de build de l'app, la plateforme, la version du système et la langue du téléphone : pour votre page de réglages ou un message au support.

• get()

  build est une chaîne sur les deux plateformes. model est un nom de modèle générique (le modèle sur Android, « iPhone » sur iOS) : aucun identifiant d'appareil n'est renvoyé.await window.saastostore?.appInfo?.get(); // → { platform: "android", version: "1.4.0", build: "12", // packageName: "com.example.app", osVersion: "14", // language: "fr-FR", model: "Pixel 8" }

Navigateur intégré

Ouvre une page dans un onglet de navigateur par-dessus l'app : Custom Tabs sur Android (ou le navigateur par défaut), Safari View Controller sur iOS. Pour les pages hors de votre domaine : conditions, aide, site d'un partenaire.

• open(url)

  http et https seulement. La page tourne hors de votre app : elle n'a ni window.saastostore, ni le user agent SaasToStoreApp, ni la session de votre app. Laissez la connexion Google ou Apple à l'app, qui s'en charge déjà. error peut valoir invalid_argument, busy (iOS : une autre feuille est ouverte), not_available ou failed. Sur Android, un lien vers un site qui a sa propre app sur le téléphone (un site de vidéos ou un réseau social, ou votre propre domaine quand les deep links sont actifs) peut ouvrir cette app au lieu d'un onglet.const r = await window.saastostore?.browser?.open("https://example.com/terms"); // → { ok: true } // → { ok: false, error: "invalid_argument" } not http or https

Barre d'état

Accordez la barre d'état à votre page : icônes foncées sur une page claire, icônes claires sur une page sombre. Jusqu'à Android 14, la barre d'état est une bande au-dessus de la page, pas la page elle-même : appelez setColor avec la couleur de fond de votre page en même temps que setStyle. À partir d'Android 15 et sur iOS, la page passe sous la barre d'état : setStyle suffit, et la réponse not_supported de setColor peut être ignorée.

• setStyle(style)

  "light" pour une page claire (icônes foncées), "dark" pour une page sombre (icônes claires). Sur iOS avec Shell V2, la réponse est not_supported : la barre d'état suit l'en-tête natif.

• setColor(hex)

  Couleur de fond au format #RRGGBB, sur Android 14 et versions antérieures seulement. Android 15 et suivants dessinent les apps bord à bord, et iOS n'a pas de couleur de barre d'état : l'appel y répond not_supported.const bar = window.saastostore?.statusBar; // a light page: dark icons, and (Android 14 and earlier) a bar of the page color await bar?.setColor("#ffffff"); // → { ok: true } up to Android 14 await bar?.setStyle("light"); // → { ok: true } // a dark page: light icons await bar?.setColor("#101827"); await bar?.setStyle("dark"); // setColor → { ok: false, error: "not_supported" } Android 15+ and iOS: ignore it // setStyle → { ok: false, error: "not_supported" } iOS with Shell V2

Orientation de l'écran

Un réglage de build, sans JavaScript : ajoutez Orientation de l'écran dans la bibliothèque de plugins, choisissez Portrait ou Paysage, puis relancez un build. L'app reste dans cette orientation (sur Android, elle peut encore se retourner tête en bas).

Notifications locales

Des rappels programmés sur le téléphone par votre page, affichés à l'heure choisie même quand l'app est fermée : un rendez-vous, une séance qui commence, un panier abandonné. Rien ne part de votre site, aucun serveur n'intervient : ce n'est pas du push. La notification ouvre votre app, et votre page sait laquelle a été touchée.

• requestPermission() et checkPermission()

  Demandez une fois, depuis une action de l'utilisateur (un bouton « Me rappeler »), jamais au lancement : Android 13 et suivants et iOS affichent une fenêtre système (les Android plus anciens répondent granted). La réponse est { granted, status }, avec status granted, denied ou prompt. Après un refus, le système ne redemande plus : envoyez l'utilisateur dans les réglages de l'app. checkPermission() lit seulement l'état.

• schedule({ title, body, at | in, id, data })

  at est une date (millisecondes, ou ISO 8601 avec fuseau, ce que donne toISOString()) ou in un délai en secondes, jamais les deux ; sans l'un ni l'autre, la notification s'affiche tout de suite. La réponse est { scheduled: true, id, at }. Limites : titre 200 caractères, texte 1 000, data un objet JSON de 4 Ko, 64 rappels en attente, 366 jours à l'avance ; une date passée s'affiche tout de suite ; l'id d'un rappel en attente le remplace. Sans la permission, { scheduled: false, error: "not_allowed", status } : demandez-la d'abord. Sinon invalid_argument, too_many ou failed.const notif = window.saastostore?.localNotifications; // ask once, from a "Remind me" button, never at launch const p = await notif?.requestPermission(); // { granted: true, status: "granted" } const r = await notif?.schedule({ id: 42, // optional: the same id replaces a pending reminder title: "Your session starts in 10 minutes", body: "Tap to open the room", at: Date.now() + 50 * 60 * 1000, // or in: 3000 (seconds), or an ISO 8601 date data: { roomId: "a1" }, }); // r → { scheduled: true, id: 42, at: 1762000000000 } // without the permission: { scheduled: false, error: "not_allowed", status: "prompt" } window.addEventListener("s2s:localNotifications", (e) => { if (e.detail.type === "tap") openRoom(e.detail.data.roomId); }); const opened = await notif?.getLastOpened(); // { notification } once, then { notification: null } await notif?.cancel({ id: 42 });

• Appui, liste, annulation

  Un appui ouvre l'app sur votre page, qui reçoit un événement s2s:localNotifications sur window (detail.type "tap", avec id, title, body, at, data). Si l'app était fermée, l'événement part avant que votre page n'écoute : appelez getLastOpened() au démarrage de la page, il répond la notification une fois, puis null. getPending() liste les rappels à venir ; cancel({ id }) et cancelAll() les retirent, affichés compris.

• Heure et redémarrage

  Android affiche le rappel à quelques minutes près (alarme inexacte, sans la permission « Alarmes et rappels ») : juste pour un rendez-vous, pas pour un compte à rebours à la seconde. iOS est à l'heure. Les rappels survivent à un redémarrage du téléphone : Android les reprogramme au démarrage, iOS les garde. Sur Android, la notification porte l'icône de votre app et un canal « Notifications » que l'utilisateur peut couper dans les réglages du système.

Scanner QR et codes-barres

Lisez un QR code ou un code-barres avec l'appareil photo, depuis votre page : un billet, un produit, un lien à ouvrir. Sur Android, le lecteur est celui de Google (services Google Play), plein écran avec zoom automatique, et votre app ne demande aucune permission caméra. Sur iOS, l'app ouvre son propre lecteur, après la permission caméra.

• isAvailable()

  { available: true }, ou { available: false, reason } : no_play_services (Android sans services Google Play : Amazon Fire, Huawei), module_not_installed (Android : Google Play télécharge le lecteur une fois ; le téléchargement est demandé, réessayez plus tard), no_camera (iOS). Vérifiez-le avant d'afficher un bouton de scan.

• scan({ formats, prompt })

  Ouvre le lecteur et répond avec le premier code lu : { scanned: true, value, format }. formats limite ce qui est lu (tout par défaut) : qr, ean13, ean8, upca, upce, code128, code39, code93, itf, codabar, datamatrix, pdf417, aztec. prompt est le texte affiché au-dessus du cadre de visée sur iOS (200 caractères au plus ; Android affiche l'interface de Google). Fermé par l'utilisateur : { scanned: false, error: "cancelled" } ; sinon not_available, not_allowed, busy, invalid_argument ou failed.const scanner = window.saastostore?.barcode; const ok = await scanner?.isAvailable(); // { available: true } or { available: false, reason: "no_play_services" | "module_not_installed" | "no_camera" } const r = await scanner?.scan({ formats: ["qr"], prompt: "Scan your ticket" }); if (r?.scanned) openTicket(r.value); // { scanned: true, value: "...", format: "qr" } else if (r?.error !== "cancelled") showMessage(r?.error); // not_available, not_allowed, busy, invalid_argument, failed

• Permission

  Android : aucune, checkPermission() répond toujours granted. iOS : scan() demande l'appareil photo la première fois ; checkPermission() et requestPermission() permettent de demander depuis un bouton à vous, avec status granted, denied ou prompt. Après un refus, iOS ne redemande plus : envoyez l'utilisateur dans les réglages de l'app.

Téléchargement de fichiers

Les liens de téléchargement de votre site marchent dans l'app, sans code de votre côté : un lien avec l'attribut download, un fichier envoyé en pièce jointe, un export fabriqué dans la page (blob:, data:). Un fichier derrière une connexion marche aussi : l'app envoie ses cookies. Sur Android, le fichier va dans le dossier Téléchargements du téléphone, avec la notification du système. iOS n'a pas ce dossier : l'app ouvre l'aperçu du système, d'où l'utilisateur partage le fichier ou l'enregistre dans Fichiers.

• Liens

  Rien à coder pour les liens de votre domaine. Un PDF, ou un type de fichier que l'app ne sait pas afficher, est aussi traité comme un téléchargement. Un lien vers un autre domaine continue d'ouvrir le navigateur. Sur Android, un fichier produit par une requête POST n'est pas pris en charge : servez-le par un lien GET ou fabriquez-le dans la page. Sur Android 9 et avant, le fichier reste dans le dossier de l'app.

• download({ url, filename, open })

  Lance un téléchargement depuis votre code et répond quand il est fini : { downloaded: true, id, filename, mimeType, size }. url : http, https, blob: ou data:, relative ou absolue. filename remplace le nom, que l'app nettoie. open: true ouvre le fichier à la fin. En cas d'échec, { downloaded: false, error } : invalid_argument, not_available, busy (5 téléchargements à la fois) ou failed avec un reason comme http_404 ou too_large (100 Mo au plus pour blob: et data:).// Links need no code. From your own code: const files = window.saastostore?.downloads; const r = await files?.download({ url: "/invoices/42.pdf", filename: "invoice-42.pdf" }); if (r?.downloaded) await files.open({ id: r.id }); // { downloaded: true, id, filename, mimeType, size } else if (r) showMessage(r.reason ?? r.error); // invalid_argument, not_available, busy, failed window.addEventListener("s2s:downloads", (e) => { console.log(e.detail); // { state: "started" | "completed" | "failed", id, filename, source: "link" | "api", error? } });

• open({ id })

  Ouvre un fichier téléchargé depuis le lancement de l'app, avec l'id donné par download() ou par l'événement : { opened: true }. Sinon not_found, no_app (Android : aucune app n'ouvre ce type), busy (iOS : une feuille est déjà ouverte), invalid_argument ou failed.

• Événement

  s2s:downloads sur window, pour les liens et pour download() : e.detail = { state, id, filename, source, error }, avec state started, completed ou failed, et source link ou api. Il sert à montrer qu'un lien touché est en cours de téléchargement. isAvailable() répond { available: true }.

Calendrier

Ajoutez depuis votre page un événement au calendrier du téléphone : une réservation, un cours, un webinaire. L'app ouvre l'éditeur du calendrier lui-même, prérempli avec le titre, les dates, le lieu et les notes que vous donnez ; l'utilisateur vérifie et enregistre. Votre site ne lit ni n'écrit jamais dans le calendrier. Sur Android et sur iOS 17 et après, l'app ne demande aucune autorisation ; sur iOS 15 et 16, iOS demande l'accès au calendrier la première fois.

• addEvent({ title, start, end, location, notes })

  Ouvre l'éditeur. title est obligatoire (500 caractères au plus). start et end : une date et une heure ISO 8601 avec leur fuseau, des millisecondes epoch ou une Date ; sans end, l'événement dure une heure. location (1 000 caractères au plus) et notes (8 000) sont facultatifs. Android répond { ok: true, saved: null } dès que l'éditeur s'ouvre : il ne dit pas si l'événement a été enregistré. iOS répond à la fermeture de l'éditeur, avec saved true ou false.const cal = window.saastostore?.calendar; // from a button, never at launch const r = await cal?.addEvent({ title: "Product demo", start: "2026-11-20T09:00:00+01:00", // ISO 8601 with a time zone, epoch ms or a Date end: "2026-11-20T10:30:00+01:00", // optional: one hour after start location: "Lyon", notes: "Room 4, bring your badge", }); // Android → { ok: true, saved: null } (Android does not say whether it was saved) // iOS → { ok: true, saved: true | false } when the editor closes if (r && !r.ok) showMessage(r.error); // invalid_argument, not_available, busy, not_allowed // all day, 20 to 22 November (end included): await cal?.addEvent({ title: "Trade fair", start: "2026-11-20", end: "2026-11-22", allDay: true });

• Journées entières

  allDay: true, avec des jours comme start et end : "2026-11-20", ou une date dont on retient le jour local. end est le dernier jour, compris ; sans lui, l'événement dure un jour. Sans allDay, une date sans heure est refusée : donnez une heure et un fuseau.

• Erreurs

  { ok: false, error } : invalid_argument (pas de titre, une date illisible, une fin avant le début), not_available (aucune app de calendrier sur le téléphone), busy (iOS : un éditeur est déjà ouvert) ou not_allowed (iOS 15 et 16 : accès au calendrier refusé ; envoyez l'utilisateur vers les réglages de l'app). isAvailable() répond { available: false } sur un téléphone Android sans app de calendrier : cachez alors votre bouton. Ni répétition ni rappel dans cette version.

Scanner de documents

Numérisez des documents papier depuis votre page : une pièce d'identité, un ticket de caisse, un formulaire signé. Le scanner du téléphone s'ouvre, trouve les bords de la page et la redresse ; l'utilisateur peut reprendre une page avant de valider. Votre page reçoit les pages en images JPEG ou en un seul PDF, sous forme d'objets File prêts à envoyer. Sur Android, le scanner appartient aux services Google Play et votre app ne demande aucune autorisation caméra ; sur iOS, c'est le scanner d'Apple, et iOS demande l'accès à l'appareil photo la première fois.

• scan({ pages, format })

  Ouvre le scanner et répond { ok: true, format, pageCount, truncated, files }. format : jpeg (par défaut), un fichier par page (scan-1.jpg, scan-2.jpg…), ou pdf, un seul scan.pdf. pages : de 1 à 20, 10 par défaut. Sur Android, le scanner s'arrête à ce nombre ; sur iOS, l'utilisateur peut en numériser plus : les premières pages sont gardées et truncated vaut true. 32 Mo au plus par numérisation, sinon too_large.const scanner = window.saastostore?.documentScanner; const ok = await scanner?.isAvailable(); // { available: true } or { available: false, reason } // from a button: the phone's own scanner opens const r = await scanner?.scan({ pages: 5, format: "pdf" }); // pages 1 to 20 (10 by default), "jpeg" (default) or "pdf" if (r?.ok) { const body = new FormData(); r.files.forEach((f) => body.append("scan", f)); // File objects: scan.pdf, or scan-1.jpg, scan-2.jpg… await fetch("/api/documents", { method: "POST", body }); } else if (r && r.error !== "cancelled") showMessage(r.error); // busy, not_allowed, not_available, too_large, invalid_argument, failed

• isAvailable()

  { available: true }, ou { available: false, reason } : no_play_services (Android sans services Google Play : Amazon Fire, Huawei), unsupported_device (Android avec moins de 1,7 Go de mémoire, ou simulateur iOS), module_not_installed (Android : Google Play télécharge le scanner une fois ; le téléchargement est demandé, réessayez plus tard). Vérifiez-le avant d'afficher un bouton de numérisation.

• Erreurs

  { ok: false, error } : cancelled (fermé sans aucune page), busy (une numérisation est déjà ouverte), not_allowed (iOS : accès à l'appareil photo refusé ; envoyez l'utilisateur vers les réglages de l'app), not_available, too_large, invalid_argument (pages hors de 1 à 20, un format autre que jpeg ou pdf) ou failed. Sur Android, le scanner ne prend que des photos : l'import depuis la galerie est désactivé.

Contacts

Laissez l'utilisateur remplir un champ depuis ses contacts : un numéro pour inviter un ami, une adresse e-mail pour partager un fichier. L'app ouvre le sélecteur de contacts du téléphone ; l'utilisateur choisit un contact, puis un numéro ou une adresse. Votre site reçoit ce choix et rien d'autre : l'app ne lit jamais le carnet d'adresses et ne demande aucune autorisation, sur Android comme sur iOS.

• pick({ field })

  Ouvre le sélecteur et répond { ok: true, contact: { name, phones, emails } }. field dit ce qui revient : phone (par défaut), le numéro choisi, dans phones ; email, l'adresse choisie, dans emails ; name, le nom seul. Seuls les contacts qui ont un numéro (ou une adresse) peuvent être choisis. name vaut null pour un contact sans nom et est coupé à 500 caractères ; la liste reste vide quand la valeur choisie est vide ou dépasse 320 caractères : vérifiez-la avant de l'utiliser.const contacts = window.saastostore?.contacts; // from a button: the phone's own contact picker opens const r = await contacts?.pick({ field: "phone" }); // "phone" (default), "email" or "name" if (r?.ok && r.contact.phones.length) phoneInput.value = r.contact.phones[0]; // { name: "Ada Lovelace", phones: ["+33 6 12 34 56 78"], emails: [] } else if (r && r.error !== "cancelled") showMessage(r.error); // busy, not_available, invalid_argument, failed

• Erreurs

  { ok: false, error } : cancelled (fermé par l'utilisateur), busy (un sélecteur est déjà ouvert), not_available (Android : aucune app de contacts sur le téléphone), invalid_argument (un field autre que phone, email ou name) ou failed. isAvailable() répond toujours { available: true } sur iOS ; sur Android, { available: false } quand le téléphone n'a aucune app de contacts : cachez alors votre bouton.

Achats in-app (Android)

Les contenus numériques vendus dans une app Android doivent passer par la facturation Google Play. Le pont vend vos abonnements par ce biais, via RevenueCat. Activez Abonnements in-app (Google Play) dans la bibliothèque de plugins avec votre clé Android RevenueCat (goog_…) et votre entitlement, laissez Shell V2 activé, puis relancez un build. L'app iOS ne l'a pas encore : masquez-y votre bouton de passage à l'offre payante.

• Appels

  billing.identify(userId); // after sign-in, before any purchase billing.getStatus(); // is the subscription active? billing.purchase(productId); // opens the Google Play purchase sheet billing.restore(); // restore purchases

• Résultats : l'événement « s2s:billing »

  Chaque appel répond par un événement sur window ; event.detail.type indique lequel. Une error qui vaut cancelled signifie que la personne a fermé la fenêtre d'achat.identify_result { success, userId, error? } purchase_result { success, productId, isEntitled?, error? } restore_result { success, isEntitled, error? } status { isEntitled, entitlementId, expiresAt? }

• Exemple

  const billing = await whenSaasToStore("billing"); window.addEventListener("s2s:billing", (e) => { const d = e.detail; if (d.type === "identify_result" && d.success) billing.getStatus(); if (d.type === "status") setPremium(d.isEntitled); if (d.type === "purchase_result" && d.success) setPremium(d.isEntitled); }); if (billing?.isAvailable) billing.identify(currentUser.id); // after sign-in // your "Upgrade" button, inside the Android app: billing.purchase("premium_monthly");

Firebase Analytics

Envoyez vos événements à Google Analytics for Firebase, sur votre propre projet Firebase. Ajoutez le plugin, ajoutez vos fichiers Firebase dans son détail, puis lancez un nouveau build. Sans ces fichiers, le plugin reste hors de l'app : il ne tourne jamais sur un projet partagé avec d'autres apps. Rien n'est envoyé avant l'accord donné par votre site (setConsent, plus bas). L'app n'a pas d'identifiant publicitaire.

• logEvent({ name, params })

  Envoie un événement. name : 40 caractères au plus, lettres, chiffres et _, commence par une lettre, sans les préfixes firebase_, google_ et ga_. params : 25 valeurs au plus, chacune un texte, un nombre ou un booléen (envoyé en 1 ou 0). Un nom ou une valeur refusé répond { ok: false, error: "invalid_argument" } ; sinon { ok: true }.const analytics = window.saastostore?.firebaseAnalytics; // undefined: normal browser, plugin not added, or app built before you added it if (analytics) { await analytics.logEvent({ name: "purchase", params: { value: 39, currency: "EUR" } }); }

• setUserId({ id }), setUserProperty({ name, value })

  id : votre propre identifiant d'utilisateur, 256 caractères au plus, jamais une adresse e-mail. name d'une propriété : 24 caractères au plus, mêmes règles qu'un événement ; value : 36 caractères au plus. null efface la valeur.

• setConsent({ analytics, ads })

  Rien n'est collecté tant que votre site n'a pas appelé cette méthode avec analytics: true, pas même les événements que Firebase enregistre seul au lancement. Appelez-la quand le visiteur accepte, ou dès le chargement de votre page si vous n'avez pas besoin de consentement. Firebase garde la réponse sur ce téléphone d'un lancement à l'autre. Le stockage publicitaire et la personnalisation restent refusés jusqu'à ads: true. analytics: false arrête de nouveau toute collecte. Demander le consentement là où la loi l'exige reste à votre charge.// once the visitor has accepted (or at page load if you need no consent) await window.saastostore?.firebaseAnalytics?.setConsent({ analytics: true });

Google Tag Manager

Votre conteneur GTM tourne dans l'app comme sur le web : vos balises se déclenchent dans la page et rien ne change. Si votre app a le plugin Firebase Analytics, une balise de plus y recopie vos événements.

• Balise HTML personnalisée

  Créez une balise de type HTML personnalisé avec ce code :<script> (function () { var analytics = window.saastostore && window.saastostore.firebaseAnalytics; if (!analytics) return; // normal browser, or app built without the plugin analytics.logEvent({ name: {{Event}}, params: { page_path: {{Page Path}} } }); })(); </script>

• Déclencheur

  Utilisez un déclencheur Événement personnalisé qui liste les événements à recopier, par exemple purchase|sign_up avec Utiliser la correspondance d'expressions régulières. N'utilisez pas Toutes les pages : GTM envoie alors des noms comme gtm.js, qu'Analytics refuse.

• Noms d'événements

  40 caractères au plus : lettres, chiffres et tirets bas, en commençant par une lettre. Tout autre nom est refusé : l'appel répond { ok: false, error: "invalid_argument" } et la page n'est pas touchée.

• Seulement dans l'app

  Pour déclencher une balise uniquement dans l'app, ou l'en exclure, ajoutez une variable JavaScript personnalisé et utilisez-la dans les conditions du déclencheur :function () { return navigator.userAgent.indexOf("SaasToStoreApp") !== -1; }

• Consentement

  Le bandeau de consentement de votre site n'arrive pas seul jusqu'à Analytics. Appelez setConsent depuis une balise déclenchée une fois que le visiteur a répondu, avant le premier événement :<script> (function () { var analytics = window.saastostore && window.saastostore.firebaseAnalytics; if (analytics) analytics.setConsent({ analytics: true, ads: false }); })(); </script>