Valider et publier des canvases

La source d'un canvas vit dans PostHog, versionnée à chaque publication. La publication est protégée : chaque modification se base sur une version spécifique, et le serveur refuse de réécrire des travaux plus récents. Chaque publication met en file d'attente une compilation côté serveur, et le canvas affiche la dernière compilation réussie.

Le projet source

canvas-source-retrieve retourne :

project — schemaVersion (1), files (chemin → contenu), entryHtml ("index.html"), dependencies (versions exactes verrouillées par plateforme), canvasSdkVersion, capabilities.
current_version_id — la version sur laquelle se basent vos modifications. Conservez-la ; la publication en a besoin. Il est null pour un canvas jamais publié — passez ce null lors de la première publication.

Conservez index.html et dependencies exactement comme retournés. Vous pouvez ajouter des fichiers sources relatifs et des assets admis au projet. Utilisez ?worker pour un module worker autonome et représentez les assets binaires comme des entrées base64 dans assets ; les nouvelles dépendances npm ou les écarts de version de dépendance échouent à la validation.

Déclarer les capabilities

L'hôte applique project.capabilities à l'exécution, donc un appel ph non déclaré compile bien puis meurt dans le canvas rendu. Déclarez :

capabilities.posthog.insights — chaque ID court d'insight que le canvas passe à ph.loadInsight.
capabilities.posthog.captureEvents — chaque nom d'événement qu'il passe à ph.capture.
capabilities.posthog.inlineQueries: true — quand il appelle ph.query du tout.
capabilities.posthog.agentRequests: true — quand il appelle ph.agent.request.
capabilities.network.origins — chaque origine HTTPS exacte utilisée par fetch, XMLHttpRequest, ou une feuille de style, image, police, fichier média ou frame externe. Les scripts distants restent bloqués. N'incluez pas les chemins, identifiants, requêtes, fragments ou caractères génériques. L'hôte doit être public : les IPs de boucle locale et privées, les noms monolabel comme intranet, et les suffixes .local, .localhost, .internal et .home.arpa sont tous rejetés, donc un hôte dev local comme https://localhost:8010 échoue la validation avec une erreur invalid_network_origin. Les données envoyées à une origine déclarée quittent PostHog et apparaissent dans l'examen des capabilities avant la promotion.

Avant la validation, inventoriez chaque URL externe littérale dans chaque fichier source. Classez les liens de navigation et les URLs ph.openExternal() comme navigation ; ils ne nécessitent pas d'origine réseau. Pour chaque URL de requête ou de ressource, déclarez son schéma + hôte + port optionnel uniquement. Incluez chaque origine vers laquelle une requête redirige et chaque origine secondaire qu'une feuille de style référence pour les polices ou images. Ne déduisez jamais qu'un nom d'hôte CDN en couvre un autre.

La validation rejette les appels littéraux et les URLs de ressources non déclarées (diagnostics capability_missing_*) pour que vous puissiez les corriger avant de publier. Les URLs dynamiques et les destinations de redirection ne peuvent pas être déduites, donc l'inventaire est toujours nécessaire même quand la validation est propre.

Valider jusqu'à ce que ce soit propre

canvas-validate-create est sans effet de bord ; appelez-le aussi souvent que nécessaire. Les diagnostics portent severity, un code stable, un message, et (pour les problèmes spécifiques aux fichiers) path et line :

Les diagnostics error bloquent la publication — corrigez-les tous. Courants : import_not_allowed (les imports simples sont limités aux dépendances retournées dans le projet source), forbidden_dynamic_import / forbidden_require / forbidden_inline_script, invalid_path, capability_missing_insight / capability_missing_capture_event / capability_missing_inline_queries / capability_missing_agent_requests / capability_missing_network_origin, dependency_not_admitted / dependency_version_mismatch, et violations de chemin/taille.
Les diagnostics warning ne bloquent pas, mais écoutez-les : network_fetch / network_xhr signifient que le code accède au réseau directement. Déclarez l'origine HTTPS exacte ou utilisez le pont ph.

Publier protégé

La publication devient live immédiatement, donc c'est pour la première version d'un canvas ou pour une modification que l'utilisateur a explicitement demandée de mettre en ligne. Un canvas qui a déjà une version live se retrouve par défaut en brouillon à la place — voir « Brouillon, puis promotion » ci-dessous.

Deux façons de publier, toutes deux protégées :

Projet complet — canvas-publish-create avec le project complet.
Modifications par fichier — canvas-edit-create avec operations (chacune définit le contenu complet d'un fichier, ou le supprime avec content: null). Préférez ceci pour les petites modifications d'un grand projet ; la protection est obligatoire ici car le sens d'un diff dépend de sa base.

Pour une publication de projet complet avec canvas-publish-create :

Passez toujours expected_current_version_id — le current_version_id que vous avez lu (ou null explicite lors d'une première publication). Les publications non protégées peuvent silencieusement écraser les modifications concurrentes.
Incluez un court prompt décrivant le changement ; il devient le libellé de l'entrée d'historique de version.
Passez name uniquement pour renommer le canvas (par ex. une première compilation d'un canvas sans titre).
Publiez une fois par modification demandée. Si l'utilisateur demande une autre modification ensuite, relisez la source (la tête a peut-être bougé) et publiez à nouveau — ne groupez pas les modifications non liées en une seule version, et ne publiez pas un travail en cours après chaque micro-modification.
Un 429 signifie que la capacité de compilation de l'équipe est temporairement épuisée. Attendez ~30 secondes et recommencez la même publication ; rien n'a été sauvegardé.

La réponse retourne le nouveau current_version_id.

Après publication : attendre la compilation

Une publication met en file d'attente une compilation côté serveur de la version. Le canvas ne se met à jour que quand la compilation est prête, et personne d'autre ne regarde le résultat — c'est le vôtre. Interrogez canvas-builds-retrieve toutes les quelques secondes (jusqu'à ~2 minutes) jusqu'à ce que la compilation que vous avez mise en file soit terminale :

queued/building — en cours ; interrogez à nouveau bientôt.
ready — le published_build_id du canvas avance vers cette compilation (sauf si une publication plus récente l'a d'abord remplacée). Le travail du canvas de la tâche est terminé.
failed — lisez les diagnostics d'erreur de la compilation, corrigez le projet, et publiez à nouveau. Une compilation échouée ne remplace jamais la dernière bonne, donc le canvas continue de rendre la version précédente — terminer la tâche ici laisserait l'utilisateur avec un canvas obsolète et une défaillance silencieuse.

Les rapports d'erreur d'exécution (déposés sur la tâche de création quand un canvas rendu lève une exception) nomment la compilation dont ils proviennent. Un rapport d'un ID de compilation plus ancien est de l'historique, pas une preuve sur votre code actuel — vérifiez-le par rapport à la compilation que vous venez de publier avant d'agir. En particulier, un rapport qu'une API ph documentée est indéfinie (par ex. ph.state) signifie que cet artefact a été cuit par une exécution d'hôte plus ancienne : republier pour qu'une compilation actuelle la remplace. Ne le « corrigez » jamais en supprimant l'API ou sa déclaration de capability.

Brouillon, puis promotion

La publication devient live dès que sa compilation est prête. Pour un canvas qui a déjà une version live, ce n'est pas la valeur par défaut : préparez la modification en tant que brouillon et laissez l'utilisateur la promouvoir. Publiez directement uniquement pour la première version d'un canvas (rien n'est live à protéger) ou quand l'utilisateur a explicitement demandé à mettre la modification en ligne. Un brouillon est une véritable version compilable qui n'est jamais la tête : le canvas live continue de rendre la version actuelle jusqu'à ce que quelqu'un promeuve le brouillon. C'est différent de canvas-validate-create, qui ne fait que vérifier la compilation et ne produit pas de compilation ou d'aperçu.

Préparer — canvas-draft-create avec le project complet (même forme, capabilities, et validation qu'une publication). Pas de expected_current_version_id : un brouillon se base sur rien et n'entre en conflit avec rien. La réponse retourne le version_id du brouillon, sa build mise en file, et capability_widening — les insights, les événements capturés, les requêtes inline, et les origines réseau que le brouillon déclare au-delà de la version live. Remontez un élargissement non vide à l'utilisateur avant de promouvoir ; c'est l'accès que le changement accorderait nouvellement.
Attendre la compilation — interrogez canvas-builds-retrieve jusqu'à ce que la compilation du brouillon soit terminale, de la même façon qu'après une publication. Un brouillon dont la compilation a échoué est corrigé en préparant un nouveau brouillon, pas en le promouvant.
Aperçu — lisez les fichiers du brouillon avec canvas-source-retrieve en passant son version_id ; une fois que sa compilation est ready, l'app affiche ce brouillon quand la version est ouverte. Le brouillon n'est pas dans canvas-versions-retrieve (qui liste uniquement l'historique publié) et ne peut pas être rétabli comme — listez les brouillons en attente avec canvas-drafts-retrieve.
Promouvoir — uniquement quand l'utilisateur a approuvé le brouillon ou explicitement demandé d'aller live ; la valeur par défaut est d'arrêter après la préparation et de signaler le brouillon. canvas-promote-create rend le brouillon la tête live. Passez expected_current_version_id (le current_version_id live depuis canvas-source-retrieve) ; c'est protégé exactement comme une publication et 409s sur une tête qui a bougé (récupérez comme ci-dessous). Un brouillon dont la compilation est toujours ready devient live sans recompilation ; sinon une nouvelle compilation est mise en file, alors attendez-la comme à l'étape 2. Promouvoir est le seul chemin d'un brouillon vers live.

Récupération d'un 409 version_conflict

Un 409 signifie que le canvas a bougé au-delà de votre base — une publication concurrente ou une annulation. La réponse inclut le current_version_id live. Ne recommencez jamais sans protection pour forcer votre version :

Relisez la source avec canvas-source-retrieve.
Réappliquez vos modifications à la source fraîche (la nouvelle tête peut contenir les modifications de quelqu'un d'autre — préservez-les).
Publiez à nouveau avec le nouveau current_version_id.

Sémantique de l'historique de version

Chaque publication ajoute une version source complète et déplace le pointeur de tête ; les utilisateurs peuvent rétablir les versions plus anciennes dans l'app (ce qui les republish et les recompile). La protection est importante car se baser sur la version que vous avez réellement lue est ce qui empêche le rétablissement d'un utilisateur, la publication d'un autre agent, et votre modification de s'effacer silencieusement.

validating-and-publishing-canvases