Sign in Register

PWA Setup

PWA Setup Guide

This guide covers the PWA website setup for your site: app name, icons, install prompts, caching, health checks, and reset tools.

It does not cover App Store export or push notification provider setup.

Enable the PWA

Go to VH360 PWA & App → General.

Turn on Enable PWA features, then save the settings.

If the setting is disabled or locked, activate your product license first from VideoHub360 → License and return to the PWA settings screen.

The PWA also requires the Videohub360 Theme to be active. If the theme is not active, the PWA admin screen shows a warning and the frontend PWA features will not run.

Configure the App Details

On VH360 PWA & App → General, complete the main app fields:

  • App Name: the full app name shown in the PWA manifest.
  • Short Name: the shorter app name used where space is limited, including iOS home screen naming.
  • Description: the app description used in the PWA manifest.
  • Theme Color: the browser/app theme color.
  • Background Color: the app background color.
  • Display: choose how the PWA should open. The default setup uses standalone.
  • Orientation: choose the screen orientation. The recommended option shown in the settings is portrait-primary.
  • Start URL: the page the app opens to. A relative path such as / is accepted.
  • Scope: the site area controlled by the PWA. A relative path such as / is accepted.

Save the settings when finished.

Add PWA Icons

Go to VH360 PWA & App → Icons.

Upload a master icon, then generate the icon sizes.

Recommended master icon:

  • 1024×1024 PNG
  • Transparent background
  • Centered logo with padding

Minimum accepted source image:

  • 512×512 PNG or JPEG

Click Upload Master Icon, then click Generate All Icons.

The icon generator creates icon sizes for iOS, Android, and maskable Android icons. If icon generation is not available, ask your host to enable either Imagick or GD.

Configure Install Options

Go to VH360 PWA & App → General.

Use these options to control how users are invited to install the app:

  • Install Prompt: enables the install helper and the install button shortcode.
  • Automatic Install Banner: shows a top bar install banner on the frontend when the app is not installed.
  • Banner Text: controls the automatic install banner text.
  • Banner Dismiss (days): controls how long the banner stays hidden after a user dismisses it.
  • iOS Onboarding: shows Add to Home Screen instructions on iOS.
  • Install Button Text: controls the default button text for the install helper.

To place a manual install button on a page, use this shortcode:

[vh360_pwa_install_button]

You can also add a PWA status display with:

[vh360_pwa_status]

Configure Caching

Go to VH360 PWA & App → Caching.

Start with Safe caching. The settings screen identifies Safe mode as caching static assets only and using network-first behavior for pages.

Available cache strategies are:

  • Safe: cache static assets only; network-first for pages.
  • Balanced: cache static assets and opportunistically cache same-origin pages.
  • Aggressive: not recommended for logged-in sites.

Use Cache Version when you want visitors’ devices to drop old PWA caches. For example, change the value from v1 to v2 after a major cache-related change.

You can also enable:

  • Precache Offline Page
  • Precache Home Page
  • Additional Precache URLs

For additional precache URLs, enter one same-site URL per line. Relative paths are recommended.

Run the Health Check

Go to VH360 PWA & App → Health Check.

Click Run Health Check.

The health check verifies the common PWA requirements and endpoints, including:

  • Theme compatibility
  • HTTPS
  • Manifest endpoint
  • Service worker endpoint
  • Offline page endpoint
  • Whether PWA is enabled
  • Current cache strategy
  • Current cache version

The screen also shows quick endpoint links for the manifest, service worker, and offline page.

Test the PWA

After saving the PWA settings:

  1. Visit the frontend of your site in a supported browser.
  2. Confirm the install banner appears if Automatic Install Banner is enabled.
  3. Add the app to your device home screen.
  4. Open the installed app and confirm it launches to the configured Start URL.
  5. Test the offline page by loading the site once, then testing without a network connection.
  6. Run the Health Check again if anything does not work as expected.

Reset PWA Caches on a Device

Go to VH360 PWA & App → Tools.

Use these tools when testing or troubleshooting one device:

  • Clear PWA Caches (This Device)
  • Unregister Service Worker (This Device)
  • Reset Everything (This Device)
  • Reset Install Banner Dismissal

Each tool opens the site in a new tab and runs the reset action for that device.

Troubleshooting

PWA options are locked

Activate your license from VideoHub360 → License, then return to VH360 PWA & App → General.

PWA warning says the theme is not active

Activate the Videohub360 Theme, then return to the PWA settings screen.

Health Check fails HTTPS

PWAs require HTTPS. Enable SSL on the site, then run the Health Check again.

Manifest, service worker, or offline page fails

Go to Settings → Permalinks and save the page once to refresh WordPress rewrite rules. Then return to VH360 PWA & App → Health Check and run the check again.

Icons cannot be generated

Ask your hosting provider to enable Imagick or GD. The icon generator requires one of those image libraries.

Old app behavior remains after changes

Go to VH360 PWA & App → Caching and change the Cache Version value. Then use VH360 PWA & App → Tools → Reset Everything (This Device) on the device you are testing.