At Phunware, we’ve been building mobile apps since 2009. Along the way, we’ve compiled a large list of Engineering Best Practices. In this blog post, we share some of the most important ones we follow.
When defining a new feature for a mobile app, it’s important to follow best practices to ensure the feature is complete, stable, and easy to maintain.
Let’s use a new Leaderboard screen as an example. A less experienced manager may write user stories for the Engineering team asking them to satisfy acceptance criteria that ensures the proper UX is followed, the UI matches the designs, and the points are populated by the appropriate data source. But there is so much more to consider.
Feature Flags
It’s imperative that a mobile app has an external config file. This file will typically contain various configuration settings, urls, strings, etc that an app needs before it launches. Phunware’s Content Management Engine is a great place for developers to create a JSON-based app config file.
Feature flags are an important component of any config file. Feature flags are simply set to true or false and determine whether a feature should be enabled or not. Using our Leaderboard screen example, we may not want to launch the Leaderboard feature until the first of the month. We can go live with the app release, but keep the flag set to false until we’re ready for users to experience it in production.
This is also helpful if an issue occurs and the data populating the Leaderboard is corrupt. Rather than delivering a poor user experience, we can temporarily disable the Leaderboard until the issue is resolved.
Externalized Strings & Images
The app config file is also a great place to externalize text strings and image URLs.
Let’s say there’s a typo in our Leaderboard screen or a Product Manager simply wants to change the copy. It’s much quicker and easier to update the text in the config file than to make the changes in code, submit to the stores, wait for approval, and then try to get all our users on the latest app version.
At Phunware, we actually take this a step further and externalize strings for each language. For example, we may have a strings_en key for English strings and a strings_es key for Spanish strings. We serve the appropriate text depending on the user’s language settings.
Externalizing image URLs is also helpful when we want to change images on-the-fly. We’re always uploading new images to Phunware’s Asset Manager and updating URLs.
Analytics
After launching a great feature, we’re going to want to know how it performs. Are users visiting the Leaderboard screen? Are they interacting with the filters?
Analytics is often an afterthought. If we train ourselves to write a corresponding analytics ticket whenever we write a feature ticket, we’ll find that our coverage will be very complete.
Phunware Analytics is a great tool for capturing app launches, unique users, retention cohorts, screen views, and custom event analytics.
Error Handling
So we wrote user story tickets for the Leaderboard screen and the developers have finished implementing it. But what happens when the API goes down and returns a 500 error? Will the app provide an informative error message, a generic one, or simply get into a bad state?
By writing an error handling ticket we can define the behavior we would like when something goes wrong. At Phunware, we like to use a mix of specific and generic error messages.
For the Leaderboard example it may be more appropriate to display a message such as “Unable to load Leaderboard data. Please try again later” rather than “An unexpected error has occurred”. However, the latter might be best as a catch all for any situation where a specific error message wasn’t implemented.
Deep Links
Chances are, if the new Leaderboard is doing well, someone is going to ask if they can send a push notification promoting the Leaderboard which, when tapped, sends users to the Leaderboard screen.
If we considered deep links when writing the initial user stories then we’re probably covered. These days there are many places that may link into an app. Deep links can come from push notifications, app share URLs, emails, or even websites redirecting to the mobile app.
Considering deep links when implementing a new screen saves the time and overhead of having to do the work in a follow up release.
Offline Caching
There are times that our users have a poor network connection. Perhaps they are on a train or their WiFi is down. Ideally we realized that this may occur and tried to create a good user experience when it does.
At Phunware, we make sure to cache as much content as possible. If the user launches the app without an internet connection we’ll still display the images and content that were available the last time they launched the app.
While it’s possible some of the content is outdated, this is a better experience than showing a blank screen.
Displaying a banner at the top showing the user doesn’t appear to have a connection is also helpful in informing the user they are being shown something slightly different than if they had a good connection.
Unit Tests
We try to cover as much of our code as possible with Unit Tests and write them when developing new features.
Unit Tests allow developers to be confident the feature works as expected. We set up our build jobs to run unit tests when new builds are being generated, so a few months down the road, if a developer introduces a regression, we catch it right away. This frees up our QA team to focus on edge case issues rather than discovering breaking changes.
Documentation
So we wrote the user stories the Engineering team needed to implement the Leaderboard screen. Everything has been externalized, deep links have been tested, analytics are in place, and unit tests are all passing. Now it’s time to update the documentation.
Keeping documentation up to date is very important as codebases and feature sets are always changing. Ensuring we have proper documentation allows team members to quickly look up that deep link URL scheme or the analytics event that fires when a user toggles something in the Leaderboard.
In addition to documentation, this is also a great time to update submission checklists and QA test plans, since we’ll want to make sure the new Leaderboard is tested with each new release.
Store Guidelines
Our final best practice to follow is keeping up to date with Google and Apple’s App Store Review Guidelines. We check these weekly because we never know when new guidelines will be announced.
It’s critical to know these before the feature is completed and the app is submitted. There’s nothing worse than getting rejected because we violated a guideline. At that point any deadline we had to launch the app went out the window.
For example, there’s a guideline that requires that any app that allows users to create accounts must also provide a mechanism for users to delete their account. If we knew this when writing that user story for Sign Up and Log In, then we’re covered. If we found out the hard way, then we’ve lost precious time because it may be another sprint or two before the Engineering team can deliver that new flow.
Luckily we followed the other best practices and we’re able to disable it for now!
