Sideloading d'Applications

Le sideloading vous permet d'installer des mini-programmes en dehors du registre officiel de l'App Store. C'est le workflow principal pendant le développement et aussi comment les utilisateurs installent des applications partagées directement par les développeurs.

Il y a trois méthodes de sideloading :

Méthode	Entrée	Idéal Pour
Installation par URL	URL du manifeste	Applications hébergées, développement avec serveur local
Upload HTML	Fichier `.html` unique	Prototypage rapide, applications mono-fichier
Bundle .ais	Fichier ZIP (extension `.ais`)	Applications multi-fichiers, distribution hors-ligne

Les trois méthodes sont disponibles dans la section Sideload du panneau Apps.

Installation par URL

La façon standard d'installer un mini-programme depuis une source hébergée.

Comment Ça Fonctionne

Vous fournissez une URL pointant vers un fichier manifest.json
La plateforme récupère et valide le manifeste
Le fichier HTML d'entrée est récupéré depuis {base_url}{entry}
Une boîte de dialogue de permission affiche le nom de l'application, sa description et les permissions demandées
Sur approbation, le manifeste et le HTML en cache sont stockés dans IndexedDB
L'application apparaît dans la grille des applications installées

Étapes

Ouvrez le panneau Apps (cliquez sur l'icône apps dans la barre latérale gauche)
Défilez jusqu'à la section Sideload
Collez l'URL du manifeste dans le champ de texte :
```
https://example.com/my-app/manifest.json
```
Cliquez sur Install
Passez en revue les permissions et cliquez sur Allow

Développement avec Localhost

Pendant le développement, servez votre application localement et installez depuis localhost :

cd my-app
python3 -m http.server 8080

Puis installez depuis : http://localhost:8080/manifest.json

astuce

La plupart des serveurs HTTP locaux servent les fichiers avec des en-têtes CORS permissives par défaut. Si vous obtenez des erreurs "Failed to fetch manifest", assurez-vous que votre serveur inclut Access-Control-Allow-Origin: * dans ses réponses.

Mettre à Jour une Application Sideloadee

La plateforme met en cache le HTML d'entrée au moment de l'installation. Pour prendre en compte les changements de code :

Désinstallez l'application (cliquez sur le bouton X sur la carte de l'application)
Réinstallez depuis la même URL

Il n'y a pas de mécanisme de mise à jour automatique pour les applications sideloadées. Les applications du registre vérifient les mises à jour en utilisant la comparaison de version pendant le cycle de rafraîchissement du registre.

Upload HTML

La façon la plus rapide de tester un mini-programme. Uploadez un seul fichier HTML et la plateforme crée un manifeste synthétique automatiquement.

Comment Ça Fonctionne

Vous sélectionnez un fichier .html ou .htm depuis votre ordinateur
La plateforme lit le contenu du fichier (max 5 Mo)
Un manifeste synthétique est généré :
- name : dérivé du nom de fichier (minuscules, tirets, max 64 caractères)
- version : 1.0.0
- entry : index.html
- base_url : local://
- permissions : ["storage"] (minimal)
- description : "Sideloaded from {filename}"
Une boîte de dialogue de permission est affichée
Le HTML est mis en cache comme contenu d'entrée

Étapes

Ouvrez le panneau Apps
Dans la section Sideload, cliquez sur Upload App
Sélectionnez votre fichier .html
Passez en revue les permissions et cliquez sur Allow

Limitations

Fichier unique uniquement — Les CSS, JS et images externes référencés par des URLs relatifs ne se chargeront pas car l'iframe a une origine nulle et base_url est défini sur local://
Permissions minimales — Le manifeste synthétique accorde uniquement storage. Si votre application a besoin de chat:read ou d'autres permissions, utilisez l'Installation par URL ou un bundle .ais à la place
5 Mo max — Les fichiers de plus de 5 Mo sont rejetés
Pas de personnalisation du manifeste — Vous ne pouvez pas définir une description, icône ou permissions personnalisées

info

L'Upload HTML est conçu pour le prototypage rapide. Pour les applications qui nécessitent plusieurs fichiers ou des permissions spécifiques, utilisez un bundle .ais ou l'Installation par URL.

Faire Fonctionner les Applications Mono-Fichier

Pour tirer le meilleur parti de l'Upload HTML, gardez tout en ligne dans votre HTML :

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <style>
      /* Tout le CSS en ligne ici */
      body {
        font-family: system-ui;
        padding: 16px;
        color: #e0e0e0;
        background: #1a1a2e;
      }
    </style>
  </head>
  <body>
    <h1>Mon Application</h1>
    <script>
      // Tout le JavaScript en ligne ici
      ais.ready(function () {
        ais.ui.toast("Application chargée !");
      });
    </script>
  </body>
</html>

Les images peuvent être intégrées en tant qu'URIs de données :

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." />

Bundle .ais

Un bundle .ais est une archive ZIP standard avec une extension de fichier .ais. Il contient le manifeste, le HTML d'entrée et toutes les ressources. La plateforme extrait le ZIP et intègre toutes les ressources référencées dans un seul document HTML au moment de l'installation.

Comment Ça Fonctionne

Vous uploadez un fichier .ais (max 50 Mo)
La plateforme analyse le ZIP en utilisant DecompressionStream natif
manifest.json est extrait et validé depuis la racine du ZIP
Le fichier HTML d'entrée (référencé par entry dans le manifeste) est extrait
Tous les autres fichiers dans le ZIP sont disponibles comme ressources à intégrer
L'intégration des ressources transforme le HTML :
- <link rel="stylesheet" href="style.css"> devient <style>{contenu CSS}</style>
- <script src="app.js"></script> devient <script>{contenu JS}</script>
- <img src="icon.png"> devient <img src="data:image/png;base64,{base64}">
- url(bg.png) dans les styles en ligne devient url(data:image/png;base64,...)
La boîte de dialogue de permission affiche les permissions du manifeste
Le HTML intégré est mis en cache dans IndexedDB

Structure du Bundle

my-app.ais (archive ZIP)
  |-- manifest.json      (requis, à la racine)
  |-- index.html         (requis, référencé par "entry" du manifeste)
  |-- style.css          (optionnel, intégré dans <style>)
  |-- app.js             (optionnel, intégré dans <script>)
  |-- icon.png           (optionnel, intégré comme data URI)
  |-- images/
  |     |-- logo.svg     (optionnel, intégré comme data URI)
  |-- fonts/
        |-- custom.woff2 (optionnel, intégré comme data URI)

Créer un Bundle

# Naviguez vers le répertoire de votre application
cd my-app

# Vérifiez vos fichiers
ls
# manifest.json  index.html  style.css  app.js  icon.png

# Créez le bundle
zip -r ../my-app.ais manifest.json index.html style.css app.js icon.png

Ou zippez tout le répertoire :

cd my-app
zip -r ../my-app.ais .

attention

Le manifest.json doit être à la racine du ZIP, pas dans un sous-répertoire. Si votre ZIP a une structure comme my-app/manifest.json, la plateforme ne le trouvera pas.

Ce Qui Est Intégré

L'intégrateur de ressources traite le HTML d'entrée et remplace les références relatives par du contenu en ligne :

Pattern	Remplacement
`<link rel="stylesheet" href="X">`	`<style>{contenu de X}</style>`
`<script src="X"></script>`	`<script>{contenu de X}</script>`
`<img src="X">`	`<img src="data:{mime};base64,{data}">`
`<audio src="X">`	`<audio src="data:{mime};base64,{data}">`
`<video src="X">`	`<video src="data:{mime};base64,{data}">`
`<source src="X">`	`<source src="data:{mime};base64,{data}">`
`url(X)` dans les styles en ligne	`url(data:{mime};base64,{data})`

Les références qui commencent par data:, http://, https:// ou // sont laissées inchangées — seuls les chemins relatifs sont intégrés.

Types MIME Supportés

La plateforme détecte les types MIME à partir des extensions de fichier :

Extension	Type MIME
`.css`	`text/css`
`.js`, `.mjs`	`text/javascript`
`.json`	`application/json`
`.png`	`image/png`
`.jpg`, `.jpeg`	`image/jpeg`
`.gif`	`image/gif`
`.svg`	`image/svg+xml`
`.webp`	`image/webp`
`.ico`	`image/x-icon`
`.woff`	`font/woff`
`.woff2`	`font/woff2`
`.ttf`	`font/ttf`
`.mp3`	`audio/mpeg`
`.mp4`	`video/mp4`
`.webm`	`video/webm`
`.ogg`	`audio/ogg`
`.wav`	`audio/wav`

Exemple : Bundle d'Application Multi-Fichiers

manifest.json :

{
  "name": "dashboard",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "title": "Dashboard",
  "description": "Chat analytics dashboard",
  "entry": "index.html",
  "base_url": "local://",
  "permissions": ["storage", "chat:read", "auth:read", "ui:toast"]
}

index.html :

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <h1>Dashboard</h1>
    <img src="logo.svg" alt="Logo" width="64" />
    <div id="stats"></div>
    <script src="app.js"></script>
  </body>
</html>

style.css :

body {
  font-family: system-ui;
  padding: 16px;
  color: #e0e0e0;
  background: #1a1a2e;
}
h1 {
  font-size: 22px;
}
#stats {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 12px;
}

app.js :

ais.ready(async function () {
  var history = await ais.chat.getHistory(100);
  document.getElementById("stats").textContent = history.length + " messages";
});

Après l'installation du bundle, la plateforme produit un HTML intégré unique :

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <style>
      body {
        font-family: system-ui;
        padding: 16px;
        color: #e0e0e0;
        background: #1a1a2e;
      }
      h1 {
        font-size: 22px;
      }
      #stats {
        display: grid;
        grid-template-columns: repeat(3, 1fr);
        gap: 12px;
      }
    </style>
  </head>
  <body>
    <h1>Dashboard</h1>
    <img src="data:image/svg+xml;base64,..." alt="Logo" width="64" />
    <div id="stats"></div>
    <script>
      ais.ready(async function () {
        var history = await ais.chat.getHistory(100);
        document.getElementById("stats").textContent =
          history.length + " messages";
      });
    </script>
  </body>
</html>

Limites de Taille de Fichier

Méthode	Taille Max
Upload HTML	5 Mo
Bundle .ais	50 Mo
Installation par URL	Pas de limite stricte (contrainte par la mémoire du navigateur)

avertissement

Les bundles volumineux avec beaucoup d'images ou de fichiers média intégrés peuvent entraîner une très grande chaîne HTML en cache dans IndexedDB. Gardez les bundles légers — compressez les images avant de les inclure, et envisagez d'utiliser des URLs externes pour les ressources média volumineuses.

Sécurité

Les applications sideloadées obtiennent exactement le même bac à sable que les applications du registre :

sandbox="allow-scripts allow-forms" (origine nulle)
Pas d'accès au DOM parent, localStorage ou cookies
Communication exclusivement via le pont postMessage window.ais
Permissions appliquées par la plateforme hôte (pas l'iframe)

La seule différence avec les applications du registre est l'absence de badge de confiance (Community, AI Verified ou Verified) dans la grille d'applications. Les applications sideloadées n'ont pas de badge.

info

Le sideloading est le niveau "Direct Install" du modèle de distribution de marketplace. C'est le mécanisme de distribution natif du web — installez n'importe quelle application depuis n'importe quelle URL, le bac à sable fournissant une sécurité de base.

L'Interface de Sideload

La section Sideload dans le panneau Apps fournit :

Champ de saisie URL — Collez une URL de manifeste et cliquez sur Install
Diviseur "ou"
Bouton Upload App — Ouvre un sélecteur de fichiers acceptant les fichiers .html, .htm, .ais et .zip
Texte d'aide — "Accepts .html single-file apps or .ais bundles (ZIP with manifest.json)"

Les trois méthodes déclenchent la boîte de dialogue de permission standard avant de compléter l'installation. Les applications installées apparaissent dans la section Installed ci-dessus, avec des boutons Open et Uninstall.

Installation par URL​

Comment Ça Fonctionne​

Étapes​

Développement avec Localhost​

Mettre à Jour une Application Sideloadee​

Upload HTML​

Comment Ça Fonctionne​

Étapes​

Limitations​

Faire Fonctionner les Applications Mono-Fichier​

Bundle .ais​

Comment Ça Fonctionne​

Structure du Bundle​

Créer un Bundle​

Ce Qui Est Intégré​

Types MIME Supportés​

Exemple : Bundle d'Application Multi-Fichiers​

Limites de Taille de Fichier​

Sécurité​

L'Interface de Sideload​

Installation par URL

Comment Ça Fonctionne

Étapes

Développement avec Localhost

Mettre à Jour une Application Sideloadee

Upload HTML

Comment Ça Fonctionne

Étapes

Limitations

Faire Fonctionner les Applications Mono-Fichier

Bundle .ais

Comment Ça Fonctionne

Structure du Bundle

Créer un Bundle

Ce Qui Est Intégré

Types MIME Supportés

Exemple : Bundle d'Application Multi-Fichiers

Limites de Taille de Fichier

Sécurité

L'Interface de Sideload