The work and times of the app development team at Steamclock.

Archive (33) RSS Feed

Allen Pike • February 19, 2020

Evaluating Backend APIs

At Steamclock, we often build mobile apps for web-savvy tech companies. Luckily for us, these kinds of clients often already have solid APIs available for us to build on top of, letting us hit the ground running.

Most of the time, anyhow. In our experience, how long it takes to build a mobile app can vary a lot depending on API backends’ quality, consistency, and level of support. In extreme cases, an app being built on an excellent supporting API could take half as much work to get to a given level of user experience than something built on top of a rough and unpredictable backend.

While we’ve built up experience working around the foibles of real-world APIs, we’ve also been building experience estimating how many foibles a given API may have.

Based on that experience, we’ve built a general checklist to use during estimation – and also to share with clients – that helps gauge how straightforward an API is going to be to build on top of, and identify what kind of backend investments could speed up app development and reduce maintenance costs.

While this checklist is a high-level review and doesn’t capture all the nuance that makes a given API straightforward or complex to work with, it should provide a good start for teams considering the state of their APIs, and help estimate how much work will be needed to tame a given backend and build a great app on top of it.

We hope this is helpful with your next project – best of luck!

A graph of screens in an app.

The Steamclock API Checklist

Structure and Consistency

One of the most useful things an API backend can do is follow standards where possible, and be internally consistent elsewhere.

  1. Does the API consistently return JSON with clearly separated data, or are there some endpoints or errors that return XML, HTML, or other formats?
  2. Is the API consistent in structure and naming, such that similar data coming back from different endpoints have consistent names and data formats?
  3. Does the API consistently use HTTP methods and status codes, or are there edge cases where a “success” status code may have an error payload, or certain codes or methods are being used for novel purposes?
  4. Is the API versioned, such that if return payloads change in the future, existing apps in the field can still work with the old API for a grace period?
  5. Are there supplementary 3rd-party APIs that the app will need to use for certain kinds of data? If so, these same questions will apply to them.

Development and Deployment

Building a good mobile app will almost always require some improvements to the API. How we support iteration on the backend will play a big part in success, especially in terms of how long it takes to make progress.

  1. Have these APIs already been “battle tested” by a production product?
  2. How much bandwidth do you have in terms of API developer resources to make fixes, make improvements, and answer questions about these APIs?
  3. How familiar is your existing software team with how these APIs are built and maintained?
  4. What facilities do you have for testing using staging, demo, and other kinds of test data?
  5. How consistent is your staging environment and production?
  6. How quickly can you roll a fix or change into your staging environment, and then on to production?

Functionality and Performance

Since answering functionality questions depends a lot on app scope, one of the first things we do when evaluating a project is start roughing out wireframes for key screens. Once we have that, we can audit the APIs for what they do and don’t provide.

  1. Is it possible to get all the data we need to display in-app from the current API endpoints?
  2. Does getting the data for any particular screen take a number of simultaneous or, worse, serial requests that will result in a slow user experience?
  3. Are there endpoints that return ambiguous data, for example returning a 0 that sometimes means $0.00 and sometimes means “no value”?
  4. Are there endpoints that return “raw” data that needs complicated transformations before being displayed (e.g. filtered and combined somehow) that would be better calculated on the API side?
  5. Are there important API endpoints that return very slowly and may require UX mitigation?
  6. What facilities do the APIs have for letting the app specify transformations such as filtering, sorting, paging, and so on? A sophisticated interface like GraphQL is great, but even consistent sorting and pagination parameters go a long way.

Authentication

A lot of fairly RESTful APIs that are consumed by web apps have idiosyncratic or under-documented authentication mechanisms. Since authentication expectations are quite different between websites and mobile apps, this area is always worth evaluating early on.

  1. Does the API support modern token-based authentication, or does it assume clients are web browsers that set and manage cookies?
  2. Are the rules for session expiry and session renewal clearly documented and understood?
  3. Does the API currently provide provisions for extra security considerations like answering security questions or two factor authentication?
  4. Do the API responses clearly distinguish between different authentication exceptions such as incorrect password, session expired and needs renewal, account locked out, security question incorrect, etc.?

Documentation

While we can work together to help fill out documentation where needed, getting developers already familiar with the API to build out and update docs can be a big early win for app development projects.

  1. What percentage of the API endpoints are currently documented?
  2. Does the endpoint documentation include example requests and payloads?
  3. Are the supported options listed for fields where “enum” style values are expected?
  4. Is the documentation in a format where we can reasonably collaborate to make corrections and fill gaps? (e.g. a wiki or other web-based CMS)
  5. Does the documentation include information on error states and edge cases, or is it focused on the “happy path”?
Accent Accent

2.19.20.1001

Allen Pike • December 9, 2019

Deploying Two Spies

All the way back in 2014, Steamclock’s Allen Pike had the itch to prototype a game, and a desire to learn Swift – Apple’s latest programming language. Inspired by boardgame-like turn-based games like Letterpress, a coding-intense weekend resulted in a prototype spy strategy game. After some highly scientific playtesting at Vancouver’s Alibi Room, the conclusion was swift: it was fun!

Two Spies game logo

Although we generally make consumer and productivity apps, our team has a long background in game development – co-founder Nigel Brooke worked at Radical Entertainment, later part of Activision, for a decade before going indie. As such, Two Spies was a popular side project to pick up for a few weeks between other projects. In this way it turned into a real team effort, and great testbed for new technologies, processes, and Swift language features.

By last year, the game had evolved into a “real time” turn based flow, and was getting increasingly positive feedback from playtesters. Thus, the Royal Pixel Service was born, Steamclock’s sibling company for publishing games and side projects – starting with Two Spies. Here’s the pitch:

Two Spies is a realtime turn-based strategy game for iPhone and iPad. Based on a purported board game created to train spies in the 1960s, Two Spies supports play over local wireless, “pass and play”, internet play against a friend, plus a training bot that can help players learn the ropes.

The communications department has provided the following key briefing points for officers, and others with short attention spans:

  • Turn-based strategy: Face off with a friend.
  • Cold War Europe: Control cities, go undercover.
  • Quick rounds: Play to 5 wins or sudden death.
  • Fun in person: Friend required, martini optional.
  • Cosmetic upgrades: No gems or other nonsense.

As of today, Two Spies is now live. You can download it on the App Store, or learn more about the game on the Two Spies site.

Thanks to the designers, developers, testers, and everybody who helped make this happen – we hope you have as much fun playing it as we had making it!

Two Spies game features

Accent Accent

12.9.19.364

Allen Pike • September 17, 2019

Rate This App

Fairly often, our clients ask if we should include a “Rate this App” function in their iOS apps. The simple answer is yes – a healthy stream of ratings and reviews is a great thing for increasing downloads of your app.

However, there are enough subtle pitfalls around the relevant APIs and App Store Guidelines that it can be easy to get this wrong. Conversations about app ratings often devolve into debates about what Apple will or won’t allow, and it’s hard to remember the exact details and limitations.

So, for your reference and possible enjoyment: the dos and don’ts of iOS app rating functionality in 2019.

Two APIs, both alike in utility

There are two ways a user can leave a rating in an iOS app. The ideal way is the in-app star rating dialog available in iOS 10.3 and later. Using the SKStoreReviewController API, your app can request that iOS show this prompt.

This is a nice way to let users rate your app, and in most aspects is the best way. However, this API has one serious caveat: an app can’t always show this prompt, it can only request it to be shown. If your app has shown this prompt 3 times in the last year, or your customer has turned off review prompts on their device, then nothing will happen when you request this prompt.

Sometimes, not showing a prompt is totally fine. In the case of a “drive-by” request for a rating, the user won’t notice or care if the prompt doesn’t show. However, it’s a serious problem if somebody taps a button that says “Rate this app” and nothing happens. If you’d like users who are browsing your Settings or More page to have the option of rating your app – which you would like, since it’s good for your business – you need to wire up a button that reliably works.

Given that, in cases like this where you’re reacting to a user tap, developers need to use the older rating mechanism: loading a review page in the App Store app. This requires using the itms-apps:// URL for your app, which jumps users out to write a review.

The App Store link is a reliable mechanism, but it has two serious downsides:

  1. Jumping out to the App Store app is a worse experience than the in-app rating
  2. The App Store review guidelines ask that apps “Use the provided API to prompt users to review your app” and threaten to “disallow custom review prompts”.

These downsides make many developers hesitant to use the older functionality, even though it’s the only way currently (as of iOS 13) to add a reliable button that lets users rate your app.

Luckily, Apple’s App Review has consistently respected the difference between a “prompt” for ratings where users are interrupted – in which case Apple expects us to use the throttled in-app dialog – and a user-initiated choice to rate, where jumping to the App Store is fine. Countless apps continue to successfully use the itms-apps:// flow to enable a “Rate our app” function without raising the ire of App Review, and all is well.

Getting clever

Beyond the routine practice of wiring up a simple “Rate this app” function that goes to the App Store, there are some more advanced approaches to streamlining how users are asked for reviews. These may may make sense for your app, depending on your business and how willing you are to risk running afoul of the App Review Guidelines.

Dual wielding

If you want to offer a “Rate this app” button but still want the nicer UX of the in-app dialog, you can take the clever approach that Overcast does: the first time a user taps the button, they use SKStoreReviewController to request a review prompt, which might do nothing, but will usually work. If a user taps again, they jump out to the App Store review page which always works.

You could go a bit further with this by tracking if you’ve called for the review prompt 3 times in the last year, switching between the two APIs as needed, and maintaining this logic if Apple changes the review prompt throttling in the future. Even with the simple dual approach described above though, your users will get the nicer UX most of the time, but still minimize the cases where your “Leave a rating” button feels broken.

Is this a good time?

If you’re willing to interrupt users with an unexpected rating prompt, it’s worth putting serious consideration into when you want to do this – and how frequently you want to bother people.

The common-sense approach is to only prompt a user for a rating once it seems likely your app has delivered them real value. Usually you want to wait until they’ve used the app multiple times, and had a modicum of success exercising its features.

In terms of frequency, although you can in theory prompt 3 times a year, it’s worth seriously considering if you dial that back, resulting in less annoyed customers and thus more positive ratings when people do see a prompt.

Are you enjoying this app?

A lot of larger apps, especially SaaS products, will add a custom prompt along the lines of, “Are you enjoying this app?” This can be great for detecting unhappy customers and directing them to customer care to help turn them into happy customers, and it also lets you encourage happy users to rate or review the app on the App Store.

The danger here, however, is that Apple is almost certainly not fond of apps only asking happy users for reviews. This behaviour could easily be construed as a “custom review prompt” as barred by the App Review Guidelines, or more seriously could be considered “manipulating reviews,” which is a bannable offence. From the Guidelines (emphasis mine):

If we find that you have attempted to manipulate reviews, inflate your chart rankings with paid, incentivized, filtered, or fake feedback, or engage with third-party services to do so on your behalf, we will take steps to preserve the integrity of the App Store, which may include expelling you from the Developer Program.

While we have not heard of an app getting banned or even rejected by App Review for only asking happy customers for reviews, doing so would be well within the wording of the guidelines and is the kind of sudden policy change App Review has made in the past.

On the other hand, this would be a hard thing to enforce – while a reviewer might be able to catch some very linear conditional-review flows, it would be fairly easy for an app to simply take note of happy and unhappy users and later “randomly” prompt just the happy ones for reviews.

Overall, our current recommendation on conditional review prompts is to tread carefully and thoughtfully.

In review

Although letting people rate your app seems like a minor consideration, a tiny detail to stick in Settings in the run-up to 1.0, there is actually a lot of thought and consideration that can go into good rating flows. If you’re in the thick of getting an app shipped you may not want to get bogged down in all the ins and outs of this, but once your app is live and you’re working to scale your user base, refining these rating flows can be a great way to spread the word of your app and what makes it great.

Accent Accent

9.17.19.1279

Allen Pike • May 10, 2019

Wanted: 2 App Developers

While our growth at Steamclock is typically slow and steady, we’ve had a record spring season with a lot of interesting client and internal projects on the go.

Given that, we have openings right now for two – two! – app developers here in Vancouver:

  1. A Senior iOS Developer (Swift)
  2. An Android Developer, Contract (Kotlin or Java)

In both cases we’re looking for folks who have experience making nice native apps, and care about the human side of software development. If you’re an experienced app developer in Vancouver that shares our values of creating great experiences, continually iterating, and investing in people, then get in touch!

Accent Accent

5.10.19.107

Brady Valentino • March 29, 2019

Making the Most of Wednesdays

There are advantages to working in the same office as your team. Sometimes it’s great to just walk over to a coworker’s desk and answer a question or hash something out. Still, there has been a slow and steady shift taking place: more and more companies are moving towards remote work. Before joining Steamclock last year, I experienced this first-hand: I worked from home full time for more than a year. Toward the end I was given a chance to summarize my thoughts on this working setup:

Working remotely allows the freedom to set my own schedule and to work in the environment best suited to my workflow. Some days it’s my home office, others it’s a coffee shop, and once in a while it’s on the couch with Grey’s Anatomy on in the background.

This still rings mostly true; although I’ve since switched from Grey’s Anatomy to The Sopranos. However, it does brush over the downsides that can come with remote work – in my experience, distractions and losing focus.

Although we mostly work in the same office at Steamclock, we do observe Work From Home Wednesdays™. It’s a special day of the week where most of the team chooses to work remotely. Based on that experience, I’d like to share my preferred approach of working from a home office, and how you can make it awesome.

So Fresh and So Clean (Clean)

The key question when working remotely is: “How do I stay fresh and limit distractions while working untethered?”

Enter Brady’s Code for Surviving Your Home Office:

  • Optimize your workspace
  • Limit distractions
  • Keep healthy eating habits, and
  • Practice mindfulness

Let’s take a look at these one by one.

Optimize Your Workspace

It’s important to be aware of what kind of workspace works best for you. Try completing this sentence: “My workspace should be x, y, and z.”

For me, my workspace should be simple, functional, and bring joy.

Let’s break down what makes a workspace optimal for me:

Simple
I keep my desktop to just the basics of what’s needed to accomplish my tasks — simple and free of clutter.

Functional
The cleaner your desktop is, the more space you have for the items you actually need to be productive. For example, a designer may need space for a drawing tablet, or a writer may need space for a large clickity-clacky keyboard.

Bring Joy
Many people use this as an opportunity for a photo of a loved one. For me personally, it’s some juggling balls and a cute piggy succulent planter — but feel free to choose the cute succulent planter that works for you.

Limit Distractions

An obvious goal, but how should you go about it?

Take a moment to name the things off the top of your head that could pull focus from your daily tasks. TV? A game console? Spouse? Pets? Lack of a Bill Lumbergh type peering over your shoulder to ensure you’re working hard?

Reducing these distractions my be easier said than done, but I’ve found that noise-cancelling headphones and plenty of natural light help me stay focused on my display rather than being drawn towards the Apple TV remote or Xbox controller.

Eating Habits

There are plenty of scientific studies showing that light snacking throughout the day is better than eating several large meals at pre-determined times. While this may seem obvious for your health, it also does wonders for mental clarity. Keep it light and healthy as much as possible. Set aside the chips with soda combo, and instead reach for some fruit with water.

My go-to snacks at home are mandarin oranges, or carrots with hummus. A little goes a long way.

Mindfulness

Don’t be afraid to step away from your desk. Keep your head clear and your mental acuity will stay sharp. I like to use a variation of the Pomodoro Technique:

  • Focus on a task for 45 minutes
  • Step away from my desk to grab water or a light snack
  • Dance to some music, catch up on tweets, or watch a short YouTube video

The official Pomodoro technique recommends working in bursts of 25 minutes, with a short break after each burst, and then a longer break after 4 bursts. Personally I’ve found myself to be more productive when working in bursts 45 minutes with 15 minute breaks.

It will take a few tries to find the balance that works best for you, but the key thing is not to underestimate the importance of giving your mind a break.

Closing Thoughts

While it’s important to give yourself breaks, it can be all too easy to brush your tasks aside when surrounded by the comforts of home. Staying mindful should help you keep not just a positive headspace, but a productive one too.

So follow my code: use your workspace as a canvas for self expression, focus on being the best you that you can be, get a cute succulent planter, and watch as your productivity reaches new heights. Of course, in the immortal words of Captain Barbossa:

The code is more what you'd call guidelines, than actual rules.

Accent Accent

3.29.19.879

The work and times of the app development team at Steamclock.

Archive (33) RSS Feed