Cycle de vie et sauvegardes

Une expérience sereine est aussi une expérience bien conçue. Elle démarre vite, se met en veille quand personne ne la regarde, ne perd aucune sauvegarde et n’en écrit jamais deux fois la même.

La négociation

La plateforme charge votre entrée avec #zc_parent=…&zc_instance=… dans le fragment de l’URL.
connect() envoie zc.ready avec votre identifiant et votre version toutes les 250 millisecondes, jusqu’à recevoir une réponse.
La plateforme compare votre identifiant, votre version et votre protocole à l’approbation, puis répond par zc.connected avec le contexte et un port privé, ou vous rejette.
Ensuite, chaque appel passe par ce port. Si votre page est rechargée, la session prend fin et le visiteur redémarre depuis la plateforme.

Soyez prêt en 15 secondes

Appelez d’abord loading.start(), puis loading.ready() dès que le visiteur peut commencer. Chargez les ressources volumineuses ensuite. Si vous n’êtes pas prêt au bout de 15 secondes, la plateforme indique au visiteur qu’un problème est survenu. Si le démarrage est impossible, appelez loading.fail(message).

Commandes du cycle de vie

Commande	Action
`pause`	Arrêtez le son, les animations et les entrées. Signalez `paused`.
`resume`	Reprenez là où le visiteur s’est arrêté. Signalez `running`.
`visibility`	Envoyé une fois après la connexion, puis à chaque changement. Si `visible` vaut false, mettez-vous en veille comme lors d’une pause.
`dispose`	Arrêtez les minuteries et laissez le SDK vider vos sauvegardes. Le cadre est retiré dès votre réponse ou, au plus tard, après une seconde.

Signalez la session, ne comptez pas le temps

Appelez session.report({state, mode}) à chaque changement d’état, puis répétez l’appel toutes les quelques secondes pendant l’exécution. La plateforme mesure le temps côté serveur à partir de ces rapports. Elle cesse de compter lorsqu’elle reçoit paused ou ne reçoit plus rien pendant 12 secondes.

Les révisions protègent chaque sauvegarde

Chaque écriture augmente la révision d’une unité. Transmettez la dernière révision observée. Si une autre personne a écrit entre-temps, depuis un autre onglet ou appareil par exemple, l’écriture échoue avec CONFLICT au lieu d’écraser sa progression.

Réessayez avec le même identifiant de requête

Une erreur TIMEOUT ou INTERNAL ne signifie pas que l’écriture a échoué, seulement que vous n’en connaissez pas le résultat. Renvoyez les mêmes données avec le même requestId. Le serveur renvoie le premier résultat au lieu d’écrire deux fois. Réutiliser un identifiant avec des données différentes échoue avec IDEMPOTENCY_CONFLICT.

Laissez la sauvegarde automatique donner le rythme

storage.createAutosave(save) appelle votre fonction au plus une fois par intervalle : 10 secondes par défaut, avec un réglage de 10 secondes à 5 minutes. Appelez schedule() à chaque changement. Lors d’une pause, d’un masquage ou d’une suppression, ainsi qu’avant la fin d’une partie ou le départ du visiteur, le SDK vide immédiatement la file. Après trois tentatives infructueuses, il signale SAVE_UNCONFIRMED via onError. Renvoyez false depuis votre fonction si des changements plus récents restent à sauvegarder.

Quand le canal se ferme

onDisconnect est déclenché une seule fois. Conservez ce que voit le visiteur, arrêtez les sauvegardes et indiquez avec douceur qu’il peut rouvrir l’expérience pour continuer. Ne tentez jamais de vous reconnecter de votre propre initiative.