Weegloo Docs - Créer une application

Pour publier sur la place de marché une application web que vous avez vous-même conçue en tant que Market App, vous devez d'abord compiler l'application et préparer le résultat de cette compilation. Cette étape comprend la compilation d'un site statique en HTML et JavaScript, puis la vérification du résultat de compilation en ligne de commande.

Une Market App est une application que vous publiez sur la place de marché et que d'autres Space installent ensuite. Sur le plan technique, c'est une application web statique, comme un Web Hosting. Vous déposez un ensemble de fichiers d'écran déjà compilés, et lorsqu'un visiteur arrive, ces écrans s'affichent tels quels.

Il existe une différence avec une application web ordinaire, et c'est elle qui impose une règle à respecter au moment de la compilation. Cette page traite de cette différence, de cette règle, et de la vérification à effectuer avant de publier.

L'installation copie les ressources dans le Space de la personne qui installe

Lorsqu'une Market App est installée, ce ne sont pas seulement les écrans de l'application qui sont copiés, mais aussi les ressources que vous avez sélectionnées au moment de la publication (Content Type, Content, Media, etc.) : elles sont copiées dans le Space de la personne qui installe l'application. Imaginez que vous avez créé et publié une application de catalogue de produits pour un magasin de vêtements. Lorsque quelqu'un installe cette application, le Content Type de produit et les Content de produit sont copiés dans son Space en même temps que les écrans de l'application.

Les ressources copiées reçoivent de nouveaux identifiants dans le Space où elles sont installées. Le Delivery Access Token utilisé pour lire le contenu est lui aussi recréé dans ce Space. Ainsi, l'application installée ne lit pas le Space de son créateur, mais sa propre copie placée dans le Space de la personne qui l'a installée. Une fois l'installation terminée, l'application fonctionne uniquement avec les ressources du Space où elle est installée.

Pourquoi les informations d'accès sont intégrées à la compilation

Une Market App installée n'a pas de serveur. Comme il s'agit d'un hébergement statique, comme un Web Hosting, il n'existe pas de moteur serveur qui calcule les écrans à chaque requête : c'est le navigateur lui-même qui appelle l'API de diffusion de WEEGLOO (CDA, Content Delivery API) pour récupérer le contenu. C'est pourquoi le résultat de compilation (les fichiers d'écran) doit indiquer par écrit dans quel Space lire, quoi lire et avec quelle valeur d'accès.

Le problème, c'est que, comme on l'a vu plus haut, l'installation copie les ressources avec de nouveaux identifiants. Les valeurs inscrites dans les fichiers de compilation sont les identifiants et le jeton du Space du créateur, alors que ce qu'il faut lire à l'endroit de l'installation, ce sont les copies nouvellement créées. Si l'on laisse les anciennes valeurs telles quelles, l'application pointe vers le mauvais endroit.

C'est pourquoi WEEGLOO substitue ces valeurs à votre place au moment de l'installation. Au moment de la publication, WEEGLOO repère à l'avance où se trouvent, dans le texte compilé, les identifiants, le jeton et les identifiants de ressources du Space du créateur, puis, à l'installation, il remplace ces emplacements par les nouvelles valeurs de la copie du Space d'installation. Grâce à cela, l'application installée pointe automatiquement vers le bon Space.

Cette substitution n'a lieu que pour les ressources que vous avez incluses dans l'application. Vous devez donc inclure sans exception, au moment de la publication, toutes les ressources que les écrans lisent (Content Type, Delivery Access Token, etc.). Si vous en oubliez une, son identifiant n'est pas substitué et reste une valeur erronée à l'endroit de l'installation. Ce que vous devez inclure est traité dans la sélection de ressources de Publier une application.

Cette substitution automatique repose sur une condition : la valeur doit figurer dans le texte compilé sous la forme d'une seule chaîne intacte, telle quelle. En effet, l'étape de publication recherche cette chaîne caractère pour caractère pour en enregistrer l'emplacement. Si vous fractionnez la valeur, si vous la construisez au moment de l'exécution ou si vous la récupérez depuis l'extérieur, l'étape de publication ne la trouve pas ; dans ce cas, aucune substitution n'a lieu à l'installation et l'application installée ne fonctionne pas.

Les valeurs intégrées à la compilation (et substituées à l'installation) sont au nombre de trois.

Le sys.id du Space d'origine (spaceId) : dans quel Space lire.
Le Delivery Access Token du Space d'origine : la valeur d'accès en lecture seule qui permet de lire le contenu publié de ce Space.
Les sys.id des ressources référencées par l'application : par exemple le sys.id du Content Type qui contient les produits, c'est-à-dire les identifiants de ressources vers lesquels pointe le code client.

Intégrer les valeurs en littéral

L'essentiel est que ces trois valeurs apparaissent dans le résultat de compilation sous la forme d'une seule chaîne littérale intacte (intact literal substring). Lorsque vous ouvrez les fichiers texte compilés (JS, HTML, JSON, etc.), la valeur doit apparaître d'un seul bloc, sans être fractionnée ni transformée. C'est à cette seule condition que l'étape de publication peut trouver la valeur et en enregistrer l'emplacement, et que l'étape d'installation peut remplacer cet emplacement par la nouvelle valeur.

Voici un exemple de configuration placée dans le code client. Les valeurs ne servent qu'à montrer le format ; vous devez les remplacer par vos véritables valeurs d'accès.

// weegloo.config.js : ces valeurs sont embarquées telles quelles dans le résultat de compilation
export const WEEGLOO = {
  spaceId: "spc_xxxxxxxxxxxxxxxx",                 // sys.id du Space d'origine
  deliveryAccessToken: "dat_xxxxxxxxxxxxxxxxxxxx",  // Delivery Access Token du Space d'origine
  productContentTypeId: "ct_xxxxxxxxxxxx",          // sys.id du Content Type que l'application lit
};

Le navigateur appelle directement la CDA avec ces valeurs.

fetch(`https://cda.weegloo.com/v1/spaces/${WEEGLOO.spaceId}/contents`, {
  headers: { Authorization: `Bearer ${WEEGLOO.deliveryAccessToken}` },
});

Les méthodes suivantes ne doivent pas être utilisées. Toutes empêchent la valeur de subsister sous forme de littéral intact dans le résultat de compilation, ce qui empêche l'étape de publication de la trouver. Dans ce cas, aucune substitution n'a lieu à l'installation, et l'application installée ne peut pas lire la copie présente dans son Space.

La lecture d'une variable d'environnement à l'exécution. L'application installée n'a ni serveur ni environnement d'exécution pour injecter la valeur, et la valeur ne subsiste pas non plus en clair dans le texte compilé.
```
// À proscrire : cette variable d'environnement n'existe pas à l'endroit de l'installation
deliveryAccessToken: process.env.DELIVERY_ACCESS_TOKEN
```
La récupération par un fetch à l'exécution. Si vous faites en sorte que la valeur soit récupérée depuis un endroit quelconque, elle ne subsiste pas dans le texte compilé et il n'existe aucun endroit d'où la récupérer.

Le fractionnement par concaténation de chaînes. La valeur n'apparaît pas d'un seul bloc et l'étape de publication ne la trouve pas.

// À proscrire : "dat_xxxxxxxxxxxxxxxxxxxx" ne subsiste pas comme une seule substring dans le résultat de compilation
deliveryAccessToken: "dat_" + "xxxxxxxxxxxxxxxxxxxx"

Laisser un espace réservé ou un champ vide. Le remplissage de la valeur est effectué par WEEGLOO au moment de l'installation. Mais cette substitution consiste à trouver la véritable valeur intégrée à la compilation et à remplacer cet emplacement ; si vous laissez un champ vide ou une marque temporaire, il n'y a aucune valeur à trouver et donc rien à substituer. La véritable valeur doit figurer en clair, caractère pour caractère, au moment où le résultat de compilation est produit.

Placez toujours les valeurs dans des fichiers texte (JS, HTML, JSON, etc.). Ne les mettez pas dans des fichiers binaires comme des images ou des polices. La recherche et la substitution des valeurs n'ont lieu que dans les fichiers texte.

Le bundler est aussi à vérifier. Certains bundlers fractionnent ou transforment les chaînes littérales lors de l'optimisation. Ne vous fiez pas au seul code source : ouvrez le résultat de compilation réel et vérifiez que la valeur y subsiste sous forme de littéral intact (voir la section suivante).

Émettre le jeton avec le moindre privilège

Le Delivery Access Token intégré à la compilation est exposé tel quel dans le navigateur. Toute personne qui installe l'application peut voir cette valeur dans ses fichiers de compilation (le jeton recréé dans ce Space après l'installation est exposé de la même façon). C'est pourquoi ce jeton doit être émis avec un SpaceRole du moindre privilège, qui ne peut lire que les Content Type que l'application doit réellement lire. N'émettez pas le jeton avec le rôle Administrator. Si un jeton doté de privilèges d'administrateur est exposé dans le navigateur, c'est l'ensemble du Space d'origine qui est mis en danger.

La façon de créer un SpaceRole du moindre privilège et d'émettre un Delivery Access Token avec ce rôle est traitée dans Jeton.

Vérifier avant de publier

Avant de publier, vérifiez non pas de tête mais dans le résultat de compilation réel que les valeurs ont bien été intégrées. Dans le dossier compilé, faites un grep du spaceId d'origine, du jeton et du sys.id de chaque ressource, et regardez s'ils apparaissent sous forme de littéral intact.

grep -r "DATxxxxxxxxxxxxxxxx" dist/

Il suffit que la valeur recherchée apparaisse d'un seul bloc (sans être fractionnée ni transformée) dans le résultat de compilation. Vérifiez-le pour les trois valeurs intégrées (spaceId, Delivery Access Token et sys.id des ressources référencées). Si l'une d'elles n'est pas détectée par le grep, l'étape de publication ne la trouvera pas non plus et elle ne sera pas substituée à l'installation (soit le bundler a transformé la valeur, soit elle a disparu à cause d'une lecture à l'exécution). Dans ce cas, reportez-vous à la section précédente « Intégrer les valeurs en littéral » et corrigez le code pour que la valeur subsiste sous forme de littéral intact.

Contraintes de la compilation statique

Le résultat de compilation d'une Market App suit les mêmes contraintes statiques qu'un Web Hosting.

Il n'y a pas de moteur serveur. Vous devez compiler en export statique (pas de SSR).
Une fois décompressé, l'ensemble doit comporter 100 fichiers ou moins.
Un fichier index.html doit se trouver tout en haut (à la racine) de l'ensemble.
Les appels aux API de WEEGLOO (CDA, etc.) se font directement depuis le navigateur.

Les contraintes statiques et les règles de l'ensemble de fichiers sont détaillées dans Déployer un site web.

Les écrans compilés sont placés dans l'App Bundle

Une fois la vérification terminée, le résultat de compilation est placé, lors de la publication, dans un App Bundle (le paquet qui regroupe l'application par version). Les ressources sélectionnées sur l'écran de publication sont placées dans le même paquet et sont copiées dans le Space d'installation lors de l'installation. La procédure de publication et de montée de version est traitée dans Publier une application.

Si l'application gère ses propres membres

Jusqu'ici, nous avons décrit le cas où l'on récupère, via la CDA, du contenu public que tout le monde peut lire. Si l'application gère sa propre inscription et connexion de membres, elle utilise ServiceLogin et le SDK client officiel. Dans ce cas, le navigateur appelle non pas la CDA mais l'ACDA (App Content Delivery API) avec le jeton du membre. La configuration et la méthode d'intégration sont traitées dans Connexion des membres de service.

Le mode d'authentification d'une Market App installée est traité par App Auth, et les utilisateurs ayant accès à l'application installée sont traités par App Member.

Étapes suivantes

Publier une application : traite de la procédure dans le studio de contenu pour publier l'application créée (App Bundle) sur la place de marché.
Déployer un site web : traite des bases du Web Hosting, comme la compilation statique, la limite de 100 fichiers et le index.html à la racine.
Jeton : traite de la façon d'émettre, avec un SpaceRole du moindre privilège, le Delivery Access Token à intégrer en littéral dans la compilation.
Référence d'API : traite des spécifications techniques comme le format des requêtes de la CDA (l'API de diffusion) que les écrans de l'application appellent pour charger le contenu, et de l'ACDA si l'application gère ses propres membres.