twocentstudios

Introducing Eki Bright 2.0

Sun, 18 Jan 2026 16:16:39 -0600

Eki Bright 2.0 is available today.

Eki Bright app icon

Eki Bright is the fastest way to access station timetables for the Tokyo metropolitan area.

The original design for the Eki Bright app evolved out of the initial use case of configuring Widgets, but steadily grew to support searching, nearby stations, DIY routing, and Live Activities.

For Eki Bright 2.0, the goal was to optimize the app for how I’d actually been using it and how its users had told me they use it.

Home screen evolution from v1.0 to v2.0

The main focus is now nearby stations, which I found to be 95% of my usage over the year since its first release. In many cases, you’ll see the exact station timetable you want in less than a second after opening the app. Other nearby stations are a quick scroll at your resting thumb position, and order based on view history and distance from your current location.

Nearby stations screen with scrolling

From here, it’s super easy to start a new DIY route by tapping your departure train time, then tapping the route icon of your arrival station.

Creating a DIY route by tapping departure time and arrival station

The route bar from v1.x has moved to the native tab bar accessory, which automatically expands and collapses.

Route bar in the tab bar accessory

DIY routes now have a full screen view in Eki Bright 2.0. You can see the full route and transfers, and view all stops along your route.

Full screen route view with expanded stops list on the right

It’s easy to compare adjacent departure times. For example, to check whether the next departing local train will actually reach your destination after a later departing express train.

Comparing local and express departure times, the express arrives 7 minutes earlier than the local that departs 3 minutes earlier

Eki Bright remembers your most used route patterns and suggests them on the route screen based on your current location. After a few trips, you don’t need to manually create DIY routes anymore.

Suggested routes based on location and history, departure times updating live

The Live Activity now updates more reliably in the background throughout your trip.

Live Activity on the lock screen

My personal favorite new addition to Eki Bright 2.0 is the station relative direction arrow indicators on the station detail screens. This makes it much easier to orient yourself with the correct direction of a railway at a glance.

Station detail with direction arrow indicators in relation to the center station

The station detail screen now shows train frequencies during different periods of the day.

Train frequencies by time period

The bookmarks and search screens have been separated out into their own tabs. I doubled down on native iOS 26 UI and UX (for better or worse).

iOS 26 liquid glass tab bar with native accessory for the route view

In the search tab, you can now search railways.

Railway search in the search tab

Speaking of railways, the railway detail screen shows the full polyline of the railway.

Railway detail screen before and after with full polyline

I think Eki Bright is the fastest and best way to get around Tokyo for everything but route planning. Local timetables give a serious edge to how fast you can find your next train.

Train Tracker Devlog 02

Thu, 29 May 2025 07:22:00 -0500

It’s been about 6 weeks since the last train tracker devlog.

I’ve been making an iOS app that automatically detects what train you’re riding (in Tokyo) and shows the current/next station in a Live Activity, all without needing to open the app.

Eki Live's Live Activity on the lock screen and Dynamic Island

I’m finally on the cusp of the release of version 1.0 of Eki Live, the christened name of the previous working title Train Tracker. At the end of the last post, I detailed what I thought was next on my TODO list.

Improve the algorithm to determine the correct railway faster, handle transfers, and off-board seamlessly.

Improve the design of the Live Activity.

Remove the debug screens and rework the in-app UI for onboarding, settings, and simple monitoring.

Create branding and add all the required info for the App Store.

I did indeed finish ~all of~ most of these TODOs, but like usual it took a lot longer than I expected. Let’s start with the easy stuff first.

Home UI

The UI for Eki Live is nowhere near as expansive as humble Eki Bright, which has a screen for each resource like station, timetable, railway, bookmarks, nearby station, search, etc. Eki Live is really just one screen, and in the ethos of the app, most users will rarely see it; the app is intended to function as an automatically appearing and disappearing Live Activity.

Eki Live's home screen, en route to Jiyugaoka station

However, there are a few required visuals and functions:

The current railway, direction, focus station, and later stations: a larger, more detailed reflection of the data shown in the Live Activity.
A map with the user’s current location: a confirmation for users that they are where they think they are.
A list of other selectable railway candidates: in the dense railway environment of Tokyo, more often than not there are railways that run parallel for stretches of track. Eki Live defaults to the top ranked candidate based on an algorithmic score that improves with more data, but I wanted to give users the ability to override or lock-in the top candidate at will.
Menu: there are a few functions I wanted to include even if they are rarely used. A permissions checkup screen since Location Services permissions are imperative. A way to reset the algorithm in case it encounters a situation I can’t handle automatically yet. Eventually some other options too like a snooze button or list of alerts.

My previous custom debug screens became outdated and I integrated the debug visuals into a “show stats” option that anyone can enable.

I fell into the trap of over-optimizing the UI because honestly it’s one of my favorite parts of iOS development. I had to keep reminding myself that most users wouldn’t and shouldn’t see this home screen if I had done the rest of my job properly.

Onboarding

Eki Live doesn’t work like a normal app, so I spent more time than I usually do on an onboarding flow when the user opens the app for the first time.

I’m not sure whether I’ve struck the right balance of over-explaining vs. under-explaining, perhaps the former. The main concern was that I need the user to understand the value proposition of the app and why I need such intrusive Location Services permissions. Otherwise, they won’t allow background permissions, the app won’t start up, and they will forget about it and go on with their life.

English support

I was very on the fence about supporting English for the version 1 release, or really at all. Sure, I have English in the underlying station data, but I never got around to fully supporting English in Eki Bright because there just too many screens and too many layout edge cases to deal with for a non-target audience.

For Eki Live, however, I decided that since my UI footprint was low and some of my beta testers preferred English, I would take a day to do a spike and see how much work it would add.

There were a few tough points (Info.plist strings, lots of onboarding string, app extension strings), but the main breakthrough was simply using the compressed width system font. This got the width of the romaji station names down to near the width of the kanji versions. The amount of layout tweaks was minimal.

I think English support makes more sense in Eki Live because in theory I could target overseas tourists as potential users. By design, Eki Bright doesn’t make sense as an app for tourists.

Eki Live's home screen in English and Japanese localizations

Algorithm improvements

After finishing all the above essentials for app release, I pushed a Test Flight v0.1, send it out to some beta testers, and then went out and took a few train rides.

It was still a little exciting when, after riding about a stop and a half, the Live Activity would suddenly pop up showing the next station. However, with my critic hat on, I was becoming less bullish:

It didn’t feel magical having to wait so long for Eki Live to finally conclude I was on a train and appear in my Dynamic Island, especially for short rides.
It didn’t feel magical that the app couldn’t differentiate between the Yamanote Line and the Keihin-Tohoku Line, even after they’d split at Shinagawa.
It didn’t feel magical that the app couldn’t differentiate between the local-like Keihin-Tohoku Line and the express-like Tokaido Line.

I was at a crossroads in early May: do I release the app as-is or do I improve the train tracking algorithm?

At first, it wasn’t a decision I actively made. While I waited for Test Flight review I wanted to do a spike to get a feel for how much work it would take to improve the algorithm.

At that time I was using only station locations as my main data source for determining which railway and direction the user was riding. In one way this was a strength because it meant I could more easily expand the scope of the app in the future to support all of Japan or even other countries.

Using only station locations was a weakness for accuracy and immediacy though. Although it’s much more difficult to obtain and maintain, having the full outline of the geopoints that make up a railway as it traverses between stations would in theory enable boosts in both detection accuracy and immediacy.

Station geopoints (large yellow dots) vs. railway geopoints (small white dots) for the Tsurumi line

The easiest way to understand the limitations of using only station data is by looking at the eastern railway corridor between around Yohohama station and Tsurumi station:

Parallel railways in the south eastern corridor from Yokohama to Tsurumi station as shown on minitokyo3d.com

For this stretch, there are 8 or so railways that run parallel for some portion before branching off. The Tokaido is the most express, only stopping at Yokohama and Kawasaki (further north of Tsurumi). Without supplementing the station data with additional data showing the relationships between the stations and railways, it would be impossible to determine the Tokaido was even in the list of candidates for trains the user is aboard.

I realized that having the railway geopoint data wouldn’t solve all the problems with the algorithm, but it could raise the limit of possibility for speed and accuracy of the algorithm.

The problem was that I didn’t immediately have a source of data for all railway geopoints. I started looking for options.

The obvious first attempt was using the railway geopoint data included in the existing dataset I was using. However, this data was optimized for another use case and after a couple hours of combing through a multi-megabyte JSON file, I was stumped at how to parse it into the simple format I needed: ordered geopoints associated by railway.

The most promising second option was Open Street Maps (OSM). It checked a lot of boxes: the data was free, continuously updated, open to updating from anyone, included all data in Japan and much of the rest of the world, included stations, railways, and railway geopoints, and had a robust query language and tooling.

I did a spike and got pretty far in transforming the data into the format I needed from OSM. I spent days writing custom fetch queries and building tooling to evaluate the results.

A hard-won query to Open Street Maps to fetch all station and railway data in Japan

I built a SwiftUI Preview to show random railways in the parsed OSM database to help me spot check the data:

In the end, the data was just too raw for my use case. Station and railway names and colors were completely non-standardized across the dataset. The accuracy of railway geopoints would have to be crosschecked one-by-one. I realized it would take weeks or months of manual work to get to the point where the data could be trusted enough to rebuild as the foundation of the app.

And I hadn’t even started rewriting the algorithm yet.

I was about to give up when I made one last attempt at parsing the data from my original source. With some LLM help, I finally cracked the parser and with a few revisions and some more custom tooling, I finally had a reliable source of railway geopoint data to use in the algorithm.

My idea for the new algorithm was to expand on the scoring system I had started before. My hypothesis was that by combining all the data I had into a score at a single point in time, then weighting those scores over time, I could manage the complexity and use real data to tweak the scoring system to continuously improve it.

In reality, I still don’t feel confident I have a handle on the complexity yet.

On a positive note, by this point I’d been collecting data from the app for over a month and had a couple dozen trips worth of data I could play back to evaluate the algorithm as I was redeveloping it. This time, I created a macOS app that gave me both greater playback control and more insight into the algorithm.

The paused state of the custom train tracker viewer app I built to develop/debug Eki Live's tracking algorithm

I was still having trouble keeping all the edge cases in my head. Especially how unreliable GPS data is. I’d usually get new coordinates from Core Location once per second, but not always. I’d usually get coordinates within 20 meters of accuracy for above ground lines, but not always, and not when I needed them the most (at station boundaries). I had to make a lot of conflicting decisions about how to fill in gaps in the sensor data. I had to make peace again with using only the sensor data I already had.

At this point, I started to feel the weight of the decision-by-indecision to not ship V1 of Eki Live in early May. I had spent weeks getting the railway geopoint data and maybe a week on the new algorithm, but it still wasn’t obviously better than the existing algorithm I’d threw together in a couple days (that version itself being an evolution of other approaches).

I used this panic and sunk cost fallacy indulgence to power through a couple more days of algorithm tweaking. Hour after hour tweaking constants and watching my ghost trains cruise along the same paths I’d see 1000 times at 10x speed.

There wasn’t one particular breakthrough insight, but soon enough I did finally feel confident enough that I was ready to integrate the new algorithm, sand off the rough edges, and ship another beta.

App Store Marketing

The last piece of the puzzled I’d been putting off was the app icon, marketing images, and App Store copy.

I’d re-learned a couple lessons from previous app icon attempts: an app icon can always can be visually simpler and more distinct and unique.

I had sketched out a quick idea for an app icon in Procreate and used it for the early Test Flight builds.

Procreate-sketched app icon for Eki Live's Test Flight beta releases

It wasn’t quite bold enough. Too much white space.

I riffed on it using vector tools in Figma and ended up with something I like and feels right on my iOS home screen. I like it enough that I might redo Eki Bright’s icon with a variant of the idea.

App icon for Eki Live version 1.0

Similarly for the App Store marketing images, I wanted to go a little more splashy than plain screenshots of the app. There is certainly room for improvement, but I’m hoping a lot of the appeal hits by the third image.

Marketing screenshots for Eki Live version 1.0

I went a little lighter on the App Store description than I previously had, and with a few last checks, Eki Live version 1.0 was ready to ship.

Submission and review

My last bit of panic was realizing that I hadn’t yet got Eki Live through App Store review yet. Each Test Flight review had taken ~3 days but had passed.

I was specifically worried because the main user value of Eki Live is that you don’t have to remember to open the app in order for it to start tracking and appear as a Live Activity. This functionality was disallowed by the ActivityKit APIs until iOS 17.2, when the server-driven push-to-start Live Activity API was released. Push-to-start is my workaround for starting a Live Activity in the background. Although there’s no rule against it in the App Store review guidelines (as far as I know), I was still concerned that Apple would view it as going against the spirit of the API.

In any case, it was something I should have de-risked earlier in the month before I started rewriting the tracking algorithm. I could have submitted an early build even if I wasn’t planning on releasing it yet.

Luckily, App Store approved v1 with little fanfare. For now, Eki Live remains in app review’s good graces.

External Marketing

I’m planning to get more serious about marketing for this app.

For a while, I’ve been thinking about ways to leverage video-based social media (e.g. TikTok, Instagram Reels) as a free-to-play passive advertising channel for my apps, but couldn’t quite figure out the right video format.

While out riding the trains doing a testing run, I was watching Eki Live while periodically looking out the train window onto the sunny Kanagawa suburban countryside. An idea hit that, hey, aren’t there lots of ASMR-like videos on social media of people just riding trains? Hadn’t I already spent hours upon hours staring somewhat mesmerized at Eki Live’s interface slowly ticking by?

I spent a short morning coding up a debug-only accessible interface mod for the Eki Live in-app UI. It displays a live camera feed on the top third of the window, hides some UI, and can start/stop a screen recording using ReplayKit.

Afterwards, I hopped back on a mostly empty afternoon train out to Ofuna and recorded some videos that look like this:

I’m not sure whether these will hit, but I will keep iterating and with some luck have a new passive stream of new users at top of funnel.

Next steps

There’s plenty more on the horizon for Eki Live, but I’m hoping to first get some positive feedback on the direction before investing more development (and research) time. I realize that filling that top of the funnel with effective marketing will be critical in getting enough signal to make a call on whether or not to continue.

If/when I do proceed, my next steps will be:

Improving the ability for the algorithm to detect train alighting and transfers.
Letting users receive alerts when they approach stations of their choice.
Allowing users who don’t want to allow background location permissions to still use the app in a streamlined way.
Enabling support for snoozing background tracking for arbitrary periods (e.g. if taking a vacation, going on a road trip).
Improving the ability for the algorithm to track in underground trains or other low-signal areas.
Add unique visualization of the journey on the map within the app.
Add static timetable support and arrival time estimates.
Add express train support.

Final thoughts

As an indie dev with near infinite freedom, I almost feel like it’s my obligation to take moonshots and experiment in ways that bigger companies can’t.

Starting from the first prototype station departure Widgets of Eki Bright, the timetable lists, the DIY routing feature, and now the live automatic station tracking of Eki Live, I know I’m following this thread somewhere. Whether it’ll be this idea or the next one that lands, my optimism is only growing.

For all who’ve been following along on this journey, thanks for reading. Eki Live v1.0 will be available in the App Store soon.

Train Tracker Devlog

Tue, 15 Apr 2025 12:06:00 -0500

Last month, I took a step back from development of my train timetables iOS app Eki Bright to think about the app in a broader context. I’ve iterated on Version 1 on and off for nearly a year, with use cases emerging out of a basic feature set and evolving with my own daily usage of the app.

Marketing screenshots for Eki Bright v1.7

As a solo developer, it’s difficult to maintain a clear perspective about any given project as it grows. It’s a balance of having a strong vision but carefully allowing reality to gently guide that vision.

All this is to say I spent some time thinking hard about what version 2 of Eki Bright would look like if I started over today. How could I optimize the app for the way I use it now? How can I entice potential users and provide value to new users immediately?

If I stopped with version 1, as a user, I’d be relatively satisfied. I know how to navigate the app and work around the various UX speed bumps and oil slicks to achieve my goal of riding the train system here in Tokyo. I can overlook the problems in the app in ways a random iPhone user wouldn’t. I knowingly stopped short of perfection on a few feature implementations in favor of getting them shipped.

I started to see a vision for how the app could work in a progressive enhancement sort of way for the various use cases I’ve uncovered. I started to see how important it was to do as much heavy lifting in the app as possible. There’s always going to be tension between a “semi-pro” app that gives the user full control while also doing work on their behalf without asking.

A key part of the vision for version 2 that emerged was that Eki Bright can be a lot smarter about understanding the user’s context. With location services, it should be possible to understand whether the user is walking to a train station and wants to know if they should run to get the next train, or whether they’re riding a train and want to know when they’ll arrive at their destination.

I started by segmenting out users into part of an app usage lifecycle:

What would make a iPhone user want to download the app in the first place? Why (if at all) are Tokyo residents unsatisfied with their current navigation apps?
For a first time user, what feature could act as an immediate hook/wedge to provide value with zero setup or explanation and remind them to come back again the next day?
For users who have seen consistent results, what motivation would they have to want to dig deeper and trade some customization effort to get significantly more value out of the app?
For users who have used the app consistently for some time, what features can be enhanced automatically based on usage history?

The features that make up this theoretical system are quite complicated! An interface that adapts to the kind of user, the user’s usage history, and the user’s current context was somewhat of a overwhelming task for me to take on all at once.

Sketching out the lattice of features that could make up Eki Bright v2

So after doing some brainstorming and pencil mockups, I decided to start prototyping a “hook” feature to capture that first segment of users: those who have not downloaded the app and first time users. A feature that is buzzy and attractive to prospective users, and is low touch and requires nearly zero configuration for first time users.

That feature was a train finder.

With the timetable data embedded in the app combined with live location data from the user’s device, I reasoned it should be possible to find the exact train a user was riding if they opened Eki Bright while enroute. If the app could do this, it’d cut down on the work necessary to unlock downstream benefits for the user like:

Checking what time the train will arrive at a destination station
Setting an alarm for the destination station
Checking what other stations are stops along the way
Setting up a DIY route to more thoroughly track a transfer
Sharing a route and arrival time to a friend

At this point, I still intended the train finder feature to be part of Eki Bright. I imagined the user opening up the Eki Bright app along their journey, the app quickly booting up location services and narrowing down the possible railways and trains within a few seconds, and the user being able to quickly take some related actions from there.

My friend David asked “why not have it run in the background so you don’t need to open the app?” I initially balked, not wanting to add background location tracking to Eki Bright due to its potential to be heavy on the device battery. I also couldn’t see how background tracking could streamline the experience beyond reducing that 1-2 second train calculation time with the tradeoff that all this work would waste battery in the cases the user never opened the app. The background activity idea stayed in the back of my mind though.

I started prototyping the algorithm for turning a time-series of GPS coordinates into a railway, a direction on that railway, and ultimately a train.

Thinking through an train tracking algorithm. This particular algorithm turned out to be a dud.

After my first day working on the algorithm, I realized that it was going to require a lot iteration on real data from inside the various trains running all over Tokyo. It wasn’t reasonable to think I could ride a train all day with my iPhone and MacBook debugging the algorithm on live data.

I therefore spent a day creating an app for collecting sessions of GPS coordinates. This has turned out to be a huge boon for development efficiency.

GPS collector app I created and used to get batches of real data from the field

This personal-use GPS Collector app allows me to collect raw data from Core Location in the background and annotate it while riding the various routes I take around the Tokyo area. I divide each trip up into a session, then manually annotate the session with the railway, direction, departure station, and arrival station to serve as ground truth annotations. I allow exporting in GPX format (for usage within Xcode) and as JSON I can import into and decode with other apps.

Seeing the raw data revealed a litany of edge cases my algorithm would need to handle. First off, any train that goes underground is a non-starter for a GPS-reliant system; I’d have to make peace with that fact for now. Core Location data includes speed and heading, which is useful, but is itself a derived value and can be gleaned from other sources. GPS accuracy will sometimes plummet temporarily inside the boundaries of a station and sometimes randomly inside dense city limits. Waypoints are usually returned one-per-second, but sometimes will cut out for seconds or minutes. Some trains go from underground to above ground at least once along their designated route.

I spent a week or so collecting GPS data while working on other apps. I returned to Eki Bright to finish up a first draft of an algorithm that took an entire time-series of GPS data and returned a ranked list of candidates: a railway, the direction on that railway, and the previous and next station.

struct RidingTrainFinderCandidate {
    let railway: Railway
    let direction: RailDirection
    let previousStation: Station
    let nextStation: Station
    // let train: TrainTimetable -- TODO: determine which train
}

I added a debug viewer to visualize how my algorithm was responding to test data as it was played back. It was mostly working! It was also kind of fun to watch the playback. Being able to throw together a view like this for the sole purpose of debugging an algorithm is a huge win for SwiftUI.

I’d hit a development checkpoint, and as cool as my little debug tracker view was, I was still far from a shippable feature that solved a real problem. My next step was extending the algorithm to guess which train the user was on (not exactly a straightforward algorithm to write based on the shape of my train timetable data).

However, I thought back to my friend David’s remark about an app that works in the background. I thought, if I freed myself from the artificial constraints of Eki Bright as it currently existed, how could this algorithm still be useful?

A new vision emerged of an app that solved a much shallower problem:

Sometimes when I’m on a crowded train and I’ve got my headphones in, it’s hard to tell what station I’m approaching. I can’t see the display above the train car door or out the window.
What if I had a Live Activity in my Dynamic Island that updated live as I stopped at or passed each station along a railway?
And what if I didn’t have to manually select what railway I was on and what direction I was going?
Better yet, what if I didn’t even have to open the app and the Live Activity would automatically appear when I was riding a train and disappear when I got off?

If I could pull it off, this feature would be supplemental to any other navigation app. It also has a bit of “cool technology” vibe to it that could entice a download and serve as a conversation piece.

Realizing this new vision came with its own new implementation challenges.

Monitor significant location changes in the background to save battery life, then switch to live location monitoring when moving at train speeds.
Detect the railway and railway direction.
Continuously update which stations have been visited and passed, and which station is next on the railway, even if it’s far away.
Start a Live Activity in the background when confidence in the current railway is high enough.
Update the Live Activity as the user approaches, arrives at, and departs a station.
End the Live Activity and switch back to monitoring significant location changes once the user has alighted their train.

I knew that significant location changes, app background activity, and the way each of these system features interacts with the relatively new (iOS 16+) Live Activities API was going to pose as the biggest risk to executing the seamless zero-touch app experience I envisioned.

I started by creating a new app project and creating a GRDB-backed event logging system. Next, I configured the app to request background location permission. I then created the bones of a location tracking algorithm that preserved battery life. I logged app lifecycle events and events for my location tracking algorithm to ensure I could quickly debug why the app was or wasn’t “waking up” or “sleeping” when I expected it to while out in the field.

Log of app events so I can verify background behavior

The next big task was reimagining my existing railway-finding algorithm for a different system lifecycle. This also meant I needed to pare down my very large train timetable static database for this new use case. I only needed the list of railways and stations. I followed a similar development flow as last time; I created a couple new debug views to view the live GPS waypoints and follow these waypoints on a map alongside the train tracking algorithm outputs.

Raw waypoints view to allow confirmation of incoming data

I started with a version that played back existing GPS data. A dashboard view showed just the user-facing data: the detected railway and “focus” station.

A debug view that plays back previously captured GPS data at variable speed and shows user-facing data

There was also a list view showing the scores assigned by the algorithm and used to determine the ultimate result shown to the user.

The derived scores used by the algorithm to determine what railway and focus station is shown to the user

Then, once I was satisfied with the algorithm accuracy on the snapshot data, I migrated this view to use only live device data.

Watching the algorithm run live was exciting. I felt like I’d hit another checkpoint as the device would wake up and start gathering GPS data in the background, then start showing me which railway I was on and which station was next as soon as I opened it.

Same as above but using live GPS data

With a basic (but admittedly incomplete) tracking algorithm proven, the last piece of the puzzle I needed to de-risk was starting the Live Activity automatically in the background. Unfortunately this is where I hit a frustrating roadblock.

In a careful scan of the lengthy Live Activities documentation, I found the line:

Your app can only start Live Activities while it’s in the foreground. However, you can update or end a Live Activity from your app while it runs in the background.

I confirmed this artificial limitation by attempting it and logging errors in my event tracking database.

LiveActivities Error: The operation couldn’t be completed. Target is not foreground

I felt like requiring the user to open the app each time they wanted the live activity to run – even if it was as simple as opening and immediately closing the app – would be too tedious an ask as a prerequisite for daily usage.

Before I neutered my vision or gave up on the idea entirely, I had one card left up my sleeve. From the documentation:

Starting with iOS 17.2 and iPadOS 17.2, you can also start Live Activities with ActivityKit push notifications.

So a push notification from a server can start a Live Activity without being initiated by a user (as I’d personally experienced with the Apple Sports app), but for some reason it can’t be started by the device itself? Strange, but since my app is already running in the background, I could technically fire off a network request to my own server with the data I wanted to start the Live Activity with and use my server as a pseudo-proxy to start a Live Activity. It feels like a loophole, but perhaps it’s simply a case of an Apple product manager not re-evaluating an initial safeguard after changing a related feature.

Setting up push notifications is involved. I really did not want to be on the hook for maintaining another set of dependencies, but it was the only option left on the table.

Aside: is it possible to send a push notification directly from a device instead of through an intermediary server controlled by the developer? In other words, could the device send a request to the APNS server directly that would send a push notification right back to it? In theory it seems possible, with the big security downside that the p8 key would need to be included in plain text within the app bundle.

I’ll leave the long debug story of how I got push notifications working for another time, but after a couple days of development, I confirmed that I could indeed start a Live Activity from the background using an intermediary server.

Whether or not the App Store app review team considers this to be a permitted workaround is still a huge risk. I’m not sure how I can determine their stance without finishing up version 1 of the app and submitting it for review. Even an unfinished version going through Test Flight review isn’t a guarantee App Store review will also approve.

So this is my current checkpoint: a new app binary with lot of debug screens that starts and updates Live Activities from the background as the user rides a railway in Tokyo.

Prototype version of the working train tracker Live Activity on the lock screen

Prototype version of the working train tracker Live Activity in the Dynamic Island

My plan is to release this app standalone. How it fits into the existing and future Eki Bright vision isn’t yet determined. Perhaps the train tracker app is a free marketing driver for Eki Bright. Perhaps the train tracker app evolves separately from Eki Bright and eventually obsoletes Eki Bright. I’m not sure, but my instinct is to test it in the market in isolation first.

What do I need to finish up in order to ship?

Improve the algorithm to determine the correct railway faster, handle transfers, and off-board seamlessly.
Improve the design of the Live Activity.
Remove the debug screens and rework the in-app UI for onboarding, settings, and simple monitoring.
Create branding and add all the required info for the App Store.

I’m getting faster at getting through this part of the process, but it still takes time. However, I do feel some accomplishment in having semi-efficiently prototyped enough to de-risk this project.

I’m planning to write a few technical posts that detail the caveats of Live Activities once I’m more confident in the robustness of my implementation. Until then.

Eki Bright - Open Data Challenge for Public Transportation 2024 Entry

Tue, 18 Feb 2025 06:22:00 -0600

Eki Bright, my iOS app for train timetables in the Tokyo metropolitan area, uses data from the Public Transportation Open Data Center (ODPT). ODPT recently concluded their 5th contest, Open Data Challenge for Public Transportation 2024.

We look forward to enthusiastic challenges from developers around the globe, aiming to create new services utilizing this data, solve social issues, and drive regional revitalization.

This post is a short retrospective on my participation.

I had already started work on Eki Bright months before the challenge was announced. My aim for the app was always to optimize the daily experience of seasoned train riders in Tokyo. But I decided it wouldn’t hurt to participate in the contest.

The past winners had various themes and target users. Some maps, some straightforward apps like mine, some chat bots. Most weren’t particularly well designed, so I thought the modern iOS look of Eki Bright could help it stand out.

The entry submission deadline was January 17th and the final ceremony was February 15th, 2025. I submitted Eki Bright version 1.7.

Marketing screenshots for Eki Bright v1.7

Unfortunately, the contest submission required a lot more than just the app. I spent valuable time creating a PDF introduction of the app’s features and benefits, a 2-minute marketing video, an instruction manual, an additional 3-minute deck for a pre-judging, and did a 10-minute interview with a few judges.

Introduction deck for Eki Bright

The upside was that, up until this point, I hadn’t really sat down and spent time polishing my marketing message for the app. The app’s use case had evolved over the months of development and it wasn’t clear to me how to sell it to prospective users.

In the end, there were ~500 entries and 17 finalists. I wasn’t selected but attended the final presentations and awards ceremony. I understood based on the finalists and winners why Eki Bright wasn’t what the judges were looking for. Translated from the announcement post:

In addition, many of the entries themselves were rich in policy suggestions, not only for solutions that improve transportation convenience, but also for solutions that address recent issues in Japan, such as eliminating “transportation vacancies,” improving business productivity, and coordinating with urban development.

Eki Bright is aiming to solve similar problems as existing transportation utilities from a different angle. It’s not intended to be a research project or a prototype for a hypothetical user problem, and my submission materials didn’t try to present it as such. Prior to the pre-judging interview (and probably after) the judges had not downloaded Eki Bright, so none of the creature comforts of a well-crafted iOS app would be apparent to them.

With hindsight I shouldn’t have spent time on the submission. But with the information I had at the time, it made sense to gamble some time for the chance of wider exposure for Eki Bright or even some of the prize money.

Regardless of the disappointing result for Eki Bright, it was still a great experience. I liked seeing the other entries and I like the winner Cycle-Shortcut.

Now that I’m unblocked by some of the entry requirements of the contest, I have some next steps lined up for Eki Bright and I’m looking forward to getting started on it again.

Fixing the Crash: ActivityKit is Unavailable on macOS

Sat, 25 Jan 2025 05:10:00 -0600

If you have an iOS app that:

supports “Designed for iPad” or “Designed for iPhone” and is on the Mac App Store (or is otherwise available on macOS)
uses the ActivityKit framework

Then your app will crash on macOS when you reference an ActivityKit symbol (through at least iOS 18.2).

Welcome to Crashville

How to fix it:

Link ActivityKit.framework as optional

Go to project -> app target -> Link Binary With Libraries
Add ActivityKit.framework
Set ActivityKit.framework’s status as Optional
Repeat for the widget app extension target as well

Link ActivityKit.framework as optional in app target and widget target

Avoid calling ActivityKit symbols in your code

There are a lot of different ways to conditionally reference ActivityKit symbols.

Conditional referencing must be done at runtime since even when running on macOS the compiler directive #if canImport(ActivityKit) will still evaluate to true.

Use if !ProcessInfo.processInfo.isiOSAppOnMac to short circuit code that shouldn’t run on macOS.

In the case of Eki Bright, I have my direct usage of ActivityKit behind a dependency, defined and configured with the swift-dependencies library. This allows me to swap out a fully functional dependency with a dummy dependency at launch time.

/// LiveActivityClient.swift
import ActivityKit
import ComposableArchitecture
import WidgetKit

typealias ActivityID = String? // Same as `Activity.ID?`

@DependencyClient
struct LiveActivityClient {
    var startOrReplaceRouteActivity: @Sendable (_ routeItem: RouteItem?) async throws -> ActivityID
    var updateOrEndRouteActivity: @Sendable (_ now: Date) async -> Void
}

extension LiveActivityClient: DependencyKey {
    static let liveValue: Self = .init(
        startOrReplaceRouteActivity: { routeItem, segmentActivePhases, now in
            /// Call real implementation of `Activity.request`, etc.
        },
        updateOrEndRouteActivity: { now in
            /// Call real implementation of `activity.update`, `activity.end`, etc.
        }
    )

    static let unavailableValue: Self = .init(
        startOrReplaceRouteActivity: { _, _, _ in nil },
        updateOrEndRouteActivity: { _ in }
    )
}

Then in the App.swift file I use .unavailableValue instead of the default .liveValue on macOS:

@main
struct TrainApp: App {
    static let store =
        Store(initialState: .init()) {
            RootFeature()
        } withDependencies: {
            if ProcessInfo.processInfo.isiOSAppOnMac {
                $0.liveActivity = .unavailableValue // ActivityKit framework crashes on macOS
            }
        }

    var body: some Scene {
        WindowGroup {
            RootView(store: Self.store)
        }
    }
}

I can then use @Dependency(\.liveActivity) var liveActivity in any one of my features.

Of course, the implementation of your unavailableValue can also throw specific errors handled by your feature code. In my case, the LiveActivity silently failing on macOS is acceptable.

If you’re using ActivityKit.framework, then you may have a widget extension that configures the LiveActivity. In my case, I have a normal widget as well as a LiveActivity widget. In order to conditionally enable the LiveActivity widget on non-macOS platforms, I’m using the following technique from this Stack Overflow post:

@main
struct WidgetLauncher {
    static func main() {
        if ProcessInfo.processInfo.isiOSAppOnMac {
            WidgetOnlyBundle.main()
        } else {
            WidgetActivityBundle.main()
        }
    }
}

struct WidgetOnlyBundle: WidgetBundle {
    var body: some Widget {
        StationBookmarkWidget()
    }
}

struct WidgetActivityBundle: WidgetBundle {
    var body: some Widget {
        StationBookmarkWidget()
        RouteActivityWidget()
    }
}

However, there are some bugs with macOS widgets in Xcode 16.2 that I haven’t found a workaround for yet. I can’t 100% say this technique works, but if the default configuration doesn’t work for you, try the above and see if it helps. I’m still pretty confused about how to efficiently test and debug widgets on macOS, so I don’t have a lot of guidance for this part.

References

Eki Bright - The Case for DIY Routing

Fri, 24 Jan 2025 10:43:00 -0600

When I set out making the first prototypes of Eki Bright, my train timetables iOS app for the Tokyo metropolitan area, I had no intentions of tackling routing. In fact, that was one of the selling points; the lack of routing, like lack of maps, made it visually and conceptually simpler for solving the problem of getting the next train departure time at any particular station.

A DIY route in Eki Bright as it appears in the bottom Route Bar

I eventually did add routing, in a form I call DIY routing, but it grew organically out of the existing feature set, and it stays within the same niche as I’ve been targeting thus far: train riders who know where they’re going and how to get there. A tool for power users, so-to-speak.

In this post, I want to make the case for DIY routing: why it’s a useful addition to the full-featured routing apps we all use regularly. I’ve never used anything like DIY routing before, so either it’s already obsolete, or the problem was solved well enough by other apps that no one had bothered to explore other solutions until now.

I’ll use Google Maps the illustrative example of a full-featured routing app. I’ll use 乗換案内 (Norikae Annai or Japan Transit Planner in English) as the illustrative example of a railway-only routing app. And this post will be focused on the Tokyo-area of Japan.

What is DIY routing?

Full-featured routing is choosing your departure point (often “current location” via GPS) and your destination point and allowing a routing algorithm propose several route options to choose from. Each routing option will often include multiple modes (e.g. walk, train, bus) and be optimized based on some goal (e.g. soonest arrival time, cost, complexity).

A full-featured routing interface in Google Maps where the departure and destination points are required in order to calculate a route

In contrast, DIY routing is documenting your own train-based route segment-by-segment starting from the departure station. A segment consists of one train and its departure station and arrival station, and therefore scheduled departure and arrival times. Multiple segments can be combined with transfers in-between.

A completed two segment route with one transfer looks like this:

A 2-segment DIY route with a transfer at Nakameguro 中目黒

And a screencast of what it looks like assembling this two segment route in the app.

After you’ve created a route, the pertinent details update automatically as a Live Activity in the Dynamic Island and on the lock screen.

A DIY route as it appears in the Dynamic Island compact view

A DIY route as it appears as a Live Activity in the lock screen before departure

The use cases for DIY routing

You may be wondering, “if I already know how to get to my destination without the aid of an algorithmic route service, why would I go through the trouble of creating one myself each time I take a trip?”

Sure, I sometimes use the station timetable widgets I’ve set up to optimize leaving the house to catch the next train.

Using a widget to check train times before leaving the house

But other times I plan ahead maybe an hour or two to ensure I catch the (fastest) limited express train while also getting to my destination in time. I do this quickly by setting up the first departure of a DIY route, and the departure time immediately appears in my dynamic island so I can keep an eye on it.

Checking my planned departure in the dynamic island while doing something else

Sometimes I’ll set up the full route, but other times I’ll only set the initial departure and set up the rest of the DIY route while I’m waiting on the platform or even when I’m already on the train. No need to do it all at once.

If you’ve got a whole DIY route set up, you get the following benefits:

Remember when to leave your current location to catch the train you want.
Remember which train to board when you get to the departure station.
Remember when to get off at the transfer station.
Remember which train to board at the transfer station.
Remember when to get off at your arrival station.

All while browsing other apps or while your iPhone is locked.

Use case: flexibility in departure

When I’m picking my departure time in Eki Bright, I’m immediately presented with the full list, including train type (e.g. local, express). It’s quick and easy to understand at a glance what my options are. The interface has only a slight bias for “leaving now” departures, showing the next 6 departures on the station detail screen and the next ~11 departures on the station timetable screen. It’s not much more difficult to plan an hour or two ahead.

Departures as they appear on the Station Timetable and Station Detail screens

Similarly, once you’ve added a departure to a DIY route, you can see and select 2 departures before and after the active departure. This lets you quickly recover if you miss your train or decide to leave a little early.

Alternate departures shown when tapping the departure station 馬車道

In contrast, other routing apps are purely optimized for “leaving now” departures, and are forced to use a variant of the time picker control in a modal view if you’re leaving even a little later.

Choosing a departure time in Google Maps

Other routing apps also have various interfaces for re-routing to the next or previous train. But I’ve found each implementation to be lacking, either in update speed or UI clarity, mostly because the interfaces need to assist users who aren’t familiar with the route.

List of alternate departures in Apple Maps

Use case: no false sense of accuracy in walking transfer times

Full-featured routing apps default to choosing the start location of your route via GPS and then calculating the train portion of the route based on the best estimate walk time to the departure station. I think this method works fine for general users.

Google Maps showing walking directions to the departure station

However, as a power-user, I’ve found these estimates to be inaccurate to the point where they’re disruptive to my route planning.

First, GPS accuracy is often quite spotty in many parts of street-level Tokyo, and even worse if you’re in one of the many underground spaces.

The app must also make a tradeoff between waiting for the GPS signal to stabilize and providing a route. Waiting longer may return a more accurate GPS location, but may cause the user to become impatient, or even miss a train in rare cases.

Since the walking shares the street with cars and buses, due to traffic light timings walking time estimates will always need to build in some margin of error.

And finally, full-featured routing apps have no setting for “I’m a slow walker” or “I can run if it means I catch the express train and therefore a ~15 minute earlier arrival time”. This means they sometimes won’t show you a route you could easily make unless you set the departure time back a minute or two.

It’s frustrating to try to work around these apps when they’re being “smart”. I need to enter my departure coordinates exactly by typing or fiddling with the map view. Or I need to open up the departure time picker and guess and check spinning the dials enough to trigger a more ideal set of route results.

Many times, I’ve been on the station platform trying to quickly double check the info for a soon-to-depart train, but Google Maps will not show me that train because it thinks I need to walk 5 minutes to the train station due to the GPS accuracy.

Norikae Annai assumes you’re already at the departure station and provides no walk guidance or departure time adjustment. This default configuration is fine for when you’re already at the station, but slow if you want to account for a couple minute walk.

Creating a route with Norikae Annai requires selecting a departure and arrival station

You either need to use the departure time picker modal or tap through to other departures (if you can find those buttons between the ads).

Choosing alternate departures in Norikae Annai (the orange buttons between the ad views)

Use case: optimizing transfer times

Estimating transfer times between segments is a variant of the above problem of estimating walking times to the departure station.

In Eki Bright, this problem is handled the same way as above. The app does not try to make any smart estimates it can’t guarantee, but instead gives you tools and surfaces relevant information to optimize transfers on your own.

If I know my route and transfer pretty well, I can estimate my absolute fastest time walking from platform to platform. From there, I can quickly see the next couple departure options and easily decide whether I can rush to make the next transfer or whether I can take my time (perhaps stopping for a drink, or snack, or to use the restroom).

Alternate departures for a transfer shown in the bottom half of the screen above the route bar. I know this transfer occurs on the same platform, so one minute is enough.

Google Maps has a reasonably good interface for checking other transfer time options. But as far as selecting a default option, it seems to be using its walking distance algorithm even within stations. For this example Nakameguro transfer, it seems to think the transfer will take a 1 minute walk, even though these two trains actually stop on adjacent sides of the same platform and usually wait for one another.

Google Maps chooses the 22:51 departure but shows the 22:47 departure in a dropdown menu

Noriakae Annai doesn’t even have an option for choosing an alternate transfer. It’s not clear to me how the app chooses possible transfer times by default. But in the below example, I can see in Eki Bright that if I get off the Toyoko-line train right after it arrives, I have a good chance of making the Hibiya-line transfer departing at the exact same time.

Norikae Annai also shows the 22:51 departure, but has no option to show the user the 22:47 option

Eki Bright shows the 22:47 transfer option by 'default', but it's easy to see/select the alternate 22:51 departure as well

Use case: eliminating distractions like maps

Other routing apps dedicate most of their UI to departure point, arrival point, routing options, maps, and proposed routes.

Google Maps' default route selection screen

If you already know which proposed route you want to take, but just need to know the departure time, the rest of the UI is just distraction and visual noise.

In contrast, Eki Bright is optimized to get you, a power user, to your first departure time as quickly as possible. Since user preferences and situations are different, I use a layering approach: lock screen widgets, today view widgets, home screen widgets, and bookmarks on the app’s home screen.

Priority for routing is secondary, since it can be ignored completely or set up en route with no consequences.

Eliminating the necessity of choosing a destination is a big win for Eki Bright.

Eliminating the necessity of a map is also a big win. Maps take up a lot of screen real estate.

Other routing apps, even Google Maps, have their own version of timetable-based UI. However, the UI and UX is usually a secondary concern and quite clumsy. They’re not intended to be a full featured replacement for routing, nor do they incorporate progressive disclosure where you can use the departure time as a jumping off point to create a route.

Google Maps station departures screen for Ebisu station

Use case: browsing waypoints while en route

When using Google Maps for routing, it’s not possible to browse waypoints like restaurants while you’re in the middle of navigating. Using another app for routing (not only Eki Bright) allows you to still search for a restaurant at your destination while still being able to keep track of your departure time.

When does it not make sense to use DIY routing?

Unfamiliar routes

Straight up, if you don’t know how to get from your departure station to your arrival station, it will be frustrating and difficult (but not impossible) to derive an ideal route using the Eki Bright UX.

Comparing multiple routes

If you think you have the option of using two different routes, but aren’t sure which is better (i.e. faster, cheaper), Eki Bright will not be useful in making that decision.

Ultra-short routes with no fixed schedule

The Yamanote line only has one type (“local”) and comes quite frequently (every ~3-4 minutes). Although it has a published schedule, in most cases trains will not wait for their departure time. This makes it ill suited to plan around if it’s the only segment of a trip. You’ll usually want to go to the platform whenever you’re ready to leave (odds are you won’t need to wait long). This is the dream of all public transportation, right?

Planning over one day in advance

Although Eki Bright has access to timetables for weekdays, weekends, and holidays, selecting a schedule other than the current day’s is not currently supported. Also, DIY routes are assumed to be temporary and reset at the end of the day. Therefore, you can’t use Eki Bright to plan routes in advance.

My progression of designing DIY routing

Eki Bright started as a list of stations and the station timetable for each.

The station list and station timetable screens in version 1.0

Right before launch, I decided to add the train timetable for each departure as a third layer of the navigation.

The train timetable screen with a train that runs multiple railways

This was arguably unnecessary, but as soon as I added it, I immediately found it useful. I could now:

Check which stations any train stopped at.
Check the arrival time of the train at my destination station.

For a single-segment trip, this was useful enough. I started using Eki Bright for more than I originally expected to.

However, this interface didn’t work for two segment trips that required a transfer. To work around the limitation, I needed to make a mental note of the arrival time of the first segment, then go back to the home screen and search for that station. But this would mean I lost access to the timetable of the first train.

From here, the next logical step was linking a station in the train timetable screen to its station timetable. This would make it quicker to tap through and see the departure and arrival times for the full route, but I’d need to pop the stack to see earlier times.

After creating some other features, I finally decided to tackle routing. My idea was maintain a bottom toolbar that floated above all screens and showed the route as the user was assembling it. I added a button to each station on the train timetable screen to allow the user to add a departure or arrival station to a route segment.

Train timetable screen with add-to-route buttons at each station

This UI immediately solved a lot of my problems. The implementation was more difficult than I expected though. I wanted to support alternate departures out of the gate, and alternate departures need to account for a selected destination segment since not all trains go to all destinations. Plus I needed to show the user when the route configuration was not temporally possible. All the usual hardening aspects of creating a production-ready feature.

But once I had the chance to use DIY routing in the field, I found it fun. Tapping through a couple screens, choosing my trains, switching up my departure times on the fly; I felt like I was in full control.

It was an obvious next step to add Live Activities and Dynamic Island support (which presented their own implementation challenges). Once these were implemented, DIY routes felt even more like the logical jumping off point for several other features that continued to improve the experience of riding trains.

The last complementary feature I added before taking a breather was share cards. I found myself often screenshotting and cropping the route bar after I’d created a DIY route and sending it via messaging apps to my friends to tell them when I’d arrive to meet them. So I added a share button and made an attractive little PNG image that’s easy to copy or export to share.

A sampling of various DIY route share cards from the Eki Bright marketing images

From my past product experience, having some sort of shareable content is a surefire way to increase interest in your app. For a train timetables app, external sharing is a tough proposition. But hopefully these share cards will help spread the word assuming I can get enough users to the bottom of that long funnel.

How to convince/teach people to try/use DIY routing

After developing this feature from scratch and using it for a few months, I’m sold. I think DIY routing is great and I use it for 90% of my trips around Tokyo.

But I’ll admit I haven’t figured out a way to convince people to try using DIY routing in Eki Bright. This blog post is a way to get my thoughts and arguments in order.

I spent a couple weeks gently polishing the UX and adding the Live Activities feature in order to make the effort of making a DIY route better rewarded. But now I need to actually convince users to try it, and also effectively teach them how to use it.

Is the most effective teaching method tooltips? An interactive onboarding? A video tutorial? All of the above? This will be a future task.

Core Location Modern API Tips

Mon, 02 Dec 2024 16:20:00 -0600

The Core Location framework for Apple platforms received some fresh API updates alongside even more permissions minutia in iOS 17 and iOS 18.

In this post I’ll list as many gotchas as I’ve found in the “modern” Core Location as of iOS 18.1 while developing my train timetables app Eki Bright. Some documented, some not. This is not a quick start or tutorial, but you may want to skim it if you’re thinking about using an iOS 17+ Core Location API so you know what to look out for.

I’ll be discussing iOS usage of Core Location exclusively (not macOS, visionOS, watchOS).

Overall recommendations

Prefer `CLLocationManager` over `CLMonitor` and `CLLocationUpdate`

CLLocationManager has been around since the beginning of iPhone OS. Its delegate-based API can feel a bit cumbersome in the current era, but overall, I would still recommend creating your own wrapper over CLLocationManager if the core competency of your app is even adjacent to location services.

As far as I can tell, CLMonitor and CLLocationUpdate are both wrappers themselves over CLLocationManager albeit with fewer options, fewer capabilities, and many more gotchas spread across iOS minor versions.

If you’d still like to try them, please read my observations below.

Prefer `CLServiceSession` if your deployment target is iOS 18.0+

In my testing, CLServiceSession has worked as advertised and requires less babysitting than the older imperative location permission APIs.

Location services permissions is still ripe with complexity and edge cases, so I recommend reading all the documentation and my observations below.

Official documentation

I’ll start by listing the documentation for the iOS 17+ APIs I’ve found useful.

WWDC videos

There are three videos from WWDC 2023 and 2024 from the Core Location team introducing iOS 17 and iOS 18 changes.

These videos do a nice job of explaining the rationale behind the new APIs. They also illustrate the intended usage pretty well for extremely simple use cases.

Sample projects

The sample projects, although very freshly updated, do a poor job of actually proving the capabilities of the framework work as advertised. They’re more useful in seeing how the API designers intend the framework user to compose all the pieces together.

Warning about the documentation

Some official articles have been written or rewritten assuming your app’s base deployment is iOS 17 or iOS 18. Suspending authorization requests shows only permission requests based on CLServiceSession.

…while some articles have not been updated. Requesting authorization to use location services does not mention CLServiceSession at all.

Some newer API’s documentation pages are missing important notes that exist in their deprecated counterpart API’s pages. For example, CLMonitor and startMonitoring(for:).

Be sure to check the individual pages under Deprecated symbols as well.

Tips

This section is an unstructured brain dump of everything I’ve run into while using the iOS 17+ Core Location APIs. I’ve divided up the subsections into:

Permissions (CLServiceSession)
Background operation
Location updates firehose (CLLocationUpdate)
Location monitoring (CLMonitor)

Permissions

I recommend starting by reading Requesting authorization to use location services carefully, and watching What’s new in location authorization.

Implicit vs. explicit CLServiceSession usage

In iOS 18+, CLLocationUpdate or CLMonitor allow implicit usage of permissions via the underlying CLServiceSession mechanism. If you’re using iOS 17 or below, or using CLLocationManager you can skip this part.

As a pseudo flowchart:

If:

You’re only using either CLLocationUpdate or CLMonitor (not CLLocationManager) and
You’re supporting iOS 18+ and
You only need whenInUse authorization without explicit full accuracy

Then you have 2 options:

Use implicit authorization: simply call CLLocationUpdate or CLMonitor and Core Location will take a CLServiceSession (the permissions mechanism) for you behind the scenes.
Use explicit authorization: add the NSLocationRequireExplicitServiceSession key to Info.plist and hold an instance of CLServiceSession for as long as you’re getting values from CLLocationUpdate or CLMonitor.

If:

You’re only using either CLLocationUpdate or CLMonitor (not CLLocationManager) and
You’re supporting iOS 18+ and
You need always authorization or explicit full accuracy

Then:

You must take a CLServiceSession. You can still add NSLocationRequireExplicitServiceSession if you want to ensure you don’t make a mistake.

Testing the full accuracy permission prompt

One way to test the permission prompt for full accuracy usage is:

Start a fresh copy of your app on a simulator.
Trigger the location prompt and allow whenInUse permissions.
Force quit the app.
In the simulator’s Settings.app, go to your app’s settings page -> Location Services and disable Full Accuracy.
Cold launch your app.
Trigger your feature that requires full accuracy permissions.
The permission prompt should appear.

An example of the temporary full accuracy permission prompt

If you approve this permission prompt it will still appear every time you trigger your feature in future cold launches (it’s “temporary” after all).

Localizing `fullAccuracyPurposeKey`

Full accuracy requests are available in two API:

(This is another one of those cases where all the documentation is on the page of the deprecated API.)

I’m using CLServiceSession in the following manner:

CLServiceSession(authorization: .whenInUse, fullAccuracyPurposeKey: "NSLocationTemporaryUsageDescriptionDictionaryMonitor")

Specifying fullAccuracyPurposeKey tells CLServiceSession that the feature associated with the CLServiceSession instance prefers having fullAccuracy, and will try to prompt for it automatically when possible (“possible” being any number of rules).

The relevant part of the Info.plist should look like the below plist for specifying your app’s reason for wanting full accuracy permission. Notice I have two different keys because I have two features that each instantiate their own CLServiceSession.

<plist version="1.0">
<dict>
	<key>NSLocationTemporaryUsageDescriptionDictionary</key>
	<dict>
		<key>NSLocationTemporaryUsageDescriptionDictionaryMonitor</key>
		<string>NSLocationTemporaryUsageDescriptionDictionaryMonitor</string>
		<key>NSLocationTemporaryUsageDescriptionDictionaryNearbyStations</key>
		<string>NSLocationTemporaryUsageDescriptionDictionaryNearbyStations</string>
	</dict>
</dict>
</plist>

If you’re not localizing and have no InfoPlist.xcstrings, you can add the actual message you show the user to the <string>your message</string> part.

If you are localizing, then you should add NSLocationTemporaryUsageDescriptionDictionaryMonitor and NSLocationTemporaryUsageDescriptionDictionaryNearbyStations as keys in your InfoPlist.xcstrings file, with the corresponding translations.

In the above plist I’ve repeated the key name as the value, but it won’t be used since I added the key to InfoPlist.xcstrings.

I’ve used a key name with the full prefix of the root dictionary key NSLocationTemporaryUsageDescriptionDictionary, but you can use any valid localization key name.

The setup is documented in this API and in the forums.

Location updates in the background

If you need to run in the background based on location changes, you have a few requirements and a few options to consider.

You must to add Background Modes -> Location updates to the Signing & Capabilities section of your app target.
You must still add the proper permissions key (probably NSLocationWhenInUseUsageDescription or NSLocationAlwaysAndWhenInUseUsageDescription).
You must have either .whenInUse or .always permission. As far as I know, fullAccuracy permission is not required but I imagine the lack of it would affect most features that require background location updates.
You must either:
- Run a Live Activity or
- Create and hold an instance of CLBackgroundActivitySession (which is conceptually a single-purpose pre-configured Live Activity).
You must^ be subscribed to an AsyncStream from either a CLLocationUpdates of CLMonitor instance. (^I have not tested how the CLLocationManager APIs work with iOS 17+ location background APIs, so you are on your own verifying how they work.)

I want to specifically call out that .always permission is not required to receive location updates in the background assuming the above requirements are satisfied. As discussed in this article, the main difference between whenInUse and always permission is that:

With always permission, your app has the chance of being cold launched in the background in response to “significant location change, visits, and region monitoring services” if it was previously terminated.
With whenInUse permission, if your app is terminated for any reason, the user must open it again before location updates may be received in the background.

Note: there’s something called a Location push service extension that requires .always permission, but I have no experience with what the other requirements are for this feature.

Relevant docs:

The location updates firehose (`CLLocationUpdate`)

CLLocationUpdate.liveUpdates returns a stream of both location coordinates, “errors”, and permissions issues in the form of the CLLocationUpdate struct.

Although in theory the API is more streamlined for the simplest of use cases, I’d generally still recommend creating your own system around CLLocationManager if you’re doing anything that requires stability, robustness, or reliability with Core Location. Regardless, some usage notes for CLLocationUpdate are below.

iOS 18+ recommended

Although CLLocationUpdate was introduced in iOS 17, I don’t recommend using it until iOS 18 for the following reasons:

In my testing, CLLocationUpdate.liveUpdates will return no results on iOS 17 when fullAccuracy permission is denied. I have no idea whether this was related to the permissions system and fixed in iOS 18 alongside CLServiceSession or whether it was simply a bug, but iOS 18 has the expected behavior of returning less accurate CLLocationUpdate results when fullAccuracy is denied by the user.

According to the WWDC video, when background usage is not requested by the app, Core Location handles automatically disabling CLLocationUpdate.liveUpdates when going to the background and re-enabling it when coming back into the foreground, but only in iOS 18 alongside CLServiceSession. I can’t say for sure how it works in iOS 17, only that my view layer was handling this manually to make sure there were no issues.

CLLocationUpdate does not include any properties for permissions or other errors in iOS 17 (e.g. authorizationDenied, locationUnavailable).

Not a huge issue by any means, but CLLocationUpdate.isStationary was introduced in iOS 17 and deprecated in iOS 18 and renamed to CLLocationUpdate.stationary.

`stationary` is rarely set (when the app is in the foreground?)

The stationary flag is set “on the last update before updates are paused because the device has stopped moving” according to the WWDC video.

What “stopped moving” means is not explicitly documented.

In practice I’ve never seen an update with the stationary flag set to true. Based on hints from the WWDC videos, my hypothesis is that stationary is most relevant when using CLLocationUpdate and your app is in the background. Perhaps in that setting, Core Location will offer fewer updates and set the stationary flag more liberally.

`CLLocationUpdate` has no concept of filtering

The “old” API CLLocationManager has distanceFilter and desiredAccuracy you can use to have Core Location filter updates on your behalf.

CLLocationUpdate does not have these options. You have to do filtering on the stream yourself.

Perhaps the CLLocationUpdate.LiveConfiguration values are supposed to influence this instead.

`CLLocationUpdate.locationUnavailable` is unpredictable

locationUnavailable was introduced in iOS 18. Previously, a CLLocationUpdate could only have a location == nil.

I expected locationUnavailable to be useful as a way to change my UI and alert my users that there may be a temporary issue with getting their location.

In practice, the behavior changed in iOS 18.1 and locationUnavailable updates would be returned in quick succession and interspersed with normal location updates under what I’d consider ideal device conditions. It caused my UI to flicker in distressing ways (nod to SwiftUI) and was unpredictable enough to be hard to filter manually.

For now, I’ve started ignoring locationUnavailable updates completely. I’ll probably revisit it again in iOS 19 to see whether it’s stable enough to positively influence the UX.

Updates are returned about 1 or 2 times per second

I haven’t seen any official documentation about the update interval from CLLocationUpdate.liveUpdates. In practice I usually see updates on average of about 1 or 2 per second while in the foreground. It’s similar on device and on the simulator. Just an FYI.

Background behavior of `CLLocationUpdate`

I don’t (yet) have a feature that uses CLLocationUpdate in the background so my testing has been light. But I can report that I’ve seen CLLocationUpdate send results while in the background as long as the app has been configured properly for it (see the above “Location updates in the background” section).

Location monitoring (`CLMonitor`)

Documented limitations

Source for most of the below quotes:

An app can register up to 20 regions at a time.

From my testing in iOS 18.1, if you add more than 20, the CLMonitor will emit one event for each condition over the limit with state CLMonitor.Event.State.unmonitored.

According to the WWDC video, CLMonitor.Event.conditionLimitExceeded should also be set in this case, although I haven’t confirmed this.

The region monitoring service requires network connectivity.

However, a note from startMonitoringSignificantLocationChanges says that “If the device is able to retrieve data from the network, the location manager is much more likely to deliver notifications in a timely manner.”

So maybe network connectivity isn’t always required?

an app can expect to receive the appropriate region entered or region exited notification within 3 to 5 minutes on average, if not sooner.

This is more or less what I’ve experienced in my testing, with the simulator reporting slightly less on average than the device. It makes testing difficult and also makes it difficult to ensure my feature reacts predictably in the background.

In iOS 6, regions with a radius between 1 and 400 meters work better on iPhone 4S or later devices.

Since this hasn’t been updated since iOS 6, the only other advice I’ve found was in this forums thread where an Apple engineer says to be careful about making the regions too small:

Also, I wonder if your regions are appropriately large. If you are getting significant location updates every 5 miles, that means you are in an area where the mobile/wifi based signal coverage (which these services depend on) is only adequate for that kind of accuracy. If your region radii are smaller than what the horizontalAccuracy the significant location updates provide, you may actually miss the entry or exit events to those smaller regions.

The above quote broadly references a note buried in the startMonitoringSignificantLocationChanges documentation:

Apps can expect a notification as soon as the device moves 500 meters or more from its previous notification.

CLMonitor on the iOS simulator

I had varying success using CLMonitor on the iOS 18.1 simulator alongside active location simulation using a GPX file (discussed later). It was a flakey enough that I’d recommend using a real device, although using one was only slightly more successful in verifying CLMonitor usage.

CLMonitor.Event.State values

CLMonitor.Event.State is an alias for the undocumented __CLMonitoringState. I can only access the values occasionally via autocomplete:

My understanding of the 4 states is:

unknown: the initial state of the condition unless otherwise specified at the add callsite.
unmonitored: I believe this is only used when there are too many conditions (over the 20 limit) and CLMonitor is reporting which conditions will not be monitored.
unsatisfied: the device is outside the condition region.
satisfied: the device is inside the condition region.

How to set up `CLMonitor`

When using CLMonitor (on iOS 18+) you need to manage the lifetime of multiple objects:

A CLServiceSession for ensuring Core Location knows your permission goals.
A named CLMonitor instance for registering conditions.
A Task that awaits await monitor.events.

If your requirements are simple – for example, you’re only monitoring a static condition – you can do all this setup in one place and then tear everything down when cancelling the monitor.events stream.

My requirements are more complicated. The user can modify their route at any time, which triggers a full update of which conditions are monitored. The route may be discarded, at which point I need to stop all monitoring completely.

If the conditions you need to monitor change unpredictably, I recommend the following pseudocode when changing monitored conditions:

If there are no more conditions to monitor:
- Cancel any existing Task you have monitoring events already.
- If a monitor exists, remove all conditions from it, and nil it out.
- Call invalidate and nil out the CLBackgroundActivitySession if it exists.
- nil out the CLServiceSession if it exists.
Otherwise:
- Create a CLServiceSession if one does not already exist.
- Create a CLBackgroundActivitySession if one does not already exist and you want monitoring to keep your whenInUse authorized app alive in the background without a dedicated Live Activity.
- Create a CLMonitor with a static name if one does not already exist.
- Calculate which identifiers you need to add and which ones you need to remove (or simpler: remove all conditions and add all new ones)
- Remove unused conditions
- Add new conditions
- If a monitoring Task exists, do nothing.
- Otherwise, start a new Task awaiting CLMonitor.events and save a reference to the Task.

Tips for creating a system around CLMonitor

You should target iOS 18+

You can technically use CLMonitor with iOS 17, but handling permissions will be either be more complicated or less robust without CLServiceSession (iOS 18+).

You need to keep a reference to `CLServiceSession`, `CLMonitor`, and the `Task` that contains your monitoring

This is because:

The CLServiceSession defines the authorization requirements of your use of location services for the lifetime of your feature that uses them.

It is dangerous to try to “recover” a CLMonitor with the same name via the initializer if you lose the reference. This means that CLMonitor is not designed to be cheaply created and discarded. I tried this strategy at first: create a monitor and discard the old one each time my conditions changed. However, the internal bookkeeping done by Core Location means that the CLMonitor may outlive your expectations. This means that if you try to initialize a CLMonitor with the same name too soon after you’ve discarded one, the app will crash with:

Assertion failure in +[CLMonitor _requestMonitorWithConfiguration:locationManager:completion:], CLMonitor.mm:517
Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'Monitor named myMonitor is already in use'

From my testing, it seems best to subscribe to CLMonitor.events once and only once per instance of CLMonitor over the CLMonitor’s entire lifetime. Let me try to explain this thoroughly.

You have a CLMonitor
You add some conditions to the CLMonitor
You subscribe to CLMonitor.events
Now you want to change the conditions

At this point, you should keep the same CLMonitor and the subscription to CLMonitor.events alive and call CLMonitor.add and CLMonitor.remove as necessary.

The other reason it’s “better” to do diffing and only add/remove conditions as necessary is because CLMonitor keeps some state on your behalf as illustrated by the CLMonitor.record(for:) API that returns a CLMonitor.Record.lastEvent.

Do not treat `CLMonitor` as cheaply disposable

You should not discard the CLMonitor and immediately create a new one with the same name (crash described above) and you should not cancel the subscription and create a new subscription.

CLMonitor has a bug (I presume) where any later subscription attempt to CLMonitor.events after the first has been cancelled will itself cancel and fall through immediately.

Do not subscribe to `CLMonitor` multiple times simultaneously

You should not try to subscribe to the same CLMonitor multiple times for whatever reason you might want to do that. In my testing, events will be pushed out randomly between subscriptions. This may be a standard AsyncStream behavior, but regardless, I can’t think of a reason why you’d want this behavior unless you were building some sort of system of distributed workers.

You may tear down the system and stop monitoring completely, while still being able to recreate the system later

OK, so what about the situation where you do want to completely stop monitoring but also retain the ability to start monitoring again later?

The “stop monitoring for now” situation should be covered by the above pseudocode. As long as you do the proper cleanup of cancelling the subscription, removing conditions from the CLMonitor, and removing your reference to the CLMonitor and CLServiceSession you should be set up fine to recreate the entire system at some later point (but not right away, with “right away” meaning at least in the same run loop).

Define your system as an actor

CLMonitor is an actor, which means that basically every one of its APIs requires an await. I found it more idiomatic and convenient to define my wrapper system as an actor.

Reinitializing the system in a terminated/cold launch scenario

There are specific requirements around reinitializing a CLMonitor system after the app has been terminated. My use case doesn’t require this functionality, and therefore my implementation does not handle it. If you do need to handle it (and have .always authorization), I encourage you to read the docs, sample code, and watch the WWDC video.

Be careful about running multiple `CLMonitor` instances simultaneously

In theory, it should be fine to create multiple CLMonitor instances within the same app session. However, the “up to 20 conditions” limitation is per-app, so with multiple CLMonitors you will need to ensure globally you’re not exceeding that limit (if your use case has a danger of doing so).

I haven’t tested running multiple CLMonitors in parallel, so your milage my vary.

`CLMonitor` wrapper sample code

Below is a lightly tested implementation of the above pseudocode based on my app’s own implementation. I’d encourage you to use it only as reference when writing your own implementation based on your own app’s requirements and testing it accordingly.

This implementation assumes you’ve set up the rest of your project correctly with permissions strings, background modes, etc.

This implementation allows you create an instance of SampleLocationMonitor with the same lifetime as your app (read: singleton). Call monitor() each time your set of conditions changes. If the input set of conditions is empty, the instance will go dormant, otherwise it will update the conditions interactively.

This implementation also supports background operation via CLBackgroundActivitySession. You should remove this if you already have a Live Activity tied to the lifetime of your monitoring. Or remove it if you don’t need any updates in the background.

The missing piece (see “TODO” below) is what you want to do in response to receiving an event. In my case (not shown), I’m simply refreshing a Live Activity based on an existing schedule.

If you want access to all events, I would be careful about modifying this to return the monitor.events AsyncStream directly because of the limitations discussed above, namely: there can only be one subscription per CLMonitor and you cannot cancel a subscription and create a new one later.

Instead, I’d consider either:

Registering a closure along side each MonitorCondition for the SampleLocationMonitor to execute (this may be difficult to design due to Swift 6 concurrency isolation).
Creating a long-lived AsyncStream as a property of and bound to the lifetime of SampleLocationMonitor that relays all events to a subscriber.

I haven’t tested either strategy, so your milage my vary.

Anyway, here is the sample implementation:

struct MonitorCondition: Identifiable, Equatable, Sendable, Hashable {
    let id: String
    let coordinates: CLLocationCoordinate2D
    let radiusInMeters: CLLocationDistance
}

@available(iOS 18.0, *)
actor SampleLocationMonitor {
    private var authSession: CLServiceSession?
    private var monitor: CLMonitor?
    private var backgroundSession: CLBackgroundActivitySession?
    private var monitoringTask: Task<Void, any Error>?
    
    private static let monitorID = "monitor"

    func monitor(_ monitorConditions: Set<MonitorCondition>) async throws {
        guard !monitorConditions.isEmpty else {
            monitoringTask?.cancel()
            monitoringTask = nil
            if let monitor {
                let monitoringIdentifiers = await monitor.identifiers
                for identifier in monitoringIdentifiers {
                    await monitor.remove(identifier)
                }
                self.monitor = nil
            }
            backgroundSession?.invalidate()
            backgroundSession = nil
            authSession = nil
            return
        }
        
        let authSession = authSession ?? CLServiceSession(authorization: .whenInUse, fullAccuracyPurposeKey: "NSLocationTemporaryUsageDescriptionDictionarySampleLocationMonitor")
        self.authSession = authSession
        
        backgroundSession = backgroundSession ?? CLBackgroundActivitySession()
        
        let monitor: CLMonitor
        if let existingMonitor = self.monitor {
            monitor = existingMonitor
        } else {
            let newMonitor = await CLMonitor(Self.monitorID)
            monitor = newMonitor
            self.monitor = monitor
        }
        
        assert(monitorConditions.count <= 20, "CLMonitor supports up to 20 conditions")
        
        let existingIdentifiers = await Set(monitor.identifiers)
        let identifiersToAdd: Set<String> = Set(monitorConditions.map(\.id)).subtracting(existingIdentifiers)
        let identifiersToRemove: Set<String> = existingIdentifiers.subtracting(Set(monitorConditions.map(\.id)))
        
        for identifierToRemove in identifiersToRemove {
            await monitor.remove(identifierToRemove)
        }
        for monitorCondition in monitorConditions {
            guard identifiersToAdd.contains(monitorCondition.id) else { continue }
            let condition = CLMonitor.CircularGeographicCondition(center: monitorCondition.coordinates, radius: monitorCondition.radiusInMeters)
            await monitor.add(condition, identifier: monitorCondition.id, assuming: .unsatisfied)
        }
        
        guard self.monitoringTask == nil else { return }
        let monitoringTask = Task {
            for try await event in await monitor.events {
                // Optional: the last event if you need to do comparisons to derive _entry_ or _exit_ events.
                let lastEvent = await monitor.record(for: event.identifier)?.lastEvent

                // TODO: Do whatever you want to do with the events here
            }
        }
        self.monitoringTask = monitoringTask
    }
}

Testing

Simulating a moving location

I had some success using simulated location changes via GPX files. It works on both simulator and device.

The GPX file playback starts immediately on app launch. The file playback will repeat immediately after reaching the last entry.

I used this tutorial: Simulating A Moving Location In iOS.

Fixing issue where GPX files cannot be selected in the file picker in Xcode

A strange issue blocked me from using location simulation at first.

In the file picker that appears when selecting “Add GPS Exchange to Project” in the Scheme editor, all GPX files would be greyed out and unselectable. The issue appeared in a few random Stack Overflow and forum posts scattered across several years.

Eventually I tracked it down to an app I had installed called Guitar Pro asserting ownership over .gpx files in macOS system wide. I confirmed this with the mdls CLI utility (output abridged for clarity):

$ mdls basha-yoko.gpx

_kMDItemDisplayNameWithExtensions  = "basha-yoko.gpx"
kMDItemContentCreationDate         = 2024-11-30 03:31:08 +0000
kMDItemContentType                 = "com.arobas-music.guitarpro6.document"
kMDItemContentTypeTree             = (
    "com.arobas-music.guitarpro6.document",
    "public.data",
    "public.item"
)
kMDItemDisplayName                 = "basha-yoko.gpx"
kMDItemDocumentIdentifier          = 57051
kMDItemKind                        = "Guitar Pro 6 document"

Uninstalling Guitar Pro was the only thing that fixed it long enough for me to select one file. After I restarted my computer, the file picker was broken again.

For anyone else suffering with this issue, you may be able to fix it by opening your .xcscheme file (sometimes embedded in the .xcodeproj or .xcodeworkspace bundle) and adding the following xml when locations.gpx is in the same folder as your .xcodeproj. Basically, the file path of identifier is in reference to the .xcscheme file, which in my case is two folders deep inside the .xcodeproj bundle.

<LocationScenarioReference
    identifier = "../../locations.gpx"
    referenceType = "0">
</LocationScenarioReference>

The only way to tell if it’s working is by running it on the simulator and seeing it the location updates are played back as you’d expect. For me, Xcode still wouldn’t show the GPX file as active in its UI.

I don’t think your GPX file needs to be added to the .xcodeproj but I’m not 100% sure.

Reference: Apple forums

Conclusion

I hope this post will help those in the Core Location avant-garde.

Core Location is an important part of my app, but I still have many other features to manage, so although I’ll try to update this post with any new behavior I discover, I also welcome any well-researched tips or links to related blog posts. Feel free to send them over.

Eki Bright - Design of Station Detail

Mon, 14 Oct 2024 17:20:00 -0500

I’ve done a few nice-sized releases of Eki Bright since my first launch in August.

Eki Bright is my solo-developed iOS app for viewing station timetables for the Tokyo-area train network.

In this post, I want to share some of the design decisions for a screen I added in v1.2 and v1.3: the station detail screen.

The station detail screen, added in v1.2

Background

The first release of Eki Bright had 4 screens: home, station timetable, train timetable, and station search (disregarding the about screen, nearby screen, and widgets).

The four screens available in v1.0

In all honesty, even the “nearby stations” section of the home screen and the train timetables screens were superfluous to my original concept for the app. Even station search by text was only required to populate your station bookmarks.

However, as most projects go, the scope started to naturally increase as I found myself out and about using the prototype and missing features.

The problem with the station timetable screen

A Station is the core model concept in the app. A Railway connects an ordered group of stations.

A Station belongs to a Railway

A StationTimetable shows when a Train departs a Station going in one Direction on a particular Schedule.

A StationTimetable is defined by its Station, Direction, and Schedule

I already had a simple station timetable screen whose focus was on departure times.

The simple station timetable screen in v1.0

The station timetable screen was built as the logical next step to choosing a StationBookmark. A StationBookmark stores both the Station a user often departs from and the Direction they’re headed. For example, I often depart from Bashamichi station going inbound towards Yokohama on a weekday schedule.

Without that second piece of data – the Direction – there’s not enough information yet to show a timetable. Not a problem for bookmarks, but a big problem for nearby stations and searched stations.

For v1.0, my design solution was:

Add a direction switcher to the station timetable screen (when applicable – some stations only have one direction).
Default the user to one of the directions when they selected a station from nearby or search.

The assumption was that the user would double check the default direction and switch to the opposite direction if necessary. More than half the time, this gets the user to their desired information (the timetable) faster than the alternative designs.

Station timetable screen in v1.0 with a direction segmented control

One alternative design would be to show both rail directions as tappable buttons on the home or search screen.

Unimplemented alternative design making the user choose both station and direction at the same time

Another alternative design would be to present an inter-statial screen that only asked: “which direction are you going?”

Alternative design explored during pre-release making the user choose a direction in a separate step after choosing a station before showing the timetable

I considered both those alternatives to be clearer in the short term, but slower in the long term once the user understood the flow.

My guiding principle of the app is speed. Therefore, I chose the v1.0 design solution with the intention to return to the decision later.

Identifying user flows

There’s clearly two user main user flows that branch off from when the user opens the app:

A. The user is in a familiar place and chooses a station bookmark
B. The user is in an unfamiliar place and chooses a nearby station

(A) and (B) use cases

Additionally, there’s a third flow for when the user is perhaps first setting up their bookmarks or doing some other station research.

C. The user is searching for a station by text

Use cases (B) and (C) are similar in that the user needs to choose a direction, so I’ll combine them.

The (A) case is already solved well enough with the existing station timetable screen. If anything, it’d be great to remove the complexity of having a direction switcher in this case where it’s ambiguously useful.

My goal was to find a better solution to the (B) use cases than I’d previously pitched (to myself).

Identifying design goals

The primary design goal is for the user to find their timetable departure as quickly as possible with as few taps as possible.

Another key observation I got from my own experience and user feedback was that it’s often quite burdensome trying to figure out which direction is the correct one in any given trip scenario.

Of course, this is mostly a solved problem with traditional algorithmic based routing based on departure and destination points, like the UX of Google Maps or Jorudan apps. You type in your destination and the app gives you a route and tells you which platform to wait at.

But despite of the ease of use of traditional routing apps, I was still finding myself wanting to explore the relative simplicity of a departure-based UX rather than a destination-based UX.

So my secondary design goal was helping the user decide which direction was correct as quickly as possible with the least amount of mental overhead.

And finally, I realized that I had a lot of often extraneous yet sometimes interesting and useful data about each station that I had nowhere to display. As a tertiary goal, it would be nice to have a place for all that data that respects the principle of progressive disclosure: staying out of the way while still being accessible when desired.

Exploring solutions

Starting from the most important of the design goals, I started mapping out the station detail screen.

First design goal: timetable departures

If we want the user to find their timetable departure as quickly as possible, the most direct solution is to simply show the timetables for both directions as the same time. The upside to this design is that there are no additional taps. The downside is visual complexity.

An interface sketch with timetable items for directions side-by-side

Honestly, this was the biggest unknown that I wrestled with throughout the design and implementation process. I doubled down on the bet that the gain in speed would outweigh the visual complexity of the screen. The only way to test it was to progressively build out more and more of the screen, enough so that I could test it in context with a wide variety of stations in a wide variety of situations.

But showing two directions means doubling much of the data on the screen. And making the visual complexity even worse.

What fell out of this design decision was that there were situations where the user had already specified which direction they were interested in. In this case, the screen could hide a full column.

What made this screen different from the station timetable screen? Well, I would have truncate the full timetable since there were other sections. The fact that I could link out the station timetable screen meant I could be smart about narrowing down the timetable items based on projected use cases.

Most often, the user is starting their journey now and doesn’t need earlier departures. I can also bet the user is not planning a journey too far into the future. But I need to account for stations that have significantly frequent departures with different train types and destination stations. Without knowing how much could be fit on the screen, I guessed 4 timetable items would fit the requirements (and later expanded it to 6).

For better or worse (UX), showing a station’s departures for both directions solves the first design goal.

Second design goal: determining direction

The second design goal – giving the user enough information to determine their direction – also could be solved several ways. I turned to skeuomorphism and the humble rail diagram commonly found in train stations.

A rail diagram on the wall at Bashamichi station

The rail diagram format has several upsides:

Almost all train riders have seen its shape before.
I already have the data to construct it dynamically.
It maps somewhat logically to directions.
It shows both terminal stations and neighboring stations (one of which is usually enough to orient a rider)
It implicitly includes railway information so users don’t get confused about e.g. which Shibuya station they’re looking at.

Posting a rail diagram at the top of the screen acts as a guide. The user can look for their destination station on the left or right side of the rail diagram, and then choose a departure from the timetable on that side. This solved the second design goal.

The distinct look of the rail diagram also acted as a nice way to distinguish the station detail screen from the station timetable screen or other screens.

Third design goal: tactfully show infrequently used data

Finally, there was the third design goal of including some lesser used information about the station.

I started by listing out all the potential pieces of data that might fit.

Station data ideas

To keep scope reasonable, I didn’t want to force myself to implement all these sections for the first release. But I did want to keep a record of ideas for later while also getting an intuitive feel for how flexible the design would be for adding new types of data.

Layout ideas for the station detail screen

With this very rough sketch, I got to work on my design-via-SwiftUI procedure.

Arranging the composite data

The required data for this screen is more complex than all the other screens so far.

Starting from the Station.ID, I’d need the full Station and Railway data.

For timetables, I’d need 1 or 2 Direction for each Schedule because I’d committed during the planning phase to support user-selectable Schedule alongside using the automatically calculated schedule for the current day.

Aside: in retrospect, committing to user-selectable Schedule was a significant development burden that was completely unnecessary and unrelated to any design goals. Although I fully designed and built the feature, because of its downstream unintended consequences on the UX of other screens, I ended up removing the option to use it before release.

A schedule selector button (bottom right) fully implemented but removed before release

For connected stations (i.e. transfer stations, connected railways), I had the data but had not yet imported it into the app’s domain model. I ended up adding this section in the next point release (v1.3).

Disregarding the additional Schedule infrastructure, it wasn’t significantly slower to create the composite model for this screen than it would have been to assemble a mock data structure. Therefore I designed with the final data structure fetched from the database. This is always preferable to mock data because the marginal cost of choosing other stations as test data to populate your design or prototype is so low. For example, it was much quicker to find station examples from the database with long text that broke my initial layouts.

List sections

Designing and implementing the railway diagram

The railway diagram was important enough to the design and implement first.

I started with a paper sketch that helped me understand the nuanced cases I’d need to cover.

Sketch of the railway diagram and 5-ish distinct cases

This was a fun design and layout challenge. I wanted to show the terminal stations of the railway and both neighboring stations to the target station. I also wanted to change the line style to be solid when the stations on the diagram were directly connected and dotted when there were other stations in between them.

Of course, the Yamanote circle line broke a lot of my assumptions and required some special casing and a custom algorithm. But overall I felt like the design ended up where I wanted it to.

The finished railway diagram

Designing the timetable section

I reused the timetable item design language from other parts of the app. Including the 1-character train type indicator. Some lines are all local and all have the same destination, but many do not and require this data in order to be useful at a glance.

In the first version, I always calculated the timetable lower cutoff based on the current (live updating) time. However, after implementing connecting stations, I realized that when calculating transfer times, it made sense to pass through times from previous screens and allow the user to toggle between them if necessary.

Toggling between cutoff times

I was a little unsure of whether the ... button would be clear enough to indicate the full station timetable. So far it seems to be okay.

Last train by type

A bit of speculative feature: I thought seeing last train times at a glance would be occasionally useful. You can see this data by searching for “last” in the Google Maps schedule selector, but it only shows the actual last train regardless of type. As a user, sometimes I want to know when the last limited express train is because for me taking the local is about twice as long.

Technically, I should also be showing the last trains by both type and destination. But for most railways, I think type is enough for now.

Another tough part about this section was what to name it in both English and Japanese.

Last train by type (local, express, etc.)

Bookmarks

Bookmarks was one of the most difficult layout choices I had to make for station detail, and I’m still not completely satisfied with it.

In my view as the designer of Eki Bright, bookmarks are the core feature of the app because they enable lookup speed and so heavily differentiate the app from its full-featured competitors. They also enable use of widgets, another core feature of the app.

The flow of adding bookmarks needs to be fast, obvious, and efficient, but after bookmarks are added, it will be rarely used. This makes it very difficult to design for.

I ended up compromising. I added a bookmark icon to the top right navigation bar that scrolls to the bookmark button section lower in the list.

Why not just have the button in the navigation bar work as the real button? Each station direction can have its own independent bookmark, so it makes more sense to have buttons segregated in the same way.

Still, it’s confusing, and definitely requires a more long term solution.

Train types

Getting less useful now, but I still think it’s good to see an overview of which train types exists for more complicated railways.

A list of train types that run from this station and their assigned category

In a future version, I’d like to add some calculations for each train type to show an average of how often each arrives and what part of the day each is active for.

Destination stations

Another rarely useful bit of information, depending on the railway. I added this mostly because it was easy to calculate.

A list of destination stations and how many trains end there on the scheduled day

Rail direction toggle

For stations that have more than one direction, the toolbar is shown with individually toggleable direction buttons.

Tap either button to hide or show it in the list

Self critique

As discussed above at various points, I think this screen has plenty of room left for improvement. However, I’m pleased enough with how it accomplishes the three design goals I set out to accomplish.

Railway diagram: there are a few stations where the text gets cut off in strange ways.
Bookmarks: I’d like to experiment with popping up a separate modal for adding a bookmark instead of scrolling the list.
Direction toggle buttons: I’d like to try moving these buttons above the railway diagram. Although important, in real usage I rarely find myself changing them.

I’m of course interested in real user feedback. If you’re a Tokyo-area resident, download the app, give it a go, and send me your thoughts.

Eki Bright - Developing the App for iOS

Tue, 06 Aug 2024 08:02:00 -0500

Continuing my series of posts about my latest iOS app, Eki Bright 駅ブライト, I’ll discuss the more interesting parts of app at version 1.0.

Eki Bright app icon

Please check out the other posts in the series:

Eki Bright - Tokyo Area Train Timetables - the motivation behind the app and the solution I’ve begun to explore
This post - the high-level implementation details

Tokyo-area residents can download the app from the App Store.

Eki Bright is currently closed source due to data licensing issues, but I’d like to open source it as some point once I get that aspect figured out.

Stats

Before starting digging into the details, I’ll go over some stats about the app for context.

The app has 6 screens (5 with behavior).
The app has around 5700 lines of Swift code.
The app has a minimum deployment target of iOS 17.0.
The app supports only the iPhone form factor. There’s no technical reason for this. It was mostly to reduce complexity, promotional material requirements, and testing for the first release.
The app uses about 5 packages via Swift Package Manager: ComposableArchitecture, Collections, AsyncAlgorithms, DependenciesAdditions, GRDB, HolidayJp. ComposableArchitecture relies on several other pointfreeco packages, which I also use directly.
The app uses a basic xcodeproj file.
The app was archived with Xcode 17.4, which includes support for Swift 5.9, iOS 17, and (colloquially) SwiftUI 4.
The app has a SwiftUI App entry point.
The database of railway, station, and timetable data is generated by a script at develop-time and included in the app bundle at compile-time. The app makes no network requests.
The app uses the licenseplist library installed via Homebrew for generating a license file for packages.
The app embeds no analytics framework.

Work schedule

Prototype

I started researching and prototyping the app in mid-November. This version had support for one station going inbound on weekdays. It parsed directly from a folder of the raw json files from my data source. There was no importing and no custom database yet. It had one station timetable screen and one widget layout.

I was excited about the animation support in the first widget

The only screen in the app; a station timetable for one station, inbound, on weekdays

After a week of light usage, I’d decided to continue on to start on a production version intended for wide release.

Sprint 1

I wrote an import script to turn the input json files into a SQLite database (more on this later). I outlined a simple screen structure, still with the idea that the main app would mostly be a pre-configuration step for the widgets that users would be most interested in.

By early-December 2023 I had a home screen with bookmarks; a station timetable screen that could show any combination of station, direction, and schedule; a station search screen that worked with romaji; and a station detail screen where you could add or remove a bookmark.

I took a break from the project for several months, whilst still continuing to use and analyze the fruits of this first sprint.

Sprint 2

I started the second sprint in June 2024.

Although I always had a freshly pruned TODO list, my day-to-day usage of the app while out exploring Tokyo guided a lot of my feelings of what was missing from the first release.

I made the big decision to only target Japanese for the first release. This required ensuring search worked equally well with hiragana, kanji, and romaji.

Search supporting romaji, hiragana, and kanji

When out riding the trains, I realized a few things:

I was using the main app a lot more than I expected; not just for my home stations.
Text search was procedurally too slow to use to look up nearby stations in the moment.
Live updating nearby stations would unlock several use cases I was really excited about.

I took a detour to implement live nearby stations, first in a dedicated screen, then as a smaller section on the on the home screen.

A standalone version of the nearby screen

Next, I had to tackle the production implementation of widgets, including a mechanism to select which station/direction pair (in the form of a bookmark) appeared in the widget.

An early version of bookmark selection from the edit widget screen

I was steadily making UX and UI tweaks across the app’s few screens, especially when considering the default Japanese localization. Especially on the station timetable screen. I implemented the swipe & segmented control for switching rail directions, support for showing the entire day’s schedule, showing the current time in-line with the timetable entries, and tweaking font sizes and colors.

Experimenting with how to show the current time in line with timetable items

I took a (probably unnecessary for version 1) sidebar to implement a train timetables screen. It shows which stations a train will visit on its journey. This was another common request from my beta testers, and a feature that vastly increased my usage opportunities for the app while riding. Users could now quickly view the destination stations of an express train on an unfamiliar railway and see whether they should get on or wait for the next one.

A early version of the train timetable screen

The core features of the app felt pretty good. I moved onto onboarding and the about screen. It was nice to be able to copy the about screen nearly verbatim from Count Biki. Code reuse is usually never that straightforward in practice.

Iterating on onboarding calls-to-action in English first

I even found a use for the Tip Kit framework new in iOS 17

The last 1% (that takes 99% of the time) was copywriting for the App Store listing, designing the icon, and submitting.

Architecture

The app is built all-in with The Composable Architecture (TCA) 1.11. This includes passing and scoping Stores through the view layer, creating Reducers with State and Actions for most screens, and creating dependencies in the style of the swift-dependencies library.

This follows on from my experience building my previous app Count Biki. TCA underwent significant changes between the time I finished Count Biki and started working on Eki Bright.

The most significant (and welcome) change was the @Shared state-sharing system. It made my iterations on the bookmark system relatively trivial. Just a lot less boilerplate than I’d previously needed. Also, @Shared worked without a hitch in the widget extension.

Overall, I’m getting a lot more comfortable with TCA and feel pretty confident using it as my default architecture on indie apps going forward.

Data

Importing and storage

I used the responsible (read: no premature optimization) strategy of starting my prototyping by live parsing the json files directly from my data provider. From this experience, I decided to implement a more robust and flexible data storage system before a first release.

As mentioned in my intro post, the overarching theme of this app is speed. Searching a directory structure for the appropriate timetable file, loading multiple megabyte json files into memory, parsing them, and aggregating the results on each request did not align with my speed goals. Especially considering the various views of that data I wanted to support.

Of the many many data storage and access systems available, I chose GRDB, a long-lived wrapper library for SQLite. Even though my requirements are of relatively minimal scale, I still can’t get get onboard with a nascent solution like Swift Data that has obvious brick-wall functionality limitations and no public roadmap as to when they will be addressed. GRDB, on the other hand, lightly abstracts SQLite, has been in heavy usage by the community for years, has robust documentation, has an extensive set of quick start code snippets, and a well respected and responsive maintainer.

A reasonable solution in our networked world would have been to host the data on my own server and perform a network request for each timetable, etc. I could have added caching layers to improve response times in the common case.

However, using the network goes against my speed goal. Although network coverage is admirably solid underground in Tokyo, there’s enough chance of drop outs that I wouldn’t want my users to lose trust in the app in those few cases there’s no signal for a duration of their request. All things equal, with implementation simplicity comes robustness. And a local database removes many breakable layers of abstraction from the request/response chain.

The tradeoff is app storage space. The database started at around 300 MB, then 400 MB, then ballooned to over 1 GB (related to app extension issues), before I could optimize it pre-release back down to ~225 MB. Still quite large for such a simple app, but again, it’s both a trade-off I committed to up front and differentiation point.

One of the best decisions I made was to invest in creating a simple and well-documented Swift script dedicated to reading JSON files and spitting out a single SQLite database. I ended up running this script dozens of times. A full import now takes about 10 minutes of wall-clock time, but in the early stages of development took less than a minute.

The import script allowed me to make iterative decisions to my schema, normalization strategy, naming, data supplements unique to my app, etc. during development. I’d simply switch targets, run the script, and replace the database file in the app directory.

Regarding the schema, I specifically decoupled the “import” model types from the “app” model types. This means that I can make the normalization/de-normalization decisions that affect query times before compile time.

For example, for search, I added a “queryTerms” field that aggregates all language variations of a station name e.g. aomi aoumi あおうみ青海アオウミ. I can create this queryTerms field at import time so no CPU time is dedicated to it at run time.

The import step also enables me to do data consistency and invariant checks. These are especially important as my provider’s data is expected to evolve over time, and relations between JSON data can get silently corrupted.

Modeling dates

A couple invariants about dates:

The data provider uses 24-hour time, within the range 00:00-23:59, specified as strings.
There are no 24-hour trains in the Tokyo train network at the moment.
Timetable schedules are specified conceptually as either weekday, saturday, sunday/holiday, or weekend depending on the railway.
No trains on any railway start before 3am.
No trains on any railway end after 3am.

I had two structs for dealing with these invariants.

HourMinute stores times at the most useful precision. It stores times as 24+ hour time, which considers early morning the next day as part of the current day. It allows easy comparison and adjustment. It ensures there are no out of bounds times.

struct HourMinute: Equatable, Comparable, Sendable {
    let hours: Int // 3...26
    let minutes: Int // 0...59

    static let earliest: Self = .init(uncheckedHours: 3, minutes: 0)
    static let latest: Self = .init(uncheckedHours: 26, minutes: 59)

    private init(uncheckedHours hours: Int, minutes: Int) {
        self.hours = hours
        self.minutes = minutes
    }

    init?(hours: Int, minutes: Int) {
        guard (Self.earliest.hours ... Self.latest.hours).contains(hours),
              (Self.earliest.minutes ... Self.latest.minutes).contains(minutes)
        else {
            assertionFailure("Out of bounds")
            return nil
        }

        self.hours = hours
        self.minutes = minutes
    }
}

When the user selects a station/direction pair, there are either 2 or 3 different timetables that we could show depending on the current time.

For example, on a honest Saturday, a particular railway may not have specific saturday schedule, but instead may have a nonWeekday schedule also valid on Sundays or holidays.

In order to determine which one to show, I use a ScheduleSelector helper to map the current logical schedule (weekday, Saturday, Sunday, or Holiday) to the potential Schedule that has a timetable.

enum ScheduleSelector: Equatable, Sendable {
    case weekday
    case saturday
    case sunday
    case holiday
    
    /// For a named day, which schedules are valid?
    var possibleSchedules: [Schedule] {
        switch self {
        case .weekday: [.weekday]
        case .saturday: [.saturday, .nonWeekday]
        case .sunday: [.holiday, .nonWeekday]
        case .holiday: [.holiday, .nonWeekday]
        }
    }
}

If the user checks the app after midnight, I need to make sure the app still fetches the schedule from the previous calendar day.

There’s some annoying date math involved. But since all schedules are locked to one timezone, the implementation is less complicated than it would be otherwise.

Train Categories

A train type is a specific name expressing which stations on a railway a train will stop. For example, “local” or “express” in English and “各駅” or “急行” in Japanese.

The names for train types follow conventions, but they are by no means standardized. For example, the Toyoko line has several train types, with a few only present on weekends:

Local
Express
Limited Express
Commuter Limited Express
Semi Express
F-Liner
S-TRAIN

A train type with the same name on a different railway may have a different color indicator. This color may not even be consistent across information sources for the same railway.

The outlier train type names can be long, even in Japanese. When I was designing the more space-constrained widgets, I realized it would be necessary to standardize train types even further for the sake of my app users.

I manually created my own system of train categories.

enum TrainCategoryKind: String, Equatable, Codable, Sendable {
    case local
    case rapid
    case semiExpress
    case express
    case limited

    var colorHexString: String { /* ... */ }

    var oneCharacterJA: String {
        switch self {
        case .local: "各"
        case .rapid: "快"
        case .semiExpress: "準"
        case .express: "急"
        case .limited: "特"
        }
    }
}

The information-dense Accessory Regular widget size necessitates a single-character identifier for a train type

In larger widget sizes where color is supported, color is a useful indicator

My design philosophy for the app is speed, and I also assume long-term usage from users who are familiar with a railway (at least enough that they’d need a widget for it). Therefore, I think its reasonable for users to learn a shorthand to distinguish between a “Local” and an “SL-Taiju” train type.

Of course, tapping on a widget takes you directly to the full station timetable in the app where the full Christian-name of the train type is shown, in case there was any confusion.

In early betas, I had even fewer categories, but thanks to some helpful feedback (thanks, Dave), I realized there was not enough differentiation for some railways in having only 3 categories.

Fetching

The interface to my database is pretty straightforward.

@DependencyClient
struct AppDatabaseClient {
    var fetchStation: @Sendable (_ stationID: Station.ID) async throws -> (Station)
    var fetchStationTimetable: @Sendable (_ stationID: Station.ID, _ railDirection: RailDirection, _ scheduleSelector: ScheduleSelector) async throws -> (StationTimetableResponse)
    var fetchTrainTimetables: @Sendable (_ trainTimetableID: TrainTimetable.ID) async throws -> ([TrainTimetableResponse])
    var fetchStationBookmarks: @Sendable (_ stationBookmarks: [StationBookmark]) async throws -> ([StationDirectionDetail])
    var search: @Sendable (_ query: String) async throws -> ([StationSearchResult])
    var fetchNearbyStations: @Sendable (_ coordinate: CLLocationCoordinate2D) async throws -> ([NearbyStationResult])
}

Perhaps surprisingly based on my commitment to speed as written thus far, I did not spend much time optimizing my database queries.

My goal was to get the query working correctly with the most obvious code. Based on testing, this was usually perceivably instantaneous from the user perspective, and therefore needed no more optimization. As of v1.0, essentially all database joins are done manually in Swift.

When I implement more complex screens with several disparate tables worth of data, I’ll probably need to revisit this! But until then, I feel like I’ve met my speed goals.

Train timetables recursion

A unique part of the Tokyo rail network is that railways across different companies share trains.

For example, a train that starts at the end of the Minatomirai line transforms into a train on the Toyoko line train at Yokohama station, which then becomes a train on the Fukutoshin line at Shibuya station (which can actually transfer again).

Note that each of these railways is owned by a different company (Yokohama Minatomirai Railway Company, Tokyu Corportation, and Tokyo Metro Co. Ltd., respectively). I don’t quite understand the politics of how this arrangement works for the railway companies, but for riders it’s incredibly convenient.

A train starting in Motomachi, Yokohama and ending in Hanno, Saitama transfers seamlessly through 5 different railways

In the dataset, a train timetable item has an optional forward and reverse link to another train timetable item. In this way, I can recursively fetch train timetables before and after the one relevant to the user’s selected station.

While testing my first implementation of this, I navigated to a Yamanote train timetable and realized that, since it’s a loop line, the same trains go from early morning to late evening.

A train on the Yamanote line circles all day

Nearby stations

I modeled the infrastructure for the nearby stations feature as a composition of 3 clients:

DeviceLocationClient
AppDatabaseClient
NearbyStationsClient

NearbyStationsClient transforms location events from the DeviceLocationClient into a list of stations fetched by coordinates from AppDatabaseClient.

DeviceLocationClient

struct DeviceLocationClient {
    var locationEvents: () -> AsyncStream<LocationEvent>
}

enum LocationEvent {
    case paused
    case update(Location)
    case unavailable
}

Under-the-hood, DeviceLocationClient uses the iOS 17 CLLocationUpdate.liveUpdates API from the CoreLocation framework. I decided to investigate CLLocationUpdate instead of the long-standing (but clunky) CLLocationManager API.

Unfortunately, the first implementation of CLLocationUpdate in iOS 17 is not fully baked. iOS 18 fixed several behavioral oddities, missing APIs, and integration points.

After spending significant time integrating CLLocationUpdate, I ultimately decided to temporarily accept its deficiencies with the intention to update to the iOS 18 version after a few months.

NearbyStationsClient

struct NearbyStationsClient {
    var nearbyStations: () -> AsyncStream<NearbyStationsEvent>
}

enum NearbyStationsEvent {
    case paused
    case update(Location, [NearbyStationResult])
    case unavailable
}

NearbyStationsClient parses the stream of LocationEvents and converts them to NearbyStationsEvents by performing a search for each set of coordinates on the station database.

In the AppDatabaseClient, I calculate the minimum and maximum latitude and longitude around the input coordinate (4 total floats), then use these in the SQL query filter.

For each raw station result from the database, I calculate the actual distance for each, sort the results, and do one last filter in case the station isn’t a departure station.

NearbyStationsFeature

The feature layer parses the stream of NearbyStationsEvents and uses the raw Location and [NearbyStationResult] to calculate a walk estimate in minutes for each result since a distance in meters is not always easy to intuit at a glance.

NearbyStationsFeature powers both the List section on the home screen and the dedicated nearby stations screen.

The nearby stations dedicated screen

Widgets

This project was my first time implementing widgets. The API and its gradual integration with AppIntents over the years made it tougher than I expected as I ventured beyond its trivial configurations.

There’s only one type of widget in Eki Bright so far: station timetable widgets. I support a few families: systemMedium, systemSmall, and accessoryRegular. I don’t support the Apple Watch in v1.0.

Two `systemSmall`-family widgets side-by-side under the `systemMedium`-family stock Weather app widget

Aside: I keep relearning the lesson that it’s useful to keep up to date with all the new frameworks at WWDC each year even if you don’t plan to use them right away. Because often the Apple engineers explain and document updates with the assumption that you already understand that SiriKit was deprecated in favor of Intents which was deprecated in favor of App Intents.

Timeline provider implementation

Implementing a TimelineProvider for a widget requires 3 functions:

placeholder - for showing the form of the widget instantaneously.
snapshot - for showing an accurate form of the widget quickly with real data.
timeline - for showing many accurate states of the widget over time.

The implementation of snapshot is similar to getting the data for the corresponding station timetable screen in the app.

let now = Date()

// Get the entire timetable for the station, direction, and schedule
let timetable = try await db.fetchStationTimetable(stationID: selectedStation.station.id, railDirection: selectedStation.direction, scheduleSelector: .from(now))

// Filter the timetable to ~9 entries
let filteredTimetable = filtered(for: now, timetable: timetable, family: context.family)

// Return success
return .init(date: now, timetable: .success(filteredTimetable))

The implementation of timeline is more involved.

// Same as `snapshot` above
let now = Date()
let fullTimetable = try await db.fetchStationTimetable(stationID: selectedStation.station.id, railDirection: selectedStation.direction, scheduleSelector: .from(now))
let nowTimetable = filtered(for: now, timetable: fullTimetable, family: context.family)
let nowEntry = TimetableTimelineEntry(date: now, timetable: .success(nowTimetable))

// Determine when the timeline should reload
let reloadDate = Date.nextDay3am(now: now, calendar: isoTokyoCalendar)

// Create an array of future dates that correspond with the minute _after_ a train leaves
let allFutureDates = fullTimetable.timetableItems
    .compactMap { $0.departureTime.advancedOneMinute() }
    .map { $0.toDate(now) }
    .filter { $0 >= now }

// Create a filtered timetable based on each of those dates
let allFutureTimetables = allFutureDates.map { filtered(for: $0, timetable: fullTimetable, family: context.family) }

// Create a TimelineEntry for each and return
let allFutureEntries = zip(allFutureDates, allFutureTimetables).map { TimetableTimelineEntry(date: $0, timetable: .success($1)) }
let allEntries = [nowEntry] + allFutureEntries
return Timeline(entries: allEntries, policy: .after(reloadDate))

Additionally, I check a few error-ish conditions before calculating the snapshot or timeline:

The database has been loaded correctly.
The user has at least one bookmark in the main app (otherwise I can guide them to do that first).
The user has selected a station from the edit widget menu (otherwise I can guide them to do that first).

Because a widget is an app extension, it requires extra steps to share data.

User settings in the file system

My user settings was stored as a Codable-generated json file in the file system within the app’s sandbox. I wanted to share the list of station bookmarks from that model with the widget extension.

I followed the procedure to enable App Groups for the App ID in the developer portal, registered the group ID in the app target, registered the group ID to the widget target, then changed the location of my user settings file.

FileManager.default
	.containerURL(forSecurityApplicationGroupIdentifier: "group.com.twocentstudios.train-timetable")
	.appendingPathComponent("user-settings", conformingTo: .json)

With that change, I could access the user settings struct from the AppIntent the same way I did in the main app.

public struct StationBookmarkEntityQuery: EntityQuery {
    let allBookmarks: IdentifiedArrayOf<StationBookmark>

    public init() {
        @SharedReader(.userSettings) var userSettings
        allBookmarks = userSettings.stationBookmarks
    }
    
    // ...
}

Database as a file from the bundle

Sharing the database was more difficult to solve. But that goes back to the unique database use case I have.

I’m using an SQLite database generated at development-time by my aforementioned Swift script. The database is read-only, bundled within the app, and is versioned alongside the app itself. This is perhaps a less-than-usual use case for an SQLite database according to the documentation around the internet.

I decided to see how far I could get with opening the database directly from the Bundle. It’s worked fine this way so far for my use case.

For simplicity, the widget reuses the same database access code as the main app. It therefore requires access to the database file.

During most of development, I gave the widget extension a copy of the database for its own bundle. I wasn’t completely aware of the implications of this at first, only that it seemed to work. Unfortunately, it does make a full copy of the database file, and results in 2 full identical copies of the database shipped with the app. The size of my database makes this quite large.

It took some research, but I found an admittedly brittle way to access the app’s bundle from the main bundle by hacking around on the bundle URL. This means I only have to include the database in the main target.

I’m not confident in this solution, but I still prefer it over superfluously taking ~300 MB of every user’s precious device storage.

Previews

Previews worked great while I was designing and implementing the prototype.

SwiftUI previews showing widget context variants for a static timeline entry

Unfortunately, as soon as I needed to upgrade to a AppIntent-powered timeline provider, the available #Preview macro no longer compiles.

The below two overloaded macros do not compile under any circumstance for me.

// Error: Macro 'Preview(_:as:using:widget:timelineProvider:)' requires that 'TestIntentTimelineProvider' conform to 'AppIntentTimelineProvider'
#Preview(
    as: .systemMedium,
    using: TestIntent.self,
    widget: { TestWidget() },
    timelineProvider: { TestIntentTimelineProvider() }
)

// Error: Macro 'Preview(_:as:using:widget:timelineProvider:)' requires that 'TestAppIntentTimelineProvider' conform to 'IntentTimelineProvider'
#Preview(
    as: .systemMedium,
    using: TestWidgetConfigurationIntent.self,
    widget: { TestWidget() },
    timelineProvider: { TestAppIntentTimelineProvider() }
)

My minimal reproduction case is in this gist.

I had to switch back to single TimelineEntry previews.

#Preview("Default", as: .accessoryRectangular, widget: {
    StationBookmarkWidget()
}, timeline: {
    TimetableTimelineEntry.mock
})

Refreshing

Apple has several frameworks that operate fundamentally based on vaguely documented heuristics, often partially related to the unique way each user uses their device.

BackgroundTasks is a good example, although it’s perhaps changed in a few years since I trialed it. It took me weeks of daily usage testing to get a feel for relevant metrics like how often a task was run by the system, how long it was run on average, how much work my task completed during that time, and what other system frameworks were available during my app’s allocated period.

I’ve found widgets to be similar to that experience.

My home screen and today screen widgets (of small and medium family) refresh as expected.

However, since its initial implementation, my accessory medium family lock screen widget behaves unpredictably, but always incorrectly.

With the same timeline provider implementation as the other widget types, the lock screen widget does not refresh at 3am. In fact, it usually does not load the day’s station schedule until somewhere between 11am-2pm.

The lock screen widget showing the 'no more trains' message. It should have loaded a fresh timeline at 3am.

The lock screen widget showing the placeholder configuration

To be fair, there is some official documentation about widget refreshing, but it leaves out enough to keep me guessing as to what the underlying problem actually is.

My current theory is that my widget has too many timeline entries per day.

In the same vein as my BackgroundTasks framework drama above, it’s painfully slow to debug this issue because I can test only one potential fix per day at most.

My theory of too many timeline entries is based on a few lines from the docs:

A widget’s budget applies to a 24-hour period. WidgetKit tunes the 24-hour window to the user’s daily usage pattern, which means the daily budget doesn’t necessarily reset at exactly midnight.

OK, the fact that the reload doesn’t happen until mid-day is consistent with the above.

For a widget the user frequently views, a daily budget typically includes from 40 to 70 refreshes. This rate roughly translates to widget reloads every 15 to 60 minutes, but it’s common for these intervals to vary due to the many factors involved.

I’m assuming the loaded term “refresh” refers to the system taking an Entry struct and loading it into the widget’s UI at the requested schedule and not the timeline provider getting a request from the system to fetch an entire fresh timeline.

If that’s true, then my widget’s timeline definitely has more than 70 entries. In fact, many railway’s stations see over 250 trains per day, and thus will have that many timeline entries if I always want to show the user the next 6 trains and no departed trains.

I tested this theory by creating a build that limited the timeline to ~60 entries, basically updating every ~6 train departures. This schedule certainly treads the line between useful and not. In a few days of testing it seemed like this change resulted in the timeline reloading properly at 3am.

With that knowledge, the rest of the docs make even less sense to me:

If your widget can predict points in time that it should reload, the best approach is to generate a timeline for as many future dates as possible.

In isolation, this makes sense and is what I’m trying to do. In theory, I could generate an indefinite timeline since the station timetables are fixed.

Keep the interval of entries in the timeline as large as possible for the content you display.

For me, “as large as possible” is once every train departure, which can be every minute at minimum.

WidgetKit imposes a minimum amount of time before it reloads a widget.

OK, fine, understandable. Hopefully it’s doing this somewhat intelligently based on user behavior though?

Your timeline provider should create timeline entries that are at least about 5 minutes apart.

Why though? Why can’t the system impose this limit dynamically, again, based on user behavior or whatever other factors it has?

Regardless of the docs, I’m still confused as to why this failure case appears as it does:

Why am I not seeing the timeline stop updating on a random time entry instead of the “no more trains” empty state or placeholder state?
Why am I not seeing any issue with the other widget types?
Why does WidgetKit not have at least a debug accessible error for reporting “too many timeline entries”? This could even be thrown when returning the Timeline.

A few more hypotheses I have:

I’m generally more active in the evening than the morning. Perhaps the hidden device heuristics are causing the system to expend my widget’s refresh budget during the time range I have the most device pickups.
The always-on screen feature is causes the system to be too overzealous about updating the widget. According to Screen Time, I generally have about 60-80 device pickups per day. I don’t think that counts times I wake my phone (e.g. to check notifications) but don’t unlock it. If the widget loads a new entry for each pickup and pre-pickup, plus whatever other triggers it has, that would exceed the budget.

A beta tester also confirmed the widget’s errant lock screen behavior on an iPhone SE, which makes me even less sure about the causal factors I’ve hypothesized.

As you can probably tell, this bug has been a thorn in my side for months. I considered removing the lock screen widget from v1.0, but I figured it’d get better data for debugging, and users would still see the timetable for most of the day. The failure also doesn’t prevent users tapping through the widget to quickly see the timetable in the app.

The navigation story for Eki Bright is straightforward since there are so few screens.

There’s one navigation stack that handles all screens except the about screen, which is presented modally.

The behavior of the search feature is standard iOS, but still a bit weird in my opinion.

I’m still planning to keep the navigation structure as simple as possible as the app’s features continue to evolve for the sake of speed. However, I’d like to provide more dedicated resource screens (e.g. a railway screen, a station detail screen), and more links between those screens.

The improvements to navigation in TCA are welcome. There are two ways to handle stack-based navigation in TCA: manipulating the StackState programmatically and/or using the SwiftUI NavigationLink view.

I chose the former, and am intercepting all navigation-related reducer actions at the root level and manipulating the StackState. (However, dismissals are handled with the dismiss dependency.)

Reduce { state, action in
    switch action {
    case let .path(.element(id: id, action: .stationDetail(.railDirectionButtonTapped(railDirection)))):
        guard let stationDetailState = state.path[id: id]?.stationDetail else { return .none }
        state.path.append(.stationDirections(.init(station: stationDetailState.station, initialRailDirection: railDirection)))
        return .none
    case let .path(.element(id: _, action: .nearbyStations(.searchResultTapped(nearbyStation)))):
        state.path.append(.stationDirections(.init(station: nearbyStation.station)))
        return .none
    case let .path(.element(id: _, action: .stationDirections(.timetableLeft(.trainTapped(trainTimetableID, from: stationID))))):
        state.path.append(.trainTimetable(.init(trainTimetableID: trainTimetableID, stationOfInterest: stationID)))
        return .none
    // ...

I consider this strategy to be somewhat brittle, but up to now it’s provided flexibility. The feature hierarchy is not so complicated yet as to be unwieldy.

Design

Depending on the app and feature, I occasionally do design work upfront in a pencil sketch and/or a Figma page. I also feel comfortable iterating quickly on design in a SwiftUI preview.

Eki Bright evolved gradually from a prototype. And at first, I was mostly focused on the appearance of each widget family.

I also planned to, and still plan to, commission a professional designer to make a full pass at least the visual design language of the app if not the UX and branding as well.

However, for v1.0 I decided to play it safe with a utilitarian design focused on, you guessed it, speed. And closely related to speed, visual clarity.

Utilitarian design

The standard iOS design language is relatively utilitarian, so it’s not too difficult to play within that sandbox if you don’t have strong opinions about visual design.

There are a lot of benefits that fall out of the decision to stick to standard UI framework components and HIG guidelines:

Dark mode requires little additional work.
Dynamic type requires thought and testing, but comparatively less work.
App-wide constants like screen margins don’t need to be maintained.
There’s no additional costs for font licensing.
Programmatic component configuration is quick.

This extends to e.g. using List vs LazyVStack (a decision that’s more loaded than just visual aesthetics). List has out-of-the-box support for item moving, deleting, edit mode, sticky headers/footers, dividers, etc. Although I just as often found myself fighting system defaults when my particular layout requirements fell apart. There’s no free lunch in (iOS) dev.

Color

I defer my use of color to the railway colors from my data provider and the 5 train category colors I chose. From my experience as a user, these colors are incredibly important in quickly choosing a station from my bookmarks or an entry from the timetable.

When choosing the app’s accent color (a HIG staple), I intentionally picked a purple-ish color because there are few railways that use purple branding.

I do my best to create visual hierarchy with SwiftUI’s primary and secondary foreground colors combined with font sizes and bolding. It’s a tough balance, and it took constant effort iterating, but I feel pretty good about where v1.0 ended up.

Animations

My use of animations is relatively light. The nearby list reconfigures often while moving, and these items rearrange themselves with animation. The station timetable screen scrolls naturally when the time updates. Besides that, I follow that same utilitarian mindset mentioned above.

Rail direction

The toughest UX decisions I’ve encountered so far (and which the jury’s still out on) are related to rail directions.

How to display the rail direction name to users.
Where to put the rail direction segmented control on the station timetable screen.

The rail direction segmented control in the toolbar (bottom), and rail direction indicator (top)

Most official rail direction names are in the dataset as 上り (inbound), 下り (outbound), 北へ (northbound), etc. However, these official names are either absent or de-emphasized in signage around stations.

Rare signage at JR Ebisu station showing inner-loop (内回り) and outer-loop (外回り) rail directions of the Yamanote line

How to display the rail direction name

For v1.0 especially, I wanted to keep my own large-scale supplements to the official dataset as minimal as possible.

My choice for displaying the rail direction was to:

(A) Default to showing the official direction name (“inbound”) with the awareness that users would find it jarring at first, but eventually learn and adapt for railways they used regularly (arguably the core use-case for the app).
(B) Default to replacing the official direction name with the last station in that railway. This is a common display technique seen in station signage, although sometimes the next station or the next major station are used instead.
(C) Default to replacing the official direction name with my own custom choice based on first-hand research of each railway.

I chose (A), using the official direction name out of pragmatism.

In user testing, this has continued to be a pain point, and will certainly be a high-priority item in the TODO list.

Where to put the rail direction segmented control

The (optional, depending on the station and railway) segmented control for the rail direction affects all the contents of the station timetable screen besides the station name in the navigation bar, the railway name, and the schedule.

Considering hierarchy, it should either be in the navigation bar or the toolbar.

The navigation bar is already full with the title, especially when used in NavigationBarItem.TitleDisplayMode.large. However, it could still be condensed into the trailing bar item.

My instinct was to put the segmented control in the toolbar. This makes it easier to tap without reaching, and also filling the space and disappearing cleanly when it’s not relevant for the station. I supplemented it with a smaller label in the section header since it’s important information.

However, in user testing, some users were completely blind to the segmented control in the toolbar position. If users don’t notice it, they’ll also be unaware they can swipe left and right to page between timetables for each rail direction.

It is crucially important users don’t miss this control. When coming from a nearby or search result, the user will navigate to the default rail direction. If they don’t realize they need to navigate further to see the opposite direction, they may use incorrect timeline information or spend time searching the interface.

Perhaps the simplest solution is to add a tooltip during onboarding to call this out. I’m generally pretty skeptical of making discovery of any critical feature reliant on users reading text.

For v1.0 it was a necessary evil to ship the toolbar interface and further measure opinions.

Short term, I should add a tap action to the rail direction label in the section header that transitions to the other rail direction timetable.

Medium term, I’m planning on de-emphasizing the full station timetable screen and replacing it in the navigation hierarchy with a station detail screen. When designing the detail screen, I can be more careful about highlighting the rail direction distinction.

Yamanote train destination

Related to rail direction is the destination station of a particular train. In the simple case, railways always end at the same station. But sometimes a railway breaks off into other railways that end at different stations.

The Toyoko line from Nakameguro continues on to a few different stations depending on the train

The Yamanote loop line (as my constant source of edge cases) presented a user clarity issue compounded by the aforementioned “how to display the rail direction name” woes.

The Yamanote line trains always start and end at Osaki station. That means every timetable for every Yamanote line station and rail direction showed Osaki as the destination.

Both inner-loop and outer-loop trains show a destination of Osaki 大崎

In my use I found train destination is a good backup when rail direction was unclear. Without this affordance, the mental gymnastics I needed to do to understand inner-loop and outer-loop directions was a deal-breaker for me.

I decided to spend a little time manually adding “direction stations” for each station on the Yamanote line only. I consulted signage for each station and chose the next most identifiable station.

let directionStations: [StationDirectionPair: Station.ID] = [
    .init(stationID: "JR-East.Yamanote.Osaki", railDirection: .innerLoop): "JR-East.Yamanote.Shinagawa",
    .init(stationID: "JR-East.Yamanote.Gotanda", railDirection: .innerLoop): "JR-East.Yamanote.Shinagawa",
    .init(stationID: "JR-East.Yamanote.Meguro", railDirection: .innerLoop): "JR-East.Yamanote.Shinagawa",
    .init(stationID: "JR-East.Yamanote.Ebisu", railDirection: .innerLoop): "JR-East.Yamanote.Shinagawa",
    .init(stationID: "JR-East.Yamanote.Shibuya", railDirection: .innerLoop): "JR-East.Yamanote.Shinagawa",
    .init(stationID: "JR-East.Yamanote.Harajuku", railDirection: .innerLoop): "JR-East.Yamanote.Shibuya",
    .init(stationID: "JR-East.Yamanote.Yoyogi", railDirection: .innerLoop): "JR-East.Yamanote.Shibuya",
    // ...

Yamanote train destinations (Shibuya 渋谷 and Shinagawa 品川) are now more relevant and make rail directions more differentiable at a glance

Conclusion

I covered a lot in this post. This is a decent summary of the many problems I worked through to varying degrees of “solved” during the few months of development leading up to v1.0 of Eki Bright.

As I become more confident in my solution to some of the above problems, I’ll try to write some more straightforward “How to X in Swift” posts in the future.

Until then, thanks for reading.

Eki Bright - Tokyo Area Train Timetables

Sat, 27 Jul 2024 09:02:00 -0500

My latest app is called Eki Bright or 駅ブライト in Japanese.

Eki Bright app icon

In short, it’s an app for quickly accessing offline station timetables and train timetables for railways in the Tokyo metropolitan area including Kanagawa, Chiba, and Saitama prefectures.

The station timetable screen for Bashamichi station on the Minatomirai Line

In this series of posts I’ll talk about:

This post - the motivation behind the app and the solution I’ve begun to explore
Eki Bright- Developing the App for iOS - the high-level implementation details

Tokyo-area residents can download the app from the App Store.

Eki Bright is currently closed source due to data licensing issues, but I’d like to open source it as some point once I get that aspect figured out.

Background

I’m a public transit (specifically train) fan. And Tokyo is easily one of the best cities in the world to get around by train.

Due to the large market, there are already plenty of full featured transit apps – Google Maps, Apple Maps, Navitime, Jorudan, etc. And I’m a heavy user of all of them, especially Google Maps.

However, after many years of use, I started to find some pain points.

I got to know my daily trips well enough that I no longer needed to know all of the below information for each trip:

Which station I needed to walk to
How long it would take to walk to the station
Which railway I needed to use
Which platform I needed to wait at
Which train type I needed to get on
When the target train type would depart

I’d memorized 1-5, and only needed the departure times in order to optimize my trip.

All of the other information requires opening Google Maps, waiting for it to load, entering a destination, occasionally entering an origin, waiting for the route data to load, scrolling, choosing the top result, scrolling.

Then there were the times that I’d want to check departure times assuming I’d leave in half an hour. In that case I’d also have to manually enter a departure time or manually change the train in the helpful selection dropdown on the route page (surprisingly, a feature still not available on the web app).

Adjusting the exact train within a chosen route is an essential step in using Google Maps' routing

There were also times where I knew more than Google Maps. For example, I know that on weekends, I can sometimes take a local or express train from Bashamichi station to Minatomirai station to catch a limited express train. This little maneuver can save 10-15 minutes into Shibuya. But this information is not easy to access with the Google Maps interface.

Sure, for the most common situation I could head out from my apartment at whatever time was natural then wait on the platform for however long. But if I could see the next departures board at the station before I left my apartment, I could optimize my time better.

Thus, the idea of Eki Bright was born.

Goals

My north star for this app is, like I mentioned above, to have the same information I’d have while standing on the platform looking at the next departures board.

The main principle required for that use case is simple: speed.

Every feature is evaluated against getting the amount of time it takes to see the departure timetable for a station optimized to near zero.

Offline data: no server roundtrip is required to fetch a station timetable, saving seconds on each tap, especially in slow network environments often expected when outside or underground. (The only reason this is even feasible is because trains in Japan are so rarely late.)
Bookmarked stations: the vast majority of trips are taken from the same stations: near home or work or a third place. Letting the user choose these and putting them on the home screen eliminates a step in getting them the information they need.
Nearby stations: for the next minority of trips, the user wants to see timetables for stations nearby their current location. This is trivial with location services (GPS).
Search: as a catch all for the remaining trips, stations can be found by text search (in romaji, hiragana, katakana, or kanji).
Widgets: for bookmarked stations, users can see timetables without even opening the app. The home screen or lock screen makes it trivial to see departure times at a glance.

Nearby and bookmarked stations on the app home screen

Widgets make station timetables available at a glance

My anti-goals – things I specifically did not want to include for fear of overcomplicating the interface and muddying the value proposition – are:

Routing (i.e. inputting an origin and destination and calculating which trains to use)
Covering every city in Japan (or anywhere else in the world)
Covering other modes of public transit (e.g. buses)

Features I feel could potentially fit into the ethos of the app, but aren’t a high-priority:

Showing any information on a map
Live-updating departure times
Platform number information
Stair/elevator locations on the platform in relation to a train car

One feature that wasn’t 100% in line with my north star but turned out to be so useful as to be prioritized for first release: train timetables. Tapping a departure time in the station timetable shows the full path of that particular train as a train timetable. This is useful for two reasons:

Seeing your estimated arrival time at any destination on that line.
Seeing which stations that train stops at, in the case you’re not totally familiar with the local, express, etc. designations for that railway.

train timetables show which stations a particular train will stop at, and at what times

I have many more ideas on how I can make this data alone even more useful to users without further complicating the app.

One example of UX optimization for speed

A conceptually-murky yet concretely defined station in the app usually serves two directions unless it is a terminus.

I made a decision early on for a bookmark to represent the combination of a unique station and a direction. The reasoning being that it’s quite common for a passenger to only ride one direction from a particular station. For example, from my local station Bashamichi, I’m always going inbound into Tokyo from my house and never outbound back towards Motomachi.

It would significantly slow me down if every time I had to select “inbound” or “outbound” each time I wanted to view the timetable for Bashamichi station.

As the designer, I could put both timetables on one screen, however that would crowd the screen with useless (to me the user in my particular scenario) information.

In the case where I do use both directions somewhat equally, it’s perfectly reasonable to have two bookmarks for the same station.

I consider this well designed for the bookmarks use case. But for nearby stations and text search results users still need to select which direction they’re going before the app can display the correct timetable.

My original design presented a station detail screen in this case. It showed no timetable data yet. The user had to select one of two (or one) direction first in order to view the timetable.

This configuration almost immediately felt wrong during use. On one hand, users were less likely to make a mistake and misread the timetable for the opposite direction. On the other hand, it felt so slow having an intermediate step presented in order to see the timetable.

The deprecated Station Detail screen, looking alright but adding time and cognitive overhead

For the first release, I made two revisions to the UX:

I removed the station detail screen. After selecting a search result, the user would now be dropped directly into the timetable for the default direction for that station.
I added a quick swipe between that station’s direction’s timetables. Now users could quickly flip between the two directions with conceptually fewer steps.

Swipe between directions of a station or tap the segmented control at the bottom

Again, optimizing for speed.

I could go further and silently save which direction for any given station the user last viewed. I could also redesign the station detail screen to be more useful to all use cases, whether that be quickly viewing either timetable or just getting metadata about the station of interest. Either way, I don’t want to compromise on the speed of getting a user to the information they’re looking for.

Data

In my prototyping phase I did a dive into potential data sources, both online and offline, paid and free.

In the current self-funding phase of my business, I heavily preferred not paying for data. This keeps my indefinite overhead low and means I have more flexibility in pricing in an already crowded and mature market.

The Association for Open Data of Public Transportation aggregates and publishes data for transit systems across Japan. They also run a hackathon/contest for websites and apps built with their sourced data. This seemed like a reliable enough source for the data at the foundation of the app.

Prototyping

I hacked together a widget that ingested the aggregated timetables for Bashamichi station (my most used station) on a weekday and showing them in a widget.

One of the first widgets I hacked together

The goal at this point was to evaluate how well this implementation solved my hypothetical pain point. I used it for a couple weeks and, yes, I did feel it was a pretty useful supplement to my go-to Google Maps. I could swipe over on my home screen on my way out the door and see whether I need to hustle out to make the next limited express or whether I could take my time.

Productionizing

At this point I had to decide whether to leave this as a scratch-my-own-itch project, or whether it had potential as a full featured app I could offer of the App Store and support indefinitely. This isn’t an easy decision!

In the end, at my level of business knowledge and sophistication, I made this decision from a selfish perspective:

How much did I personally want to use the most ideal version of this app?
How interested were my friends in the concept?
How motivated was I to work on this concept for weeks or months? Could I get it to the finish line?
How capable was I of doing the design on my own?
How much revenue did I need from the app to make it worthwhile?
How many monetizable features could I implement while still committing to simplicity and speed?
What other ideas was I more motivated to work on instead?

Making sense of the data

I was by no means an expert on the intricacies of the vast Tokyo area train network. I’ve done my fair share of rides in the 6 years I’ve lived here, but vast majority of those rides were the same trains going to the same stations, with extracurricular trips being a novelty I quickly forgot the details of.

Learning not only the train system as it exists in the real world, but also as it exists modeled in my chosen dataset was a process. A couple fun concepts I had to wrap my head around:

How to model time, especially across midnight and logical day spans
How to choose a weekday, weekend, Saturday, or holiday schedule
How to internally and externally deal with train directions and destinations
How to deal with the one-off case of the one circle line (Yamanote)
How all these concepts were most naturally expressed in Japanese
How to deal with searching via multiple Japanese character sets
How to generalize train types like local, express, etc. over disparate railways
How to display colors and associate them with railway concepts

A peek into the SQLite database that powers Eki Bright

Internationalization

My initial thought was that it’d be reasonable support both English and Japanese localizations at first release. Especially considering my dataset has pretty good English support.

However, after getting into the details of the design, I realized it’d be a lot more pragmatic to optimize the interface for Japanese at first. Although I’m keen to help the low Japanese-proficiency community in Tokyo, realistically, the vast majority of my users will be comfortable enough with Japanese.

In the next phase I’ll focus on getting internationalization complete on the interface layer of the app, then focus on the data layer. It will require some design thought because a lot of the time even English speakers will want access to both the English and Japanese station name, train type, etc. when out and looking for their train.

Icon

Creating the app icon was the last step for Eki Bright. My intention for much of development was to create an anthropomorphized train character with a happy disposition, similar to the vampire rabbit mascot Count Biki.

Step zero was buying a magazine with lots of various train photos.

Luckily, train enthusiast magazines are not difficult to find in Japan

Step one was sketching some trains, then iterating heavily on character designs.

My somewhat embarrassing sketchbook (blue pen/good sketches are by my friend Kazuyo)

Step two was 3D modeling.

3D design work in progress

Which unfortunately ended up with me throwing in the towel regarding the character and pivoting into a more traditional icon.

The final icon

Although a cute character would be great, I realized it wasn’t a huge loss. Realistically, the app design is extremely utilitarian. A cute character on the book cover wouldn’t really reflect the contents very well.

In the future, assuming a healthy adoption of the app, I’d love to do a full redesign that emphasizes playfulness alongside usefulness and a streamlined UX. At that point, I think it’d be reasonable to revisit the app icon design.

Monetization

Monetization on the App Store is still a mystery box to me. The entire market is relatively mature closing in on two decades on existence.

At first release, I decided not to implement any in-app purchase or subscription at all. My focus up front is testing the market and ironing out the rough edges.

I think there are 3 valid monetization paths (or some combination):

Themes: offer themes for the app and/or widgets that are each unlockable as a one-time purchase.
Subscription: make the app functionality severely limited outside a subscription: no nearby stations, no train timetables, only one bookmark/widget. Charge a low monthly/yearly rate to cover the ongoing development costs and data renewal costs.
One-time purchase: assume prospective users understand the value, and that I can cover my long-term costs by adding new users. The upside is pricing simplicity.

One reason I’m not focused on monetization yet is that I’m not confident I can fill the top of the funnel.

Getting anyone’s attention is often an insurmountable problem, especially when most people already have an okay-ish solution to the problem I’m trying to solve.

Does anyone have space on their phone for another widget or app? Do they want to build new muscle memory and decide to open app A or app B depending on the situation? Is it a daily-use app that justifies an ongoing payment?

Although I implemented tips in raw Store Kit for my last app Count Biki, and it’ll theoretically be less development this time around, it still requires enough work that could be better spent on marketing, especially while the top of the funnel is so small.

All that’s to say that for now I’m going to focus on finding a reliable process to get users into the top of the funnel (the ever-reliable VC startup playbook, haha).

Conclusion

I’m of course happy to see this little app make its way out into the world, and hopefully shave of a few seconds or minutes for train-hopping Tokyo residents. I’m a little biased, but I’ve found myself reaching for Eki Bright before Google Maps for a majority of my trips, even when multiple transfers are involved.

It may simply be a naive sense of control Eki Bright gives me when bouncing around timetables, but regardless it’s surprisingly entertaining (rather than burdensome) to do my own simple route planning on the fly. And knowing I’m getting the absolute fastest trip from A to B.

For developers, see you in the next post for all the fun development details.

twocentstudios

Introducing Eki Bright 2.0

Train Tracker Devlog 02

Home UI

Onboarding

English support

Algorithm improvements

App Store Marketing

Submission and review

External Marketing

Next steps

Final thoughts

Train Tracker Devlog

Eki Bright - Open Data Challenge for Public Transportation 2024 Entry

Fixing the Crash: ActivityKit is Unavailable on macOS

Link ActivityKit.framework as optional

Avoid calling ActivityKit symbols in your code

Hardening your widget extension

References

Eki Bright - The Case for DIY Routing

What is DIY routing?

The use cases for DIY routing

Use case: flexibility in departure

Use case: no false sense of accuracy in walking transfer times

Use case: optimizing transfer times

Use case: eliminating distractions like maps

Use case: browsing waypoints while en route

When does it not make sense to use DIY routing?

Unfamiliar routes

Comparing multiple routes

Ultra-short routes with no fixed schedule

Planning over one day in advance

My progression of designing DIY routing

How to convince/teach people to try/use DIY routing

Core Location Modern API Tips

Overall recommendations

Prefer CLLocationManager over CLMonitor and CLLocationUpdate

Prefer CLServiceSession if your deployment target is iOS 18.0+

Official documentation

WWDC videos

Sample projects

Warning about the documentation

Tips

Permissions

Implicit vs. explicit CLServiceSession usage

Testing the full accuracy permission prompt

Localizing fullAccuracyPurposeKey

Location updates in the background

The location updates firehose (CLLocationUpdate)

iOS 18+ recommended

stationary is rarely set (when the app is in the foreground?)

CLLocationUpdate has no concept of filtering

CLLocationUpdate.locationUnavailable is unpredictable

Updates are returned about 1 or 2 times per second

Background behavior of CLLocationUpdate

Location monitoring (CLMonitor)

Documented limitations

CLMonitor on the iOS simulator

CLMonitor.Event.State values

How to set up CLMonitor

Tips for creating a system around CLMonitor

You should target iOS 18+

You need to keep a reference to CLServiceSession, CLMonitor, and the Task that contains your monitoring

Do not treat CLMonitor as cheaply disposable

Do not subscribe to CLMonitor multiple times simultaneously

You may tear down the system and stop monitoring completely, while still being able to recreate the system later

Define your system as an actor

Reinitializing the system in a terminated/cold launch scenario

Be careful about running multiple CLMonitor instances simultaneously

CLMonitor wrapper sample code

Testing

Simulating a moving location

Fixing issue where GPX files cannot be selected in the file picker in Xcode

Conclusion

Eki Bright - Design of Station Detail

Background

The problem with the station timetable screen

Identifying user flows

Identifying design goals

Exploring solutions

Prefer `CLLocationManager` over `CLMonitor` and `CLLocationUpdate`

Prefer `CLServiceSession` if your deployment target is iOS 18.0+

Localizing `fullAccuracyPurposeKey`

The location updates firehose (`CLLocationUpdate`)

`stationary` is rarely set (when the app is in the foreground?)

`CLLocationUpdate` has no concept of filtering

`CLLocationUpdate.locationUnavailable` is unpredictable

Background behavior of `CLLocationUpdate`

Location monitoring (`CLMonitor`)

How to set up `CLMonitor`

You need to keep a reference to `CLServiceSession`, `CLMonitor`, and the `Task` that contains your monitoring

Do not treat `CLMonitor` as cheaply disposable

Do not subscribe to `CLMonitor` multiple times simultaneously

Be careful about running multiple `CLMonitor` instances simultaneously

`CLMonitor` wrapper sample code