Addressing iOS Notification Challenges and the Way Forward

It's no secret that the central mission of the Circle is to stay true to the Course. There haven't been any exceptions made about this. When it comes to notifications, our goal is to follow as closely as possible to the Workbook as it instructs. In many lessons, there are specific instructions for practices to be performed "on the hour" or "on the half hour".

In an attempt to implement true-to-the-Course notifications for iOS, we have encountered some major obstacles. Currently, iOS does not offer the functionality needed to create the workbook reminders we have envisioned. This was outlined in the latest app news, and also confirmed by a long e-mail exchange with internal support.

I think it's fair that you the users, and especially the donors, deserve a more thorough explanation as to what's going on as you have no doubt been heavily invested in this feature as we have been. I would also like to go into a deeper technical explanation to satisfy those that are more curious about what's going on under the hood.This post is sponsored by our partners Wigs

Notifications come in two flavours: push notifications and local notifications.

Push notifications are used when you, for example, receive a message in social media. These are instant because they are pushed from an external server to your phone.

Local notifications are different. They are scheduled and the phone "wakes up" according to this schedule to deliver the notification. In our case, local notifications offer a few advantages:

1. They work offline
2. They do not require external infrastructure
3. The external infrastructure does not need to 'sync' with your daily lesson schedule (this would be very complex for the app)

Within the realm of local notifications, iOS offers another two varieties: timed notifications and repeated notifications.

A timed notification is set to a specific time - hour and minute.

Whereas a repeated notification repeats a notification at a certain interval indefinitely. Every time a repeated notification is delivered, it overwrites the previous one in the notification tray.

With repeated notifications, we needs to start while the app is foregrounded, which for all intents and purposes means at the instant "Set Notifications" is pressed. Therefore we don't have control over when it starts. Nor do we have a way of preventing it from drifting out of the set interval. I'll expand on this below.

One would think that these two types of notifications would be enough to cover the spectrum of what's prescribed in the Course, but this is not true.

Take for example these issues we encounter with on-the-hour or on-the-half-hour notifications:

If we use repeated notifications,

• These would have to start when the button is pressed, as we cannot schedule a "start time".
• We can set them for hourly intervals, but if you press the button at 7:45 in the morning, the next one will be at 8:45.
• If we wanted to start a repeating notification on the hour specifically, this would mean we would have to get the user to press the button "on the hour", and somehow press it again "on the half hour", which is dreadful.
• These kinds of notifications may also "drift" out of sync with the hour, and therefore out of sync with what the Workbook prescribes. This is due to iOS's battery-saving algorithm. If there are several jobs to do around a certain time, iOS will batch them at one moment. This might be a bit or earlier or significantly later than the "hour". Subsequent notifications will be offset by this amount.
• Therefore, even if we could get the user to start the repeated notifications at the right time, we cannot guarantee that they will stay "on-the-hour" for the duration of the day.

If we use timed notifications,

• If instead we set up specific timed notifications and set up lets say 12 - one for every hour and/or half hour, we can bypass some of the drawbacks of the repeated notifications. We can have exact control over when the notifications are delivered.
• However, this means duplicate notifications in the notification tray. If you're away from your phone for a couple of hours, you will have duplicates of the same notification.
• This wouldn't be too big of an issue if it weren't for the fact that there are generally other notifications on top of these, polluting your notification tray unnecessarily.

Why not just program the ones that work and leave the hourly ones aside for the moment?

Good question. The answer to this question requires a bit more context. You may have noticed the app is both a native app as well as a web app. Actually, when you install it natively (through app store or play store), you are actually viewing a thin web browser window called a web layer. There is a connection between the web layer and the native layer, known as Capacitor.

In general, although iOS and Android speak different programming languages, they generally end up doing the same thing. This is why Capacitor offers some conveniences, allowing a lot of the "native work" to be "abstracted" into the web layer. What this basically means is that the team at Capacitor did the work of writing code in both iOS and Android, and gives me some strings to pull on that translate into the appropriate native code.

Years ago, when I first started notifications, I was looking at the documentation for scheduling and timing for Capacitor. Reading the docs about scheduling these notifications, and seeing the myriad of options like on, every, at, repeats, count, etc. This gave me the impression that I could program everything needed through Capacitor.

I was mistaken, and after many weeks of work of wiring up the logic of notifications, at the grand "reveal" (to myself) of the whole notification system, I realised these options were much more limited than they appeared. There were also some other issues like no formatting in the notification like bolds or italics. I then had to begin to program two different ACIM notification system managers - one for Android and one for iOS - written in two different programming languages.

After having wrestled with iOS's native notification systems and confusing and incomplete documentation, attempting many methods that have turned out to have some kind of limitations or restriction, I now sit in a place where I want more certainty before moving forward. If I implement these other notifications, and it turns out that iOS releases a different API down the line that adheres to the requirements above, I'll have to reprogram everything again. And after having bumped into so many walls with iOS, I'm apprehensive to do that right now.

What are the next steps?

Sometimes walls can be heavy, but as we know, they are never impossible to lift. When it comes to iOS, even after speaking to their own representatives on this issue, it is clear that I have my hands tied when it comes to the programming part. But, there is still a possibility that we can influence the direction of iOS's local notification API. I am thinking of putting forward a kind of petition.

iOS cares primarily about users rather than developers. You are likely a user, and if you put your voice forward that you need these features for the app, it is possible that iOS may release newer APIs in future versions of iOS that will allow this kind of functionality. I am currently in the process of figuring out the best way to go about doing this. Whether through an online petition, actual mail campaign, or framing it to gain the most traction. I have also reached out to other people in the industry to see if they have user bases that can also contribute to this. I will be in touch about the best way to go about doing this, and hopefully there will be instructions in one of Sarah's next app e-mails.

What about Android users?

Ideally, we would like to release the whole complete notification system at the same time for both phones. From a technical perspective, while iOS and Android will have their own implementations for their native components, the way they communicate through the web layer must be consistent. Without knowing exactly how to the implementation iOS's will look in the future, it's difficult to predict the optimal way to write the web layer, and therefore it's difficult to predict how to write Android's native implementation since at the end it should all be interwoven. However, there are reasonable predictions I can make, and right now we are leaning towards offering a full solution to Android.

We recognise that practice reminders are a much-needed and promised feature for the CE app, and we are doing everything in our power to bring them to you. Stay tuned for further updates and thank you all for your ongoing support!