Lebenszyklus und Speichern

Ein ruhiges Erlebnis verhält sich auch zuverlässig. Es startet schnell, ruht, wenn niemand hinsieht, verliert keinen Speicherstand und schreibt keinen doppelt.

Der Handshake

Die Plattform lädt deinen Einstieg mit #zc_parent=…&zc_instance=… im Hash.
connect() sendet alle 250 Millisekunden zc.ready mit deiner ID und Version, bis eine Antwort eintrifft.
Die Plattform vergleicht deine ID, Version und dein Protokoll mit der Freigabe und antwortet mit zc.connected, dem Kontext und einem privaten Port – oder weist dich ab.
Danach läuft jeder Aufruf über diesen Port. Wird deine Seite neu geladen, endet die Sitzung und die Besuchenden starten erneut über die Plattform.

Innerhalb von 15 Sekunden bereit sein

Rufe zuerst loading.start() und dann loading.ready() auf, sobald die Besuchenden beginnen können. Lade umfangreiche Ressourcen erst danach. Bist du nach 15 Sekunden nicht bereit, weist die Plattform auf ein Problem hin. Kannst du nicht starten, rufe loading.fail(message) auf.

Lebenszyklus-Befehle

Befehl	Aktion
`pause`	Beende Ton, Animation und Eingaben. Melde `paused`.
`resume`	Setze dort fort, wo die Besuchenden aufgehört haben. Melde `running`.
`visibility`	Wird nach der Verbindung einmal und danach bei jeder Änderung gesendet. Wenn `visible` den Wert false hat, ruhe wie im pausierten Zustand.
`dispose`	Beende Timer und lass das SDK deine Speicherstände schreiben. Sobald du antwortest, wird das Frame entfernt, spätestens nach einer Sekunde.

Sitzung melden, Zeit nicht selbst zählen

Rufe session.report({state, mode}) bei jeder Statusänderung und während des Betriebs alle paar Sekunden erneut auf. Die Plattform erfasst die Zeit anhand dieser Meldungen auf dem Server. Sie zählt nicht weiter, sobald sie paused empfängt oder 12 Sekunden lang keine Meldung erhält.

Revisionen schützen jeden Speicherstand

Bei jedem Schreiben steigt die Revision eines Speicherstands um eins. Übergib die zuletzt gelesene Revision. Hat inzwischen jemand anderes geschrieben, etwa in einem anderen Tab oder auf einem anderen Gerät, schlägt der Schreibvorgang mit CONFLICT fehl, statt den Fortschritt zu überschreiben.

Mit derselben Anfrage-ID wiederholen

Ein Fehler TIMEOUT oder INTERNAL bedeutet nicht, dass der Schreibvorgang fehlgeschlagen ist, sondern nur, dass du es nicht weißt. Sende dieselben Daten erneut mit derselben requestId. Der Server gibt das erste Ergebnis zurück, statt doppelt zu schreiben. Wird eine ID mit anderen Daten wiederverwendet, schlägt der Vorgang mit IDEMPOTENCY_CONFLICT fehl.

Das automatische Speichern gibt den Takt vor

storage.createAutosave(save) ruft deine Funktion höchstens einmal pro Intervall auf: standardmäßig alle 10 Sekunden, einstellbar zwischen 10 Sekunden und 5 Minuten. Rufe bei jeder Änderung schedule() auf. Bei Pause, Ausblenden und Aufräumen sowie vor Abschluss eines Durchlaufs oder dem Verlassen schreibt das SDK sofort. Nach drei Fehlversuchen meldet es SAVE_UNCONFIRMED über onError. Gib aus deiner Funktion false zurück, wenn neuere Änderungen noch gespeichert werden müssen.

Wenn der Kanal geschlossen wird

onDisconnect wird einmal ausgelöst. Lass die aktuelle Ansicht bestehen, beende das Speichern und erkläre freundlich, dass die Besuchenden das Erlebnis erneut öffnen können, um fortzufahren. Stelle niemals selbst eine neue Verbindung her.