Bolt Offline Behaviour

We have moved to docs.pugpig.com! You can find this article here

Pugpig Bolt aims to strike a balance between ensuring content is available whenever a user wants to read it, and respecting the limitations of data usage and storage space. This document details:

1. How content is fetched
2. How much content we store
3. How long that content may be stored
4. How you can manually make your user’s apps fetch content

CONTENT FETCHING

The first, and most obvious, way to fetch new content in your Bolt app is simply to open it. We check for new content on every foregrounding of the app. During an app session, new content can be fetched by a pull to refresh on any timeline as well as by paging around the app. 

The way in which content is saved to the device and made available offline varies depending on whether it is edition or timeline content.

Editions

Editions are asynchronously downloaded/updated when opened or the download icon on the storefront is tapped and are stored indefinitely as long as the edition remains available to the user and the user does not manually delete it. We don’t impose a limit on how many editions can be stored. In version 3.9 we're adding the ability for the user to select a time period after which editions are automatically deleted. 

These downloads include:

1. Article text
2. Article images
3. PDF pages
4. Audio files

Timelines

Timeline content the user reads is cached up to 200 MB and should be available for some time depending on usage. The reason we can’t specify exactly how long is fundamental to our use of the Least Recently Used (LRU) algorithm. Additionally, mobile operating systems retain the ability to reduce or remove an app’s stored data when device storage runs low. 

This cached data includes:

1. Article text
2. Article images

BACKGROUND DOWNLOADING

(Note that background downloading is disabled in Bolt 3.9 but will be reenabled in Bolt 3.10). This means that content will currently only be downloaded when the app is in the foreground.

Additionally, Bolt uses background fetch in order to maximise the availability of fresh content. This means that the app periodically wakes up when backgrounded and fetches content from the server. What content we fetch is based on a heuristic which prioritises content from timelines the user frequently visits. This means that some timelines might not be refreshed in the background, particularly in the case of apps with a large number of timelines.

Server-side we have the ability to control these background downloads. By default, to minimise the data usage and time required, the download may skip assets such as images, PDFs or audio files, we also default to only prefetching the first 50 articles of a timeline. This should be reduced in the case of apps with a large number of timelines.

By default, our background download will fetch the following data, depending on content type:

Editions

1. Article text
2. Article images
3. PDF pages
4. Audio files

Timelines

1. Article text

In discussion with you, we can alter this to increase or decrease the amount that is fetched. For example, you may want the background downloads to include the article images, because you have a lot of image-centric content. This will substantially increase the data usage for both you and your users, but may offer a much-improved reading experience.

The frequency and timing of this content refresh is dictated by the operating system, and is likely to happen more regularly the more a user engages with the app. The volume of content fetched is also controlled by the operating system, as the app is effectively given a certain amount of resource (time, storage and bandwidth) and we’ll do the best we can in that time. Furthermore, the operating system chooses the order in which the queued files are downloaded, hence the articles not necessarily being fetched in the same order as they’re listed on the timeline

BACKGROUND PUSH

It’s also possible to proactively trigger a background content fetch via a silent push notification, this will have the same effect described above, just at a time of your choosing. This is particularly useful in the case of apps with clear usage patterns (i.e. a morning edition) or shortly after any other notable content drop.

Background Push is also disabled in Bolt 3.9 but will be reenabled in Bolt 3.10.