Aspen Mobile Setup

Aspen Web App Setup

Overview

Aspen Progressive Web Application (PWA) is built into Aspen Discovery. It is essentially a shortcut that will save on devices as a screen icon. It enables many “app” features, like Push Notifications, on any mobile or desktop device, without having to manage a separate app codebase and upgrade cycle.  Configuration changes made in Aspen Discovery are instantly available to all users.

Users can install Aspen Web App via their web browser for free. Once this is configured, users will see a prompt to install when they visit the Aspen URL on a mobile device. To get your Aspen Web App into the App Stores, you’ll need to either build and submit it yourself (the site pwabuilder.com has guidance on how to do this), or contract for this service with ByWater. Once accepted, you should only need to upgrade the app itself infrequently.

Prerequisites

Notes
You’ll need Aspen 26.05+

If you haven’t already, go to DB Maintenance from the Aspen Administration > System Administration and run the database updates for Aspen PWA. If there are no updates listed, then your Aspen system is already up to date. 

Setup Steps

Contact ByWater Support

ByWater will set up Firebase to allow notifications in the Web App. 
Please indicate whether you would like ByWater to add the library's Aspen Web App to the Google Play Store, as is a contracted service and requires special configuration. 

Notes
Note: Some may wish to set up Firebase on their own. If so, find Firebase setup instructions below. 

Enable the Aspen Progressive Web Application (PWA) module

  1. In Aspen Admin, go to the modules under the System Administration section
  2. Find Aspen Progressive Web Application (PWA) and make sure the enabled checkbox is checked for the module
  3. Save

Add Permissions for Aspen PWA

  1. Again in the System administration section of Aspen Admin, this time go to Permissions
  2. Choose your role at the top (likely opacAdmin but this could be any role you wish to do this setup)
  3. Find the Aspen Progressive Web Application (PWA) section and enable all the permissions there for the role you are using to do this initial setup
  4. Be sure to scroll to the bottom of the page and hit Save changes

Create a Theme

From Aspen Administration, navigate to Themes and Layout > Themes and add a new theme or duplicate the library theme. Give it a name that will identify it as the theme used by the web app. The only element that needs to be configured is the app image. Add this image in the Aspen LiDA section. 

Add Settings in Aspen

Begin this step once you have received Firebase information

From Aspen Administration, navigate to Aspen PWA > Settings > Add New.
  1. Name, Short Name, and Description fields are up to you.  These values will be seen by patrons. It is best practice to use values with no spaces for Name and Short Name.
  2. Add the name of the Theme created in the previous step.
  3. For Manifest ID, use the url for your website backwards. (i.e. your-library.example.com becomes com.example.your-library)
  4. Slug is also up to you; it's not used anywhere and will eventually be removed.
  5. The SHA-256 Cert Fingerprint field is only necessary when putting an app in the Google Play store and can be updated with the value you get from Google so they can verify that your website is what is supposed to be in the app.
  6. You will get values for all of the Firebase settings from ByWater unless you have configured it yourself. 

Testing Aspen Mobile

You can visit your library's Aspen Discovery URL, and if all your settings are in place, get an "Install" prompt on mobile devices.  App Store entries are not a requirement for Aspen Mobile! Click here for browser-specific instructions.

To test push notifications:
  1. First, identify a test patron account, and under My Account -> Notification Preferences, set "Allow Notifications" to ON
  2. From Aspen Admin -> Aspen Progressive Web Application(PWA) -> Notification Testing Tool, enter the above users barcode or username and click the "Find Devices" button (pressing 'enter' is not the same as clicking in this case)
  3. If any devices have been registered to receive notifications, they will be listed.  You can select the device, enter a subject and body, and click "Send Notification".
  4. If everything is configured properly, your device should receive a push notification within a few seconds

Set up Firebase

Alert
ByWater Solutions will do the following steps unless the library prefers to use their own Firebase. 

Firebase is a Google service that allows for the delivery of push notifications to partner devices.

  1. Create a new Firebase project (https://console.firebase.google.com/?pli=1).  If you have an existing firebase project you want to re-use, you can skip this step
  2. Once you have your project, create a new app within the project
    1. choose “web” (the </> icon)
    2. give it a nickname
  3. At this point, you should have a block of code with a variable called "firebaseConfig" displayed. Save those values to add to your Aspen Settings later
    1.   apiKey ->Firebase API Key
        authDomain -> Firebase Authorization Domain
        projectId -> Firebase project ID
        storageBucket -> Firebase Storage Bucket
        messagingSenderId -> Firebase Messaging Sender ID
        appId -> Firebase application ID
  4. In the Settings for your new app, go to the Cloud Messaging tab and click the “Generate key pair” button in the “Web Push certificate” section
    1. Save the value under "Key pair." This will go in the Aspen Progressive Web App setting field Web Push Certificate (VapidKey)
  5. On the same tab, click “Manage service accounts”
  6. On the page that opens, click the three dots under Actions in the table row and choose “Manage keys”
  7. From here
    1. choose from the add key dropdown “Create new key”
    2. Leave “json” checked
    3. Hit “Create” and a file will download
    4. The contents of this file will populate the Aspen PWA Setting fields Service Account and Confirm Service account. Open the file up in a text editor and copy the values.
  8. You can access these values again later in the General Settings section for the app you created in Firebase. Scroll to the bottom of the screen.

    • Related Articles

    • Installing the Aspen Web App (Aspen Mobile)

      Before installing, please see this article detailing how to configure Aspen Mobile from your Aspen Discovery interface. Browsers The Aspen Progressive Web App, or Aspen Mobile, will work best on the following browsers and operating systems. Using ...

    • Aspen Mobile FAQ

      Aspen Mobile is a Progressive Web App. It was built to be installed directly to your device or downloaded as an app, and feature push notifications. Aspen Mobile was designed to provide Aspen Discovery users with a stable, responsive version of the ...

    • Preparing for Library Closures in Aspen Discovery

      Libraries sometimes have to close for different reasons. Here are the steps to prepare Aspen for a closure. Many of these steps are significantly more complicated for multi-branch or multi-library systems. We've attempted to note those areas below, ...

    • Accessibility Compliance for Aspen

      Aspen Discovery and Aspen LiDA's goal is to comply with level 2.1 AA standards of the Web Content Accessibility Guidelines (WCAG). While accessibility guidelines are meant to ensure equal access to online content, these standards actually benefit all ...

    • Integrating Quipu with Aspen & Koha

      Aspen supports Quipu eCARD (self-registration) and eRENEW (patron account renewal). First, decide whether your library would like to have Quipu's form display in Aspen or embed it on your website. Aspen setup If you want to keep the form on your ...