Offline Mode

Mattercraft’s publishing process has an ‘Offline Mode’ feature. When enabled, the first time a user visits the experience in a compatible web browser, all of the files and assets that make up that project will be downloaded and stored in the browser's cache. This means users can return to the experience even if they don't have a functioning network connection.

End User Experience

When an end user first visits an experience that has Offline Mode enabled, the browser will proactively download and cache the project’s files and assets. An on-screen user interface is shown to notify the user of the progress and completion of this process.

A custom Offline Mode user interface

One the download is complete, that page can be accessed by the user later, even if they don’t have a network connection on their device, or if their connection is slow.

If the user subsequently visits the experience after an update has been published, that update will be downloaded and the user will be prompted to reload the page to access the latest version.

Enabling Offline Mode

Offline Mode can be enabled from the Publish tab’s menu:

Offline Mode options via the Publish tab in the Left Menu

There are three settings for Offline Mode:

Setting Description
Off No attempt is made to make the experience available offline. This is the default setting.
On with UI When users visit the page, the experience will attempt to download the necessary files and assets for offline access. A simple on-screen user interface will be shown to the user, both to indicate the status of the download and when there is an update to the site that requires a reload of the page.
On without UI Support for Offline Mode is provided by Mattercraft, but no default user interface will be shown to the user to indicate status. With this option, we highly suggest adding custom UI of your own.

There are a few important considerations when using Offline Mode:

  • Only assets stored in your project in Mattercraft and referenced from your scenes or script files will be downloaded.
  • Mattercraft uses a standard browser feature called 'Service Workers' to provide this functionality. Most modern browsers support Service Workers, but how long the downloaded cache of a site is stored varies by browser and device.
  • Offline support applies only to the published version of your project and thus it does not affect Live Preview.

Offline Mode status indications

It’s often helpful to give the user an indication of the status of the experience’s availability for access offline. The following states are important:

Status Indication Description
Downloading Is shown when the browser is downloading the files for the first time, or if the content has been updated.
Available Offline Is shown once any download is complete and the user can return in the future without a network connection.
Update Available Is shown when an updated version of the content has been downloaded and the user must reload the page to access it.

Customization of the user interface is possible with the provided <mattercraft-offline-ui /> HTML tag.

Customizing the Offline Mode user interface

Mattercraft provides the <mattercraft-offline-ui /> HTML tag for use within the HTML of your project, such as in the index.html file. Place it at the location that you’d like the user interface for Offline Mode to appear in the page’s DOM. The appearance of the tag can be customized with CSS in the usual way.

Check out the Custom Offline Mode UI template in Mattercraft for an example of how to use this HTML tag.

Without any options set, the tag shows a button for the user to click or tap to make the site available offline, then it shows status messages throughout the download process.

The <mattercraft-offline-ui /> HTML tag has the following attributes:

Tag Attribute Description
auto When set, the download process will start automatically when the user lands on the page.
off When set, no built-in UI is shown.
prompttext The text for the button that starts the download process. The default is "Make available offline".
preparingtext The text to show when the file/asset download is taking place. The default is "Making available offline...".
availableofflinetext The text to shown when all files/assets have been downloaded and the site can be accessed without a network connection. The default is "Available offline".
updatingtext The text to show when a content update is being downloaded. The default is "Updating...".
reloadtext The text to show when an content update has been downloaded and the user can reload the page to access it. The default is "Reload to update".

Example of use:

<mattercraft-offline-ui prompttext="Going on a plane? Tap here to make this page available in airplane mode." />

Fully Custom UI with JavaScript

It’s possible to combine <mattercraft-offline-ui off /> with JavaScript events to build a fully customized user interface for Offline Mode.

The tag emits the following JavaScript events:

JavaScript event Description
preparing Is emitted when the download of files or assets has begun.
availableoffline Is emitted when the download is complete.
updating Is emitted when a content update download has begun.
reload Is emitted when a content update had been downloaded and the user can reload the page to access it.

Example of use:

<mattercraft-offline-ui off id="offline-ui" />
<script>
const offlineMode = document.getElementByID("offline-ui");
offlineMode.addEventListener("availableoffline", () => {
    // Show own UI
});
</script>
zapcode branded_zapcode i