Aspen Mobile Setup

Aspen Web App Setup

Overview

Aspen Progressive Web Application (PWA) is built into Aspen Discovery.  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

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.   It must be 512 x 512 pixels, and in PNG format.

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. 

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

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 a legacy field, and not used anywhere.  Put any value you wish; it'll be removed in a future version.
  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 configurations are working properly, install Aspen Mobile directly through the browser.  Click here for browser-specific instructions. App Store entries are not a requirement for Aspen Mobile! 
Idea
Not sure if Aspen Mobile is working?  Try visiting <your Aspen URL>/pwa-icon.png in your browser.  If you get an image file, then your setup is working correctly!

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.