What is a configuration version?

A configuration version is a versioned set of app settings that controls parts of your Pugpig Bolt app without requiring a new release through the Apple App Store or Google Play.

It is separate from the app version installed on a device. The app version identifies the mobile app software itself, while the configuration version identifies the app setup that the app is using.

Configuration versions are created and activated by Pugpig. Once a configuration is activated, it becomes available for the app to download. An installed app normally picks up the new configuration the next time it connects to the internet and starts a new session.

Two kinds of configuration

There are two kinds of configuration in a Bolt app:

1. Runtime configuration: settings that can be changed after the app has been released, by activating a new configuration version.
2. Build time configuration: settings and assets that are packaged into the app when it is built and submitted to the app stores. These can only be changed with an app update.

What can be changed with runtime configuration?

The exact options depend on the features enabled in your app, but runtime configuration can include:

App appearance

• Colours used for icons, toolbars and text
• Font sizes and text styling (using fonts already included in the app)
• Timeline styling

App structure and navigation

• Tabs and tab order
• Toolbar logos and tab icons
• Settings screen layout and content
• Timeline groups and storefront structure

App wording and presentation

• Labels and other in-app copy
• Presentation and styling of configured app components

Authentication and subscriptions

• Adjustments to existing third-party authentication settings
• App Store and Google Play subscription settings
• Other supported subscription and access configuration

These changes can generally be tested before they are made available to all users. Pugpig can provide a preview process so that your team can review the proposed configuration before activation.

What is set at build time?

When your app is built, a configuration is packaged into it. This build time configuration determines what the app can do and what it looks like the very first time a user opens it.

Integrations and addons

Integrations that rely on third-party SDKs are only included in the app if they are configured at build time. This keeps the app as small as possible. Examples include:

• Push notification providers
• Analytics providers
• Authentication providers
• Native Google ads

Adding a new integration of this kind requires an app update. Once an integration is included in the build, many of its settings can be adjusted later through runtime configuration.

Elements required on first install

Some elements must be in the app from the moment it is installed, because they are needed before the app has had a chance to download a newer configuration:

• App icon and app name
• Toolbar logos and tab icons: these can be updated later through configuration, but they also need to be in the build so the app is correctly branded from first launch
• Other bundled assets, such as fonts
• Welcome (onboarding) screens: these appear on first launch, so new or changed screens are only seen by users who install a version of the app that contains them
• Splash screen: if a splash screen is not included at build time, it cannot be added later through configuration. If it is included, it can be changed or removed through configuration

Platform permissions and entitlements

• App Tracking Transparency (iOS)
• New domain entitlements for linking (iOS and Android), and new deep link path structures on Android
• iOS capabilities such as background audio and background refresh

The build time configuration does not have to be the active one

The configuration packaged into a build does not need to be the configuration that is currently activated for existing users. A build can be submitted with a configuration that has not yet been activated, for example when preparing new features or a redesign alongside an app release.

Users installing the app for the first time see the configuration the app was built with. After that, the app fetches the activated configuration in a later session.

Other considerations

Include important changes in the build time configuration

Because new users see the build time configuration when they first open the app, some changes that can be made through runtime configuration should also be included in the next build:

• Subscription and metering changes. Where subscription or metering settings are changed through configuration, include them in the build time configuration too. This ensures that every user, including those installing the app for the first time, gets a consistent subscription and paywall experience.
• Major branding changes. Toolbar logos and tab icons can be updated through configuration, but any major branding changes should also be included in the build time configuration. This ensures that new users installing the app see the correct branding from the start, rather than the previous branding until the new configuration is fetched.

Some features require an activated configuration

Most configuration changes can be previewed before activation. However, some features only work with an activated configuration version, so they cannot be fully tested using an unactivated configuration. Where this applies, Pugpig will agree an approach with you for testing and rollout.

Compatibility with older app versions

Pugpig takes steps to make sure new configurations work with older versions of the app. Occasionally, however, a newer configuration may not be fully compatible with an older app version, for example where a configuration relies on functionality introduced in a more recent Bolt release.

This is one of the reasons we recommend keeping your app up to date with the latest Bolt version. Readers who do not, or cannot, update their app to the latest version may be affected. This includes readers whose devices run an operating system version that newer Bolt releases no longer support. See Pugpig Bolt Supported Operating Systems for details.

What is not included in a configuration version?

• Editorial content. Articles, editions and other content update independently of configuration versions. You can add new timelines to existing timeline groups and new editions to existing storefronts at any time. Adding new timeline groups or storefronts requires a configuration change.
• The app software. New functionality that requires changes to the native app code requires an app update.

Configuration version versus other versions

Several version numbers may appear in the app's Settings screen. They refer to different things:

All of these version numbers are recorded in the app logs. The logs include both the build time configuration version and any updated configuration versions, along with when each configuration was updated or activated on the device. This lets Pugpig see exactly which app software, timeline component and configuration were in use when an issue occurred.

This is one of the main reasons app logs are so important for troubleshooting. When reporting an issue, please send the app logs from an affected device wherever possible. See How to find and email app logs for instructions.

When will users see a new configuration?

After a configuration is activated, users do not necessarily see it straight away. The app must fetch the new configuration, which requires an internet connection. In normal use, the change is picked up after the previous app session has ended and the app is opened again, either because the user has force closed the app or because the operating system has removed it from memory after it has been in the background for some time.

In summary

A configuration version is a versioned set of remotely managed app settings. It lets Pugpig change many aspects of your app's appearance, structure, wording and subscription behaviour without a new app release. Integrations, first-install elements such as the app icon, fonts, welcome screens and splash screens, and certain platform permissions are set at build time and need an app update to change. Subscription, metering and major branding changes should also be included in the build time configuration so that new users get a consistent experience. Keeping your app on the latest Bolt version ensures the best compatibility with new configurations.

Further reading

• Preview content and app configurations in Pugpig Bolt
• Pugpig Bolt Supported Operating Systems
• How to find and email app logs