Skip to main content

Push Notifications Troubleshooting Guide

This guide provides steps to troubleshoot issues with push notifications using the hemlock-sendmsg daemon. Follow these steps to identify and resolve problems with notifications on both iOS and Android devices.

General Debugging Steps​

Verify App Version​

Details

Ensure that the device has the correct build version of the app:

  • Android: Version should be at least 3.1.0.x. Check via Play Store >> Profile Icon >> Manage apps & device >> Acorn >> About this app.
  • iOS: Version should be at least 3.1.0 (x). Check via TestFlight or App Store.

Only One Device per Account​

Details

Only one device per patron account can be registered for push notifications. The last device to log in will be the active one.

Check Notification Permissions​

Details

Ensure that notifications are enabled for the app:

  • iOS: Go to Settings >> Notifications >> Acorn Catalog and allow notifications.
  • Android: Ensure notification permissions are granted in Settings >> Apps >> Acorn >> Notifications.

3. Test Push Notifications Manually​

Details
  • Use curl to manually send a push notification to the device:

    • Obtain the push notification token by querying the database.

      SELECT s.value AS "Push Notification Token" FROM actor.usr_setting s
      JOIN actor.usr u ON u.id=s.usr
      WHERE usrname='username' and s.name='hemlock.push_notification_data';

    • Use the following command, replacing $token with the actual token:

      curl -F token="$token" -F title="New Message" -F body="Test Notification" -F type=holds -F debug=1 http://localhost:8842/send
  • Watch for errors in the hemlock-sendmsg output: 
    sudo journalctl -fu hemlock-sendmsg

Verify Latest hemlock-sendmsg Daemon​

Details
  • Ensure the hemlock-sendmsg daemon is updated to the latest version.
  • Restart the daemon after pulling the latest code: 
    git pull
    make
    sudo make install
    sudo systemctl restart hemlock-sendmsg
  • Check the daemon output for correct startup and notification processing:
    • Example of startup output: 
      2024/09/11 15:03:34 INFO starting hemlock-sendmsg date=2024-09-10 commit=03031fad
    • Example of notification processing output: 
      2024/09/05 11:10:02 INFO GET /send result=ok code=200 username=xxx title="xxx" type="holds" body="xxx" token=xxx

Confirm Action Trigger Configuration​

Details
  • Ensure that the action triggers are correctly configured in Evergreen:
    • Example action trigger for hold notifications: 
      <Parameters>
        title Hold Ready for Pickup
        type holds
        body You have an item ready for pickup.
        token [%- helpers.get_user_setting(user.id, 'hemlock.push_notification_data') %]
        username [%- user.usrname %]
        debug 1
      </Parameters>
  • Confirm that the type parameter is correctly set to target specific screens (holds, checkouts, etc.).

Specific Troubleshooting Steps​

General Scenarios​

iOS Notifications Not Working​

Details
  1. Ensure the device is the last one to sign in (force quit the app and sign in again).
  2. Test manually with curl and check for errors in the hemlock-sendmsg output.

Android Notifications Not Working​

Details
  1. Ensure the device is the last one to sign in (force quit the app and sign in again).
  2. Verify that the app build is up-to-date.
  3. Check notification channels registered in the app's settings.
  4. Ensure the daemon sets the type correctly for selective disabling by channel.

Notification Opens the Wrong Screen in the App​

Details
  1. Ensure the type parameter in the action trigger is correct.
  2. Verify that the app's code correctly handles the type parameter and routes to the appropriate screen.
  3. (Android only) Verify the app is registering the channel (search for "notification_channel_register_checkouts_channel").

Errors in the hemlock-sendmsg output​

"Auth error from APNS or Web Push Service"​

Details
  1. Ensure the APNs Authentication Key is correctly configured in the Firebase project.

Errors in the app​

"500 Error" after signing in​

Details
  1. Ensure the User Setting Type is created. After signing in, the app tries to store the push notification token in the database, and it gets this error if the User Setting Type is missing. See Push Notification Setup Guide.

Additional Notes​

  • The hemlock-sendmsg daemon filters out requests with an empty token parameter, so it does not attempt to send a push notification to a patron that does not use the app. The EmptyToken metric tracks the number of such requests. Refer to the README for more details.