|
| 1 | +# Push Notifications Troubleshooting Guide |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Common Issues |
| 6 | +1. **Notifications not received on iOS or Android.** |
| 7 | +2. **Notifications received, but they do not open the correct screen.** |
| 8 | +3. **Push notifications work on one platform but not the other.** |
| 9 | +4. **Receiving errors when sending push notifications manually.** |
| 10 | + |
| 11 | +## General Debugging Steps |
| 12 | + |
| 13 | +### 1. Verify Build and Device Registration |
| 14 | +- Ensure that the device has the correct build version of the app: |
| 15 | + - **Android:** Version should be at least 3.1.0.x. Check via `Play Store >> Profile Icon >> Manage apps & device >> Acorn >> About this app`. |
| 16 | + - **iOS:** Version should be at least 3.1.0 (x). Check via TestFlight or App Store. |
| 17 | +- Confirm the device is registered to receive push notifications: |
| 18 | + - Only one device can be registered for push notifications per patron account. The last device to log in will be the active one. |
| 19 | + |
| 20 | +### 2. Check Notification Permissions |
| 21 | +- Ensure that notifications are enabled for the app: |
| 22 | + - **iOS:** Go to `Settings >> Notifications >> Acorn Catalog` and allow notifications. |
| 23 | + - **Android:** Ensure notification permissions are granted in `Settings >> Apps >> Acorn >> Notifications`. |
| 24 | + |
| 25 | +### 3. Test Push Notifications Manually |
| 26 | +- Use `curl` to manually send a push notification to the device: |
| 27 | + - Obtain the push notification token by querying the database. |
| 28 | + |
| 29 | + ```sql |
| 30 | + SELECT s.value AS "Push Notification Token" FROM actor.usr_setting s |
| 31 | + JOIN actor.usr u ON u.id=s.usr |
| 32 | + WHERE usrname='username' and s.name='hemlock.push_notification_data'; |
| 33 | + ``` |
| 34 | + |
| 35 | + - Use the following command, replacing `$token` with the actual token: |
| 36 | + ```bash |
| 37 | + curl -F token="$token" -F title="New Message" -F body="Test Notification" -F type=holds -F debug=1 http://localhost:8842/send |
| 38 | + ``` |
| 39 | + |
| 40 | +- Check for errors: |
| 41 | + - If you see "Auth error from APNS or Web Push Service," ensure the APNs Authentication Key is correctly configured in the Firebase project. |
| 42 | + |
| 43 | +### 4. Verify `hemlock-sendmsg` Daemon Status |
| 44 | +- Ensure the `hemlock-sendmsg` daemon is updated to the latest version. |
| 45 | +- Restart the daemon after pulling the latest code: |
| 46 | + ~~~bash |
| 47 | + git pull |
| 48 | + make |
| 49 | + sudo make install |
| 50 | + sudo systemctl restart hemlock-sendmsg |
| 51 | + ~~~ |
| 52 | +- Check the daemon output for correct startup and notification processing: |
| 53 | + - Example of startup output: |
| 54 | + ~~~ |
| 55 | + 2024/09/11 15:03:34 INFO starting hemlock-sendmsg date=2024-09-10 commit=03031fad |
| 56 | + ~~~ |
| 57 | + - Example of notification processing output: |
| 58 | + ~~~ |
| 59 | + 2024/09/05 11:10:02 INFO GET /send result=ok code=200 username=xxx title="xxx" type="holds" body="xxx" token=xxx |
| 60 | + ~~~ |
| 61 | + |
| 62 | +### 5. Confirm Action Trigger Configuration |
| 63 | +- Ensure that the action triggers are correctly configured in Evergreen: |
| 64 | + - Example action trigger for hold notifications: |
| 65 | + ~~~xml |
| 66 | + <Parameters> |
| 67 | + title Hold Ready for Pickup |
| 68 | + type holds |
| 69 | + body You have an item ready for pickup. |
| 70 | + token [%- helpers.get_user_setting(user.id, 'hemlock.push_notification_data') %] |
| 71 | + username [%- user.usrname %] |
| 72 | + debug 1 |
| 73 | + </Parameters> |
| 74 | + ~~~ |
| 75 | +- Confirm that the `type` parameter is correctly set to target specific screens (`holds`, `checkouts`, etc.). |
| 76 | + |
| 77 | +### 6. Verify Firebase and APNs Configuration |
| 78 | +- Ensure that the Firebase project has the correct APNs key and Team ID set up. |
| 79 | +- If notifications work for some types but not others, ensure that all notification types are registered correctly in the app's source code. |
| 80 | +
|
| 81 | +## Specific Troubleshooting Steps for Common Scenarios |
| 82 | +
|
| 83 | +### A. iOS Notifications Not Working |
| 84 | +1. Ensure the device is the last one to sign in. |
| 85 | +2. Verify the APNs configuration in Firebase. |
| 86 | +3. Test manually with `curl` and check for errors related to authentication. |
| 87 | +
|
| 88 | +### B. Android Notifications Not Working |
| 89 | +1. Verify that the app build is up-to-date. |
| 90 | +2. Check notification channels registered in the app's settings. |
| 91 | +3. Ensure the daemon sets the `type` correctly for selective disabling by channel. |
| 92 | + |
| 93 | +### C. Notifications Open Incorrect Screens |
| 94 | +1. Ensure the `type` parameter in the action trigger is correct. |
| 95 | +2. Verify that the app's code correctly handles the `type` parameter and routes to the appropriate screen. |
| 96 | +
|
| 97 | +### D. Errors When Sending Notifications Manually |
| 98 | +1. Check for missing or incorrect parameters in the `curl` command. |
| 99 | +2. Ensure that the `hemlock-sendmsg` daemon is updated and configured properly. |
| 100 | +
|
| 101 | +## Additional Notes |
| 102 | +- 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](https://github.com/kenstir/hemlock-sendmsg/blob/main/README.md#collecting-metrics) for more details. |
0 commit comments