Skip to main content

A Django app to include a manifest.json and Service Worker instance to enable progressive web app behavior

Project description

django-pwa

Build Status Maintainability codecov PyPI - Downloads PyPI - Downloads PyPI - Downloads

This Django app turns your project into a progressive web app. Navigating to your site on an Android phone will prompt you to add the app to your home screen.

Prompt for install

Launching the app from your home screen will display your app without browser chrome. As such, it's critical that your application provides all navigation within the HTML (no reliance on the browser back or forward button).

Requirements

Progressive Web Apps require HTTPS unless being served from localhost. If you're not already using HTTPS on your site, check out Let's Encrypt and ZeroSSL.

Installation

Install from PyPI:

pip install django-pwa

Configuration

Add pwa to your list of INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    ...
    'pwa',
    ...
]

Define STATICFILES_DIRS for your custom PWA_APP_ICONS

STATICFILES_DIRS = [
    os.path.join(BASE_DIR, 'static'),
]

Configure your app name, description, icons, splash screen images, screenshots and shortcuts in settings.py:

PWA_APP_NAME = 'My App'
PWA_APP_DESCRIPTION = "My app description"
PWA_APP_THEME_COLOR = '#0A0302'
PWA_APP_BACKGROUND_COLOR = '#ffffff'
PWA_APP_DISPLAY = 'standalone'
PWA_APP_SCOPE = '/'
PWA_APP_ORIENTATION = 'any'
PWA_APP_START_URL = '/'
PWA_APP_STATUS_BAR_COLOR = 'default'
PWA_APP_ICONS = [
    {
        'src': '/static/images/my_app_icon.png',
        'sizes': '160x160'
    }
]
PWA_APP_ICONS_APPLE = [
    {
        'src': '/static/images/my_apple_icon.png',
        'sizes': '160x160'
    }
]
PWA_APP_SPLASH_SCREEN = [
    {
        'src': '/static/images/icons/splash-640x1136.png',
        'media': '(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)'
    }
]
PWA_APP_DIR = 'ltr'
PWA_APP_LANG = 'en-US'
PWA_APP_SHORTCUTS = [
    {
        'name': 'Shortcut',
        'url': '/target',
        'description': 'Shortcut to a page in my application'
    }
]
PWA_APP_SCREENSHOTS = [
    {
      'src': '/static/images/icons/splash-750x1334.png',
      'sizes': '750x1334',
      "type": "image/png"
    }
]

Show console.log

Set the PWA_APP_DEBUG_MODE = False to disable the the console.log on browser.

All settings are optional, and the app will work fine with its internal defaults. Highly recommend setting at least PWA_APP_NAME, PWA_APP_DESCRIPTION, PWA_APP_ICONS and PWA_APP_SPLASH_SCREEN. In order to not use one of the internal defaults, a setting can be set to an empty string or list, whichever one is applicable.

Add the progressive web app URLs to urls.py:

from django.urls import url, include

urlpatterns = [
    ...
    url('', include('pwa.urls')),  # You MUST use an empty string as the URL prefix
    ...
]

Inject the required meta tags in your base.html (or wherever your HTML <head> is defined):

{% load pwa %}

<head>
    ...
    {% progressive_web_app_meta %}
    ...
</head>

Troubleshooting

While running the Django test server:

  1. Verify that /manifest.json is being served
  2. Verify that /serviceworker.js is being served
  3. Verify that /offline is being served
  4. Use the Application tab in the Chrome Developer Tools to verify the progressive web app is configured correctly.
  5. Use the "Add to homescreen" link on the Application Tab to verify you can add the app successfully.

The Service Worker

By default, the service worker implemented by this app is:

// Base Service Worker implementation.  To use your own Service Worker, set the PWA_SERVICE_WORKER_PATH variable in settings.py

var staticCacheName = "django-pwa-v" + new Date().getTime();
var filesToCache = [
    '/offline',
    '/css/django-pwa-app.css',
    '/images/icons/icon-72x72.png',
    '/images/icons/icon-96x96.png',
    '/images/icons/icon-128x128.png',
    '/images/icons/icon-144x144.png',
    '/images/icons/icon-152x152.png',
    '/images/icons/icon-192x192.png',
    '/images/icons/icon-384x384.png',
    '/images/icons/icon-512x512.png',
    '/static/images/icons/splash-640x1136.png',
    '/static/images/icons/splash-750x1334.png',
    '/static/images/icons/splash-1242x2208.png',
    '/static/images/icons/splash-1125x2436.png',
    '/static/images/icons/splash-828x1792.png',
    '/static/images/icons/splash-1242x2688.png',
    '/static/images/icons/splash-1536x2048.png',
    '/static/images/icons/splash-1668x2224.png',
    '/static/images/icons/splash-1668x2388.png',
    '/static/images/icons/splash-2048x2732.png'
];

// Cache on install
self.addEventListener("install", event => {
    this.skipWaiting();
    event.waitUntil(
        caches.open(staticCacheName)
            .then(cache => {
                return cache.addAll(filesToCache);
            })
    )
});

// Clear cache on activate
self.addEventListener('activate', event => {
    event.waitUntil(
        caches.keys().then(cacheNames => {
            return Promise.all(
                cacheNames
                    .filter(cacheName => (cacheName.startsWith("django-pwa-")))
                    .filter(cacheName => (cacheName !== staticCacheName))
                    .map(cacheName => caches.delete(cacheName))
            );
        })
    );
});

// Serve from Cache
self.addEventListener("fetch", event => {
    event.respondWith(
        caches.match(event.request)
            .then(response => {
                return response || fetch(event.request);
            })
            .catch(() => {
                return caches.match('offline');
            })
    )
});

Adding Your Own Service Worker

To add service worker functionality, you'll want to create a serviceworker.js or similarly named template in a template directory, and then point at it using the PWA_SERVICE_WORKER_PATH variable (PWA_APP_FETCH_URL is passed through).

PWA_SERVICE_WORKER_PATH = os.path.join(BASE_DIR, 'my_app', 'serviceworker.js')

The offline view

By default, the offline view is implemented in templates/offline.html You can overwrite it in a template directory if you continue using the default serviceworker.js.

Feedback

I welcome your feedback and pull requests. Enjoy!

License

All files in this repository are distributed under the MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_pwa-2.0.1.tar.gz (448.2 kB view details)

Uploaded Source

Built Distribution

django_pwa-2.0.1-py3-none-any.whl (454.0 kB view details)

Uploaded Python 3

File details

Details for the file django_pwa-2.0.1.tar.gz.

File metadata

  • Download URL: django_pwa-2.0.1.tar.gz
  • Upload date:
  • Size: 448.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.0 CPython/3.12.6

File hashes

Hashes for django_pwa-2.0.1.tar.gz
Algorithm Hash digest
SHA256 5539fabb41fe189cc2a82cb1f0f889b45671a8144d7b5bb5206a9ddd0fddb3c2
MD5 14fa22f3056606f015c4ab8247becfbd
BLAKE2b-256 395f4a77504bb5edd693711ec2a396d47836f0a0b4d3f2fb9dc773f8b450c067

See more details on using hashes here.

File details

Details for the file django_pwa-2.0.1-py3-none-any.whl.

File metadata

  • Download URL: django_pwa-2.0.1-py3-none-any.whl
  • Upload date:
  • Size: 454.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.0 CPython/3.12.6

File hashes

Hashes for django_pwa-2.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 41dc931c645c6125c556bd753205ca051aa48e5d46edbf281003594f3d76d4a3
MD5 d19b6a0810e41879b13b02acb1bb1ef3
BLAKE2b-256 c3645ffd65b8e8e9d5563e863d868c259f69a1af79c878f6be469540c573347c

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page