How to Modify and Use the PWA - CoryInIT/chrome-presentation-pwa GitHub Wiki

Simple Use

Simply add a Chrome App as a Kiosk and set it to automatically launch with the address

https://coryinit.github.io/chrome-presentation-pwa/?sheetID=<YOUR PUBLISHED AS A CSV GOOGLE SHEET ID>

With the Google sheetID in the format:

2PACX-1vTkKXXXXXXXXXXXXXXX_JXXXXXXXXXXXXXXXXXXX_SJpXXXXXXXXXXXXXXXXlo2nSi

Then see the section below for how to format your CSV and publish your presentations for this to work correctly.

However I make no warranty about the fitness of this for your use case, nor do I guarantee I won't break this as I test and update things. Therefore, please do the following

Fork and Use your own PWA.

To download and modify the Chrome PWA from the provided GitHub repository, follow these steps. This guide will walk you through cloning the repository, updating the application's icons and name, and changing the URL for the CSV data source to a Google Sheet published as a CSV.

How to Download and Modify a Chrome PWA for Web Hosting

This document explains how to download the chrome-presentation-pwa repository, modify its icons, app name, and the CSV data URL to suit your specific needs. While the instructions will focus on GitHub Pages for deployment, remember that this PWA can be hosted on any web server that supports HTTPS.

Prerequisites

  • Git: You need Git installed on your system. You can download it from [git-scm.com](https://git-scm.com/).
  • Text Editor: A code-friendly text editor (e.g., VS Code, Sublime Text, Atom).
  • Google Account: To publish a Google Sheet as a CSV.
  • GitHub Account: (Required for GitHub Pages hosting).

Step 1: Download the GitHub Repository

  1. Open your terminal or command prompt.

  2. Navigate to the directory where you want to store the project. For example:

    cd Documents/Projects

  3. Clone the repository:

    git clone https://github.com/CoryInIT/chrome-presentation-pwa.git

    This command creates a new directory named chrome-presentation-pwa containing all the project files.

  4. Navigate into the cloned directory:

    cd chrome-presentation-pwa

Step 2: Prepare Your Icons

Before modifying manifest.json, you'll need your custom icons. The PWA requires icons of various sizes for different contexts.

  1. Create your icon files. It's recommended to have square PNG images.
  2. Resize your icons to the following dimensions:
    • 192x192.png
    • 512x512.png
  3. Place these icon files into the images directory within your cloned repository (e.g., chrome-presentation-pwa/images/).
  4. Rename your icon files to something descriptive, or use the recommended icon-192x192.png and icon-512x512.png to match the existing structure. If you use different filenames, you will need to update manifest.json accordingly.

Step 3: Modify manifest.json (Icons and App Name)

The manifest.json file defines your PWA's metadata, including its name and icons.

  1. Open the manifest.json file located in the root of your chrome-presentation-pwa directory using your text editor.

  2. Modify the name and short_name fields:

    • Change "name": "Chrome Presentation PWA" to your desired application name.
    • Change "short_name": "PWA" to a shorter version of your app name, which is often used when space is limited (e.g., on a home screen).
    {
  "name": "Your Awesome App Name",
  "short_name": "Your App",
  "icons": [
    {
      "src": "images/your-icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/your-icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "start_url": "index.html",
  "display": "standalone",
  "background_color": "#3E454B",
  "theme_color": "#3E454B"
}

  3. Update the src paths for the icons:

    • Ensure the src values under the "icons" array point to your new icon filenames within the images directory. For example, if your new icons are named my-app-icon-192.png and my-app-icon-512.png, you would update the src paths accordingly.
    {
  "name": "Your Awesome App Name",
  "short_name": "Your App",
  "icons": [
    {
      "src": "images/my-app-icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/my-app-icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "start_url": "index.html",
  "display": "standalone",
  "background_color": "#3E454B",
  "theme_color": "#3E454B"
}

  4. Save the manifest.json file.

Step 4: Publish Your Google Sheet as a CSV

The PWA is designed to fetch data from a CSV file. You can easily use a Google Sheet for this purpose by publishing it as a CSV.

  1. Open your Google Sheet that contains the data you want to use.
  2. Go to File > Share > Publish to web.
  3. In the "Publish to web" dialog:
    • Under "Link," select the sheet you want to publish.
    • From the dropdown menu, choose "Comma-separated values (.csv)".
    • Click the "Publish" button.
    • Confirm by clicking "OK".
  4. Copy the URL that is provided. This is your CSV URL. It will look something like: https://docs.google.com/spreadsheets/d/e/2PACX-1vR.../pub?gid=0&single=true&output=csv

The CSV must include both 'device_id' and 'presentation_url' (case sensitive), but can contain other columns as needed, shown below:

device_id,serial_number,building,type,location,presentation_url,notes
GIPS3782812317,5CDasd4B124,BuildingName,General,IT Office,https://docs.google.com/presentation/d/e/2PACX-1vQh4kABaQQDB5M86rstdnncaHLrmz7bo4frZb9u1uijznHCKDDBt4bbMvGUh/pubembed?rm=minimal&start=true&loop=true&delayms=10000,Test Chromebook
GIPS729123641,5Cssseeee1L,BuildingName,HumanResources,Joes Office,https://www.youtube.com/embed/9PJ2SHm0UYk?rel=0&autoplay=1&loop=1&playlist=9PJ2SHm0UYk,Test Chromebook

Note:

Presentation URLs are for Google Slides Presentations and Youtube Links. Use the Share -> Embed code from Youtube to generate the URL. I removed the 'si' tracking tag, but I think you can use it. You have to put the videoID as the playlistID to loop a video as Youtube loops playlists, not individual videos.

Step 5: Test Your PWA (Optional but Recommended)

You can test your modified PWA locally using a simple web server or by loading it as an unpacked extension in Chrome.

Option A: Using a Local Web Server (Recommended)

  1. Install a simple HTTP server if you don't have one. Python's http.server is a good option:

    python -m http.server 8000

    (Run this command from within the chrome-presentation-pwa directory).

  2. Open your web browser and navigate to http://localhost:8000.

  3. Your PWA should load, and you can test if the data is fetched correctly and if the manifest settings (like app name and icons) are recognized by the browser.

Option B: Loading as an Unpacked Chrome Extension

  1. Open Chrome and go to chrome://extensions.
  2. Enable "Developer mode" (usually a toggle in the top right).
  3. Click "Load unpacked".
  4. Navigate to and select your chrome-presentation-pwa directory.
  5. The PWA should now appear in your extensions list. You can then launch it.

Step 6: Host Your PWA with GitHub Pages (or Any HTTPS Server)

To make your PWA publicly accessible, you'll need to host these files on a web server. It's crucial that your hosting environment supports HTTPS for your PWA to function correctly and be installable by users.

Hosting on GitHub Pages

This is a simple way to host static websites directly from your GitHub repository.

  1. Create a New GitHub Repository:

    • Go to [github.com](https://github.com/) and log in.
    • Click the "+" sign in the top right corner and select "New repository."
    • Give your repository a name (e.g., my-chrome-pwa).
    • Choose whether it's public or private.
    • Do not initialize with a README, .gitignore, or license.
    • Click "Create repository."

  2. Push Your Local Project to GitHub:

    • Open your terminal and navigate to your chrome-presentation-pwa directory.
    • Initialize a new Git repository: 
      git init
    • Add all your files: 
      git add .
    • Commit your changes: 
      git commit -m "Initial PWA setup"
    • Add your newly created GitHub repository as a remote: 
      git remote add origin https://github.com/YOUR_GITHUB_USERNAME/YOUR_REPOSITORY_NAME.git
      (Replace YOUR_GITHUB_USERNAME and YOUR_REPOSITORY_NAME with your actual GitHub username and the name of the repository you just created).
    • Push your code to GitHub: 
      git push -u origin master
      (Or main if that's your default branch name).

  3. Enable GitHub Pages:

    • On your GitHub repository page, click on "Settings."
    • In the left sidebar, click on "Pages."
    • Under "Source," select the branch you pushed to (usually main or master).
    • Click "Save."
    • GitHub Pages will now build and deploy your site. It might take a few minutes. You'll see a message indicating your site is published at a URL like https://YOUR_GITHUB_USERNAME.github.io/YOUR_REPOSITORY_NAME/.

Hosting on Any Other HTTPS Web Server

If you prefer to host your PWA on a different platform (like Netlify, Vercel, Firebase Hosting, or your own web server), the process is generally similar:

  1. Upload the entire contents of your chrome-presentation-pwa directory to the root of your web server's public directory.
  2. Ensure your web server is configured for HTTPS. Most modern hosting providers offer free SSL certificates (e.g., Let's Encrypt). If you manage your own server, you'll need to set this up.
  3. Access your PWA via the URL provided by your hosting service.

You have now successfully downloaded, modified, and learned how to host your Chrome PWA! Once deployed, users can visit your PWA's URL in Chrome, and if it meets the PWA criteria, they'll see an "Install app" option in the address bar or browser menu, allowing them to add it to their home screen or desktop.