← iOS

Testing Push Notifications and Deep Linking

Basics

Testing push notifications requires access to OneSignal. There is a Banno organization, and individuals can be added to it upon request.

Within the Banno organization, there are OneSignal apps for each bundle ID in the grip-assets repository. Searching by name is the quickest option, but the OneSignal app ID from a given properties.json file from grip-assets can be loaded directly at a URL of the following form:

https://app.onesignal.com/apps/<onesignal-app-id>

App Configuration

On the client side, three details have to be adjusted, all of which come from the properties.json file for the institution of interest:

  1. In Banno/Banno/BNBuildConfig.plist, modify institutionID to use the value of the institutionId JSON attribute.
  2. Also in BNBuildConfig.plist, modify oneSignalAppID to use the value of the onesignal_app_id JSON attribute.
  3. In the Xcode project, modify the Bundle Identifier for the Banno target to use the value of the bundle_identifier JSON attribute.

It is necessary to install the app on a physical device to receive any kind of notification. This is because OneSignal does not yet support sending notifications to the iOS simulator.

IMPORTANT: For this to work, the application binary has to be signed. Depending on which bundle ID has been set, the development team may need to change. The default is 46YH3KR4UA for the Tactical 8 Technologies team. Bundle IDs associated with the iPay Technologies team will require setting the team (DEVELOPMENT_TEAM in Banno/Banno.xcodeproj/project.pbxproj) to HB7SFHWAR4. Your Apple ID must be a member of the team with the Developer role and have access to developer resources.

The app can have all necessary settings applied using a script in the banno-ios repository called Build/apply_institution.py. It requires the same GitHub personal access token setup used for applying the institution theme imagery at build time. With the desired institution ID, it can be run this way from the root of the banno-ios repository clone to configure for UAT testing:

./Build/apply_institution.py <institution-id>

Consider YourFI (institution ID 8eac4943-acd6-40d6-b9a0-ecba52bc35ef) as a specific example. The default state of the app is to build a “fake” YourFI app that is really more like YourFI 2 (institution ID 89ad3ca0-37a8-4d90-a5ae-9bf4cdbefda2) except for the institution ID. (Yes, this is not great.) To produce a fully configured UAT-connected YourFI app, first do the following:

./Build/apply_institution.py 8eac4943-acd6-40d6-b9a0-ecba52bc35ef

Then, build and run the app as normal from Xcode. Everything about the produced app will be configured for YourFI on UAT: bundle ID, OneSignal app ID, app name, app groups, theme imagery—even the Apple-assigned unique ID of the app for App Store access.

To configure for production testing, use the following form:

./Build/apply_institution.py --production <institution-id>

In so doing, it is possible to produce a build that would be virtually identical to what gets submitted to the App Store.

To apply overrides for the alpha or the qa-uat group, use the following form with the desired group name:

./Build/apply_institution.py --group <group-name> <institution-id>

Short versions of the --production and --group command line arguments are available. To see all usage details, do the following:

./Build/apply_institution.py --help

To change to a different institution ID, it is necessary to undo the changes first. Be careful as the following will undo every unstaged change to the repository clone.

git checkout -- .

The apply_institution.py script makes every adjustment needed to configure the app for the desired institution. That includes changing the app bundle name; the app product name; and the entitlements for both the app and the notification service extension. It is basically like producing a TestFlight build for yourself without having to wait for one to be available on App Store Connect. (This script is used as part of making IPAs, and using it for development builds is a way to exercise a critical part of the release build process.)

Sending a Test Push

With OneSignal access, a test push can be sent for the OneSignal app matching the iOS app configuration applied above. Do the following:

  1. Load the OneSignal app of interest.
  2. Click the New Push button.
  3. Compose the message.
  4. Choose to send to a test device (the SEND TO TEST DEVICE) button below the iPhone mockup) or to all the installed apps that have notifications enabled (the CONFIRM button at the bottom of the page). In general, it is best to send to a test user.

A OneSignal test user is identified by the player ID. In the iOS app log output, look for something similar to the following:

Updating push registration for ID <uuid>

This is logged every time a sync is run. It may be necessary to add a new test user, and the player ID is how to find the desired device in the list of registered users.

A test push will not be formed in the way that the app expects in terms of “extra” details. At minimum, though, a test push can be used to confirm that the iOS app can receive notifications at all.

Sending a Real Push from UAT

When signed in to the VPN, a command similar to the following can be used to send a notification to a specific user. This applies to UAT institutions only. There are numerous endpoints that can be used. The example payload below is for the low balance notification.

curl --location --request POST 'http://notification-authoring.banno.svc.cluster.uat/v1/notifications/author/push/queue-low-balance' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "userId": "<user-id>",
  "accountId": "<account-id>",
  "balance": "1.00",
  "lowBalanceValue": "1.50"
}'

Deep Linking

Beyond push notifications, the apply_institution.py script sets things up for institution-specific deep linking, but only if the institution properties.json file contains the bannoOnlineDomain detail. If it does not, then deep linking will be disabled. This is exactly what happens when making a release build of the app.

Please note, for the app deep linking (i.e. Universal Links) to properly work, the apple-app-site-association file must contain the assoicated link details (for example https://devbank.banno-uat.com/.well-known/apple-app-site-association). If this file needs to be updated, it is maintained by the Prism team.