MacKuba.eu

March 2024 projects update

2024-03-27T01:14:35Z

I’ve been still pretty busy with various Bluesky- and social-related projects recently, so here’s a small update on what I’ve been working on since my November post, if you’re interested:

Skythread – quote & hashtag search

I was missing one useful feature that’s still not available on Bluesky: being able to see the number of quote posts a post has received and looking up the list of those quote posts. The Bluesky AppView doesn’t currently collect and expose this info, so it’s not a simple matter of calling the API. But since everything’s open, anyone can build a service that does this, they just need to collect the data themselves.

Since I’m already recording all recent posts in a database for the purposes of feeds and other tools, I figured I could just add an indexed quote_id column and set it to reference the source post on all incoming posts that are quotes, and later look up the quotes using that field.

Skythread, my thread reading tool, seemed like a good place to add a UI for this. When you look up a thread there, it now makes a call to a private endpoint on my server which returns the number of quotes of the root post, and if there are any, it shows an appropriate link below the post. The link leads you to another page that lists the quotes in a reverse-chronological order, like this (it doesn’t currently do pagination though). You can open that page directly by appending the bsky.app URL of a post after the quotes= parameter here: https://blue.mackuba.eu/skythread/?quotes=.

In the same way, I also indexed posts including hashtags, since hashtags were being written into post records since the autumn, but it wasn’t possible to search for them in the app. However, this has now been added to the Bluesky app and search service, so you don’t need to use Skythread for that. I hope that the quote search also won’t be needed for much longer :)

Handles directory

One very cool feature of Bluesky is that you can verify the authenticity of your account by yourself, by proving that you own the domain name that you’ve used as your handle. So for official accounts like The New York Times, The Washington Post, or Alexandria Ocasio-Cortez, it’s enough if they just set their handle to their main website domain (or a subdomain of house.gov in AOC’s case) to prove they’re legit – they don’t need to apply anywhere to get a blue or gold tick on their profile.

I was thinking one day that it would be nice to see how many e.g. .gov handles there are and notice easily when new ones show up. So I grabbed a list of all custom handes from the plc.directory and started recording new and updated ones from the firehose.

In the end, I decided to build a whole catalog of all custom handles, grouped by TLD, and show which TLDs are the most popular. At first I only included the “traditional” main TLDs and country domains, but a lot of people liked it and I got a lot of requests to also include domains like .art, .blue, .xyz and so on, so in the next update I’ve added all other domains too. (I gave it an old-school tables-based design as a homage to the old “web directory” websites like Yahoo Directory 😉)

Apart from handles, the website now also tracks third party PDS servers that started to show up after the federation launch in February.

Bluesky activity charts

I’ve also made a page that shows some charts tracking Bluesky user activity – the number of daily posts and unique users that have posted in a given day. The activity has been gradually falling since October until February, then there was a huge spike when Bluesky opened up for registrations without an invite (when Japan suddenly took over), and then it’s been falling down again since then (currently around the level of the October top).

You can also see some other interesting stats on Jaz’s page and Eric Davis’s Munin charts, especially the one tracking daily/weekly/monthly active user count. (I also have a few more ideas for what to add to my charts.)

DIDKit

In the last few weeks, I’ve been updating the code that tracks custom handles again to adapt to some protocol changes. The #handle event in the firehose, which included handle info on every handle change, is now deprecated and being replaced with a new #identity event, which only tells you to go fetch the account info from the source again (source being usually plc.directory).

At the same time, I also implemented validation of custom handles – clients and services that display handles are supposed to verify the handle reference in both directions themselves, because some accounts may have handles in the PLC registry assigned to domains that they don’t actually own or which don’t exist (the Bluesky official app shows such accounts with an “⚠ Invalid Handle” label, which you’ve probably seen before). For example, the handles directory page initially listed an amongus.gov account under .gov TLD, which was loaded from plc.directory, but is not in fact a real domain.

This should ideally be done by not relying on Bluesky servers, and instead checking the DNS TXT entry and the .well-known URL of a given domain manually. There’s a bunch of pretty generic logic there that will be needed in most projects that need to convert between DIDs and handles, so I extracted it to another Ruby gem named DIDKit, which lets you do things like:

get the DID of an account with a given handle
load the DID JSON document, which includes info like assigned handle(s) or hosting PDS server
check if any of the assigned handles from the document resolve back to the same DID
fetch all updates to all DIDs in batches from the PLC directory

mackuba ∕ didkit

A library for handling DID identifiers used in Bluesky AT Protocol

Skyfall

I’ve also been making some minor updates to my Skyfall library for streaming data from the Bluesky relay firehose.

One thing I’ve been trying to fix is a rare but annoying issue with the websocket connection getting stuck. From time to time, it manages to get into a state where no data is coming, but the connection doesn’t time out and just waits for new packets for hours, until I notice it and restart it. It isn’t only happening to me, others have mentioned it too (and not only in Ruby code); but it happens rarely enough that it’s really hard to debug.

My proposed fix is adding a “heartbeat” timer, which runs with some interval like every 30 seconds, and checks if there have been any new packets in some period of time; if there haven’t been any in a while, then it will forcefully restart the connection. (This isn’t included in the latest release yet, I’m waiting for it to get triggered a few times first.)

Another thing I’ve added is being able to connect to a new kind of firehose exposed by “labellers” a.k.a. moderation services. Bluesky has released this new important piece of the federated architecture earlier this month – third party developers and communities can now set up independent moderation services, which manually or automatically add various “labels” to accounts or specific posts, flagging them e.g. as “racism” or “disinformation”. Anyone can subscribe to any labellers they choose, and they’ll see the labels from those selected services shown in the app. The new firehose (the subscribeLabels endpoint) allows you to connect to a specific labeller and stream all new labels that it’s adding.

I’m also tracking all new registered labeller services and keeping a list here (it’s not curated, just a dump from a database table, so it also includes various test servers etc.).

mackuba ∕ skyfall

A Ruby gem for streaming data from the Bluesky/AtProto firehose

The “Bluesky guide”

Last month I wrote a long blog post titled “Complete guide to Bluesky”, where I included various info and tips for beginners about Bluesky history, available apps, handles, custom feeds, privacy, or currently missing features. I’m now updating it every time Bluesky releases another big feature :) Check it out if you’ve missed it.

I have ideas for a few more Bluesky introduction posts with a developer focus – a general intro to the protocol and architecture, and about working with the XRPC API and the firehose. I hope I’ll be able to find time for that in the next few months.

Tootify – cross-posting to Mastodon

I still want to finish my Mac app for cross-posting to Twitter, Mastodon and Bluesky one day, but it’s a lot of work and I’ve got too many different things in progress at the same time, so it’s moving at a glacial pace… In the meantime, I started thinking if I could maybe quickly build something much simpler that also does the job. I’ve been mainly hanging out on Bluesky in recent months and posting on Mastodon only occasionally, because having to copy-paste things from one tab to another is annoying, especially if images and alt text are involved. But the folks I know from Twitter still mostly follow me on Twitter and Mastodon only and aren’t coming to Bluesky.

I also didn’t want to simply copy every single post from here to there, because a lot of things I post on Bluesky are specifically about Bluesky stuff, so it doesn’t always make sense to post them to Mastodon – I only want some selected ones to be copied. But at the same time, I wanted to minimize the amount of friction this would add.

So the idea I had one night was that I could mark the Bluesky posts to be copied to Mastodon by simply “liking” my own posts that I want copied; a service or a cron job would then periodically look at the list of my recent likes, and when it notices one made on my own post, it would copy that post to Mastodon (and remove the like).

I managed to build it in about a day and a half, complete with image support with alt text and copying of quote-posts as posts with plain links. It’s now running happily on a Raspberry Pi on my local network 😎

The code is published here, if you’re interested – but it’s a bit of a proof of concept at the moment, just enough to make it work for myself, so it’s probably not very user-friendly. But maybe I’ll build it up into something bigger if people find it useful. (Just to clarify, this is meant to be a one-way sync by design – syncing in the other direction would be harder for various reasons, e.g. because of the complex “facets” system that Bluesky uses for post record data, and because Mastodon’s post length limit is higher than on Bluesky.)

mackuba ∕ tootify

Toot toooooooot

And One More Thing ;)

Paul Frazee, Bluesky’s lead dev, has a lovely cat named Kit and often posts photos of her. I’m a big fan of Kit, so I made a feed named the Kit Feed, which only includes posts with these photos 🙂 Like and subscribe! 🐱

A complete guide to Bluesky 🦋

2024-02-21T18:05:12Z

(Last update: 24 Jun 2024.)

For the past 10 months, I’ve been a pretty active user of Bluesky. I enjoy it a lot, and I’ve managed to learn a lot about how it works, what works well and what doesn’t, and also what’s likely coming next.

I’ve decided to write down some of the tips & tricks that I often give to friends when I send them an invite code, or the advice and answers that I sometimes give to people that I find in some feed asking about things.

This of course got much longer than I planned 😅 so if only have a moment, here’s a TLDR:

there are official iOS and Android apps, but you can also use bsky.app in the browser, or try e.g. Graysky, deck.blue, Skeets (iOS) or Skywalker (Android)
if your timeline feels empty, check out the default algorithmic feed called “Discover” – or even better, go to the “Feeds” tab, look for the “Discover New Feeds” section and look for some feeds on the topics that interest you (on the top list or in the search); follow these feeds, and then if you find some interesting people posting in those feeds, follow them too. You can also search for feeds on goodfeeds.co.
don’t be afraid to interact with people, repost good posts, like good comments, comment in threads and so on – that’s how you make friends! (but be nice :)
if you see too much NSFW stuff, look for “Content filters” settings in the Moderation tab
everything you post here is very public, so don’t share anything too private 😏
if you own some cool domain name like “taylorswift.com”, you can set it as your handle
hashtags, word muting, GIFs (from Tenor) and DMs (simple version) are now available, videos and more DM stuff are coming, post editing is planned; some kind of private profiles for sharing to limited audience may be coming, but not in near future
Jack Dorsey is not the CEO and does not run the company ;)

And now the long version:

What is Bluesky?
The company
Apps
How are things called here?
Feeds & algorithms
Safety & moderation
Privacy
Account security
Handles & IDs
What is this federation thing?
Search
Settings
Missing features
Other tools

What is Bluesky?

(A bit of history, skip if you’re not interested :)

Bluesky is a project started originally by Twitter (now an independent company), whose goal is to create a decentralized Twitter-like social network, or more generally, a platform for building various decentralized social networks.

The project was started in Dec 2019 by Jack Dorsey, former Twitter CEO. The basic idea was to design a protocol on which you could build something that would work like Twitter, but which would not be under the control of a single company that makes unilateral decisions about everything on it. It would be more like web and email, which are open standards that anyone can build on – any company can set up an email service or write an email app, and anyone can sign up for an account and start sending emails. There’s no one central authority on the Internet that can ban you from email altogether.

Such network would consist of many servers owned by different companies and people connecting together, and the idea was that eventually, Twitter itself could become a part of that network, as just one of its elements.

(If this all sounds a lot like the Mastodon social network, or “the Fediverse”, then you’re right – there are a lot of similarities between these two. However, Bluesky is built on a completely different system they’ve designed from scratch, called the AT Protocol or ATProto. They’re hoping that this will let them build some things better than they are done in Mastodon, making the network less confusing, more useful and more user-friendly. Bluesky does not directly connect with Mastodon servers and apps, although there are some “bridges” being worked on.)

After a research phase, in 2021 a team was chosen to build the platform and the Bluesky company was formally created. A woman named Jay Graber, formerly a developer at Zcash, was chosen as the CEO. Thankfully, Jay had the foresight at that point to insist that they’d set it up as an independent company, which was funded, but not controlled by Twitter. Had they not, it almost certainly would have been shut down last year after Elon’s Twitter takeover.

The team has been working on designing and building the pieces of the system throughout 2022, and in February 2023 they’ve launched a very early and rough beta and started slowly letting in some users who wanted to try it out and have signed up on a waitlist. However, the whole Elon thing happened in the meantime and that was a moment when everyone was looking for a Twitter alternative, so the interest has wildly exceeded expectations and they weren’t ready yet to take in everyone.

Since then, the user base has been gradually growing, with people being let in from the waitlist and existing users inviting their friends using invite codes. Meanwhile, the team had to speed some things up to adapt to the new situation and has been working hard on adding the most important features, and building up the backend to allow for more and more traffic. Finally, almost a year later, in the first week of February Bluesky has opened up for registrations from everyone.

The company

Bluesky is still a fairly small team at the moment. The dev team is probably something like a dozen people altogether, and that’s for the frontend, backend, protocol, servers and so on. So they just can’t add new features as fast as they’d like to, but they’re doing what they can.

The team members interact with people on the platform all the time, answering questions and just having fun in general. They’re also building almost everything in public – the source code of the app and servers is available on GitHub, so we can track in real time what they’re working on next, report bugs and sometimes submit code with some new features they can merge in.

The company is set up as a “public benefit corporation”, which basically means (in my non-US layman understanding) that it is a business and it’s meant to make profit, but that profit is not it’s only and main goal. It can and should have other, more noble goals that benefit the public, as the term implies, in this case: creating a protocol for decentralized social apps that everyone can build on.

At the moment, they don’t have a clear plan on how the company is going to make money on the platform – the general idea is to build some extra paid services on top for users and developers. They said they don’t plan to ever add ads and they promise they won’t “enshittify” the service in future. In any case, they’re explicitly building the network to be resilient even in the unlikely scenario that they themselves “turn evil” in the future – the network is meant to be “billionaire-proof”, impossible to completely take over by one guy with too much money. To quote the lead dev:

“Our culture doc includes the phrase “The company is a future adversary” to remind us that we won’t always be at the helm – or at our best – and that we should always give people a safe exit from our company. It’s weird at times to frame our priorities as protecting users from us, but that’s exactly what we’re trying to do.

The Bluesky team is made up of users. None of us come from big tech companies. We all came together because we were frustrated by the experience of feeling helpless about how our online communities were being run. We don’t want to give that same feeling to other people now that we’re the builders.

When we build an open protocol, we’re giving out the building blocks. We want to start from the premise that we’re not always right or best, that when we are right or best then it might not last, and that communities should be empowered to build away from us. Sometimes this can all feel very intangible and abstract, and for the average user the goal is to just feel like a good & usable network. But this is one big reason why we put all the Fancy Technology under the hood.

Also, contrary to what you might have heard, this isn’t “Jack Dorsey’s company”. Yes, he started it, but he isn’t running it, Jay Graber is. ~~Dorsey is still on the board with 1/3 of the vote, but~~ He was very little involved in the project after they started building. He basically gathered a team, gave them a lot of money and let them do their thing.

In fact, he deleted his account on the platform last summer, after he was booed off it by the users, and now he’s mostly hanging out on Nostr instead. In early May 2024, it was announced that Jack has left the board of directors too. He also doesn’t own any shares of Bluesky.

Apps

Bluesky has an official mobile app for iOS and Android. It’s written in React Native, so it doesn’t feel fully native in all places and some system integration features take a while to be added – the reason is that they’ve started with a very small team at first (I think initially just one guy did all the frontend), so the only way they could do it was to build for both platforms & the web from one codebase.

At this point, after various improvements over the last months, the mobile app is mostly ok and gets better with every update, it’s also obviously the most feature-complete one. One issue is that it doesn’t support iPad yet.

There is of course also a web interface, at bsky.app, which is pretty good – this is the main UI that I use Bluesky with. At the moment it’s mostly meant to be used while logged in, although some pages like posts/threads and profile views can now be viewed unauthenticated.

But there is also a small but enthusiastic group of third party developers building various apps, tools and experimenting with the protocol. They’ve built several independent apps, libraries to access the API in various languages, and they often manage to build various new features in their apps before the team gets around to doing that in official apps.

Here’s a few of these apps (in various stages of development):

Graysky – a mobile app, probably the most advanced one (though its dev is working for Bluesky now)
deck.blue – a web-based “Tweetdeck” column UI, written in Flutter
SkyFeed – a web app with a column UI that also lets you build custom feeds
Skeetdeck – another web-based, more lightweight “Tweetdeck”
Skeets – native iOS app with iPad support and some interesting features
Skywalker – a native app for Android
Skychat – a webapp initially built to let people form a “chat” around a specific hashtag
Sora – a new multi-network client for iOS

Additionally, there is also a third party bridge service called SkyBridge that allows you to use Mastodon apps like Ivory to use Bluesky (although of course it only supports a subset of features).

How are things called here?

The app generally uses “neutral” terms like “post”, “repost”, “feed”, “timeline” and so on. That said, pretty early on someone came up with with the word “skeet” for posts, for “sky + tweet”, and it stuck, despite (or likely because of) the team’s protests. So the term is used pretty commonly, though maybe a bit ironically, despite being a bit controversial because of its existing, other slang meaning (see Urban Dictionary)… By analogy, you can also “reskeet”, “subskeet” and so on.

The timeline/home feed is also sometimes called a “skyline”.

New users that have joined Bluesky recently are often called “newskies” – there is even a Newskies feed, which includes every new user’s first post (and only their first post).

On the opposite end, some folks sometimes jokingly call people with a long experience on the platform “Bluesky elders” (a reference to one post that was widely made fun of).

A “hellthread” is something that existed for some time in the spring of last year – the initial implementation of notifications notified you of any reply somewhere below your post or comment, to an unlimited depth. People have started creating extremely long and nested threads, which notified everyone involved of any reply, and there was no way to opt out of it. A certain community has formed around these hellthreads, of people who hang out together and sometimes waged wars in them. Eventually, the notifications were fixed, but due to protests, the devs have kept an option to still create hellthreads in one place, hardcoded in the app code. This was finally removed a few months later.

Feeds & algorithms

Social networks generally include two kinds of feeds: a chronological one, showing all posts from the people you follow in order, and an algorithmic one, showing what the service thinks you will like (which often means though: what they think will bring them more profit). Centralized platforms generally push you towards an algorithmic feed and often make the chronological feed harder to reach (if at all). Mastodon on the other hand only includes chronological feeds and no algorithms.

Bluesky has both – and much, much more.

The default “Following” feed is a classic chronological feed ~~although with a twist – by default it shows you more replies from the people you follow than on Twitter or Mastodon~~. You can configure a lot of aspects of that feed in the settings (see the Settings section), e.g. how many replies you want to see in it.

The “Discover” feed is Bluesky’s main algorithmic feed – it mixes some posts from the people you follow with some other posts that you might like. You can pick the option “Show more like this” or “Show less like this” from the menu on each post to give it some hints on what you like or don’t. The devs are constantly tweaking it and asking for feedback, so it should be getting better over time.

But that’s just the tip of the iceberg. Bluesky has built a system where anyone with a server and some knowledge of coding can implement their own algorithmic feeds that they can share with everyone else. There are currently about 40 thousands of custom feeds (as of Feb 2024) made by the Bluesky community that you can add to your app. And more importantly, the “Following” and “Discover” feeds are just what you start with by default – you can set any of the thousands of other feeds as your default, and you can even remove the two built-in feeds if you don’t like them, and leave e.g. only the “Cat Pics” custom feed as your only feed tab. Nothing here is forced on you.

The way a feed works is that it basically reads all new posts on Bluesky from a giant stream and decides which of them to keep and how to arrange them (this can be a shared feed, same for everyone, or a personalized feed that looks different to each user). Most feeds match posts by keywords – these are feeds on some specific topics like Linux, food, gardening, climate change, astronomy, and so on. They usually define some sets of words, phrases, hashtags, sometimes emojis, and include all posts that contain any of these, chronologically.

There are also various “top posts of the week / all time” feeds, posts using AI models to match some specific kinds of photos like pictures of cats, frogs, or moss, or personal algorithmic feeds that show you posts selected for you according to some specific idea: posts from your mutual follows, from people who follow you, posts with photos only, posts from your friends who post less than others, and so on. These are all feeds built by third party developers who just had an idea and implemented it, without having to register or apply anywhere or ask anyone for permission.

There is also a very popular web tool called SkyFeed, built by one German developer, which allows you to build some of the simpler feeds using a web form, without having to write code or host it yourself. This allowed a lot of people without programming knowledge to build their own feeds – currently around 85% of all feeds are built in and hosted by SkyFeed.

There is a feed search engine integrated in the official app, in the Feeds tab (the “Discover new feeds” section). You can also search for interesting feeds on these two external sites:

Goodfeeds also has a nice guide to feeds that describes them in more detail, there is also a blog post on Bluesky’s blog.

Safety & moderation

Like on most other networks, you can mute someone if you find them annoying, or you can block them if you find them really annoying. ~~There is no way to mute words and phrases yet~~ It’s also possible (added in February) to mute words, phrases or hashtags. There’s currently no way to mute something or someone for a specific period of time, but that will hopefully come at some point.

(Note, the blocking mechanism here is pretty aggressive, in that it also hides all previous interactions between the two users *for everyone*; so don’t be surprised if someone blocks you and your reply or quote “disappears” – it wasn’t deleted, just hidden.)

You can also create whole “moderation lists” for muting or blocking some groups of people at once, which can be shared with others. This is meant to let various communities on Bluesky build their own “defences”, by collecting lists of people who are unpleasant or annoying in some way and letting others mute or block them all at once before they come across them.

Bluesky itself seems to be pretty light on moderation so far, which some people criticise them for. That said, I think they generally get rid of obvious trolls pretty quickly, and I’ve personally only ever come across a few of those. They claim to have around 20 people in the moderation team right now (as of February), which is about half the total company size.

The general high-level plan for moderation at Bluesky and on the AT Protocol is something they call “composable moderation” (old blog post) or “stackable moderation” (recent post). It’s an idea that moderation will have many layers – from server operators including the Bluesky company, through various tools and services provided by other companies, organizations, and communities, ending with some ways to privately personalize your experience according to your personal needs.

Labellers

A core part of this is a feature called “labellers” that they’ve released in March, which are basically third-party moderation services. They work by assigning a set of labels/tags (manually or automatically) to accounts and posts – this can be because one of the labeller’s moderators has come across an offending post, or because it was detected automatically using some custom software, or because the post or account was reported to the service by a user (users can send moderation reports to any set of these services).

All users on the platform can “subscribe” to one or more of these services and configure how they want these labels to affect their experience: for any label type, they can choose if the user/post marked with such label should be hidden from their view, just marked with a label, or if this kind of label should be ignored. (A labeller doesn’t have the full power of a built-in platform moderation in that it can’t just ban someone from the site and delete their account – but they can make someone effectively disappear for those users who trust and agree with the given service.)

Labellers are usually specialized in some area: they could be protecting their users from things such as racism, antisemitism, or homophobia; they could be automatically detecting some unwanted behaviors like following a huge number of people quickly; marking some specific types of accounts like new accounts without an avatar, or accounts from a different network; fighting disinformation or political extremism; or they could be serving a community using a specific language or from a specific country.

A simple labeller can be run by one person, but the bigger ones are managed by a whole group of people that collaborate on processing the reports. This system allows different communities to handle moderation in their own way independently, to make their members feel safer and have a better experience in the aspects that are important for them. And most importantly, different communities could often have somewhat conflicting or even completely opposing views on some things – and Bluesky as a company doesn’t have to try to satisfy everyone (which is impossible) or always pick a side. They also don’t necessarily have to specialize in every country, language and culture on Earth. Of course they reserve the right to take down some accounts completely, because some things and some people have to removed from the platform for everyone (e.g. things that are just illegal), but in less serious or less clear cases, they can just use labels or defer to other labellers (the Bluesky built-in moderation is now “just” another labeller among many others, using the same API, and with only some special powers).

You can read more on this topic in the guide titled “Bluesky Crash Course: Labelers” written by Kairi, who used to run one of the most popular labellers called Aegis (now defunct).

There’s no easy way to search for labellers in the app yet, but I’m keeping a rough list myself on this page. I also made a “Label Scanner” tool where you can find all labels assigned to a given account from any labeller.

Privacy

One important thing from the privacy aspect that may not be obvious at first, which you need to be aware of: the underlying protocol on which Bluesky runs is extremely open. Anyone who knows how to code can write an app or tool that can read practically any data about anyone, without having to ask anyone for permission (since there’s no central authority that can require registration and payment to get API keys like on Twitter). This is by design, because all the different pieces of the network that make it work, apps, tools and services, need to be able to access the data to provide their functionality, and we want everyone to be able to build those to keep the network decentralized and not controlled by one corporation.

This has both advantages and disadvantages. For a developer, it means that the only limit is your time and imagination (and maybe API rate limits). You can build feeds that show all posts with cat photos, a bot that responds to the text “/honk” with a random photo of a goose, implement some new features before the Bluesky team gets around to that, count the statistics of how the percentage of languages used in posts has changed over time, and whatever else you can think of. You don’t have any monthly quotas or paid plans.

For a user though, this means that everything you do is very public – kind of like it was on Twitter, just more so, because there are fewer restrictions.

Specifically, all of these are publicly accessible (even if they aren’t all displayed in the official app):

your posts
your likes
the photos you’ve attached to posts
all the handles you’ve previously used (you can’t delete those)
the list of people you follow
the list of people you block (!)
the user lists and moderation lists (mute/block lists) that you’ve created
which moderation lists (yours or others’) you are blocking people with

And these things are private and known only to you (and the apps and tools that you’ve explicitly granted access to your account):

the people you’re muting (individually or through lists)
the words, phrases, hashtags etc. that you’re muting
your selected languages and other preferences
your email address, birthday and phone number
who invited you and who you have invited
the moderation services you’re subscribed to
the custom feeds that you’ve saved or pinned
- one caveat though: the provider of the feed knows when you are opening it

DMs are private between you and the person/people you’re chatting with, but they’re not currently end-to-end encrypted, so the Bluesky team can theoretically access them. A fully encrypted version will come later.

The difference between muting and blocking is because muting is simply a filter applied only for you – nobody else needs to know that you’ve asked your app to hide some of the posts. On the other hand, blocking is inherently a two-way thing – that other person, their app/server and any other pieces of the network that process their posts need to be aware of the block, so that they can prevent them from interacting with you. So the fact that the block exists needs to be publicly known.

Now, what all of this can mean in practice:

anyone can download anyone’s posts and do various targeted or global analysis on it, track your likes and contact graph and so on
if you are posting personal photos, especially NSFW photos or photos that can be geolocated, anyone can be downloading all of them automatically (though the official apps strip metadata from photos)
some (any) companies can potentially train some kind of AI models on the data (speaking purely about technical possibility, not legality of course)
blocking someone only adds friction, but it can’t completely prevent them from seeing your posts (same as it always was on Twitter until recent changes, since you could always open a post in an “incognito” window)
there is no way to add a feature that would let you “lock” a profile for followers only, hiding your content from others, because all post data has to be public for the network to work
copies of any posts you delete might still remain on some third party servers

Some of this might sound scary, but most of this is or was always the case on other social networks too, those that have APIs at least – if you’re posting something publicly anywhere, you need to realize that anyone can record it forever. The main difference is that it’s easier to do it here, because the API has fewer restrictions than on centralized platforms, and that it’s currently not possible to do any semi-private content that’s visible to some people but not to others.

Account security

For logging in to third party apps and tools, there is currently a temporary system of “app passwords” in place. It will be replaced with something more robust (OAuth) soon.

At the moment, when you log in to an app other than the official one, you should use a special one-time password that you can generate in the official app (Settings / App Passwords). Those passwords look something like this: abcd-ef56-vxyz-qq34. You can generate a separate password for every tool and app that you log into.

An app password grants almost the same privileges as the main password, but without a few critical ones, and you can revoke it at any time from the Settings screen if you’re not using that app anymore, which disables access to your account for that app. You can also specify if the app password should give the app access to your DMs or not.

There is now a simple email-based Two-Factor Authentication (2FA) feature, added recently. A more complete 2FA system is coming soon.

Handles & IDs

Bluesky has a really cool system of handles. They couldn’t have just used single-element handles like “@donaldtusk”, because that wouldn’t really make sense in a decentralized system. They also didn’t want to bind your account permanently to the name of the server you’re on like in Mastodon, where you’re e.g. “ivory@tapbots.social” and you can’t change that unless you make a new account.

So here’s what they’ve come up with: internally, your account is identified by a unique identifier called “DID” (Decentralized Identifier), which is an ugly string of random letters. To that DID you assign a handle, which you can switch at any moment to a different one, and any contacts, references and connections will (mostly) stay intact; and the handle is actually just any domain name, usually displayed with an “@“ at the beginning, but without any additional username before it.

By default, when you first join Bluesky (the current official server) you’re given a handle which is a subdomain of bsky.social, e.g. “dril.bsky.social”. This is a real domain name, you can type it into the address bar of the browser and it will redirect you to your profile on Bluesky.

But at any moment you can switch to a different handle by assigning any domain name that you own. It can a very short name like retr0.id, or something long with one of those quirky new TLDs like .horse or .computer, or it can even be a very official sounding domain like washingtonpost.com.

There are two ways to assign a domain, either via HTTP by putting a file in a specific place on the website hosted on the domain, or via DNS by putting a new entry in your domain configuration – the complete instructions are here. (BTW, Bluesky also runs a service that resells and automatically configures domains through a partnership with Namecheap, which is the first of possibly many premium services that they want to actually make money on.)

This also means that you don’t need to rush to “reserve your handle” at ***.bsky.social – because custom handles are cooler anyway 😎 (although be aware that if you change your handle from ***.bsky.social to a custom domain, that old handle becomes available for others again).

This system also makes it much easier to move your account to a different server – you can take your content and connections with you and keep your existing identity, because your DID identifier never changes.

What is this federation thing?

The goal of Bluesky is to be a network that consists of many, many servers run by a lot of different companies, organizations and people that connect with each other – that’s roughly what federation means. Initially, all the critical pieces were controlled by Bluesky PBC; however, this is now starting to change. The team has been working hard preparing everything needed for the launch for the last few months (which is partly why some of the more user-facing features had to wait), and now they’ve taken a big step towards federation by letting people migrate their accounts to self-hosted servers. This will be a gradual, controlled rollout, so that they have a chance to test how things are working, but the network is really starting to open up now.

If you’re worried that things will get more complicated, maybe you have some bad experiences from Mastodon – then don’t worry. They’ve specifically designed everything to be less confusing. The accounts on the platform have actually already been spread out on a number of separate servers for a while now (though all controlled by Bluesky) – they’ve been migrated sometime in November, and few people have noticed, because everything just kept working. Now, you will have an option to move your account to a server controlled by someone else, if you want to – but you’ll be able to just ignore the whole thing if you don’t care about it.

Note, Bluesky opening to federation does not mean that it will connect with Mastodon servers, since they use different, incompatible protocols. There is however a third party “bridge” called Bridgy that has started operating recently. The way it works is that it “mirrors” Mastodon accounts and their posts to Bluesky or Bluesky accounts to Mastodon (for accounts that have enabled the bridge). It’s possible to create whole threads where some replies are made by Mastodon accounts and some by Bluesky accounts, all of them being visible in both places.

Search

It took a while, but search works pretty well now on Bluesky. You can search for words, phrases and hashtags, and sort by popular posts or by latest. This is a global search like on Twitter, so it finds posts from everyone everywhere, not like the limited full text search on Mastodon.

You can also add “from:some.handle” to find only posts from a given user, or “from:me” to search within your own posts. There are several more filters available, like filtering by date or by language, although there’s no easy UI for them yet – but the Bluesky team has posted a tutorial “Tips and Tricks for Bluesky Search” on their blog recently.

Hashtags

Hashtags have been partially implemented since last autumn – the protocol specifications were ready and the official app was actually encoding hashtag data into posts for a few months, but it wasn’t displaying them in the UI (although that did work in some third party apps). Full support was finally added in February. When you click on a hashtag you have an option to search for all posts with this hashtag, only posts from the given person, or to mute that hashtag.

One thing that’s defined in the protocol but not implemented yet is that hashtags will eventually have two forms: inline tags like on Twitter, and external tags which are shown below the post, which I think is the way they work on Tumblr (Mastodon also recently started showing trailing hashtags at the end of a post as somewhat separated visually from the text). You will be able to use either or both in a post according to your preference, and they will be interchangeable, with both being returned in the same search.

Settings

Some things that you may want to change in the settings:

Languages – turn on all the languages that you understand or want to see; Bluesky generally hides posts in languages that you don’t have enabled from most places like your home timeline or feeds. For your own posts, you set a post’s language yourself in the compose post window – you can switch between a few languages, and if you have the wrong one set when writing, a popup with a warning should appear.
Thread Preferences – you can choose to have threads sorted by newest, oldest or most liked comments; there is also an experimental nested (tree-like) thread view that I highly recommend enabling (although for longer threads you may want to use my tool Skythread instead :]
Following Feed Preferences – choose if you want to see replies, quotes, reposts etc. in the home feed.
For replies, you can set a threshold of how many likes a reply needs to get to show up in the feed, and you can also choose to see all replies made by people you follow to anyone (this used to be the default, although now it’s turned off initially for new accounts). This option is actually pretty nice when you don’t follow many people at the beginning, because it’s a great way to find new people to follow – but it may get too noisy when you follow a lot of active people.

So you can set this according to your preferences – if you’re just starting, you can turn on replies to everyone even with 0 likes, and if you want to trim your timeline a bit, set it to “followers only” to make it work like on Twitter, and/or increase the likes threshold.
Chat Settings – who you want to be able to contact you via DMs: everyone, no one, or only people that you follow yourself (default is people you follow); conversations you’ve started before are accessible even if you change the setting
Moderation » Content Filters – here you can set what kind of potentially objectionable content you may want to show or hide – generally various NSFW things. I’m not sure what the defaults are currently, but it’s worth checking and tweaking to your preferences. (Watch out, there can be quite a lot of somewhat NSFW content there that you can randomly come across in some feeds, although it’s generally hidden behind a content warning.)
In the “Advanced” section below, you can adjust which of the moderation labels from each specific labeller you want to apply in your feeds – this includes the built-in “Bluesky Moderation Service” labeller.
Accessibility » Require alt text before posting – you can turn this on to always be reminded to set an alt text on photos (it’s generally considered nice to add the alt text to images whenever possible, for people who use tools like screen readers or VoiceOver)
Accessibility » Disable autoplay for GIFs – prevents gifs from automatically playing in the feed, instead you get a play button on each that you have to press first to see it

Missing features

There are a few things missing on Bluesky that are available on some other networks. Some of these are limitations of the protocol, and some are just a matter of too much work and too few hands to do it – the team is still pretty small and they have a ton of things to build to catch up with more mature platforms (Mastodon) or those with more people and funds (Threads), and they need to prioritize and some things are always put off.

That said, in recent months they’ve started accepting outside contributions and some recent features have actually been submitted as PRs from external developers.

Some things that are still missing:

Private profiles / circles

Like I’ve mentioned in the Privacy section, the AT Protocol as built currently requires all data apart from your private settings to be completely public. There is no way to make something that you only share with some people but not others. There may very well be something like this in the future, because a lot of people are asking for this and the team wants to look into it – but they will have to first invent some other, separate way to share content in the protocol, which will take a lot of time and thinking. So it’s likely to come at some point, but not anytime soon, because it’s much harder than it may look.

DMs on the protocol

For the same reason, sharing messages with only one or a few people using the AT Protocol is currently not possible. The team wants to eventually add DMs to the protocol, but this is something that will require a lot of research first.

But since *a lot* of people wanted to have some way of talking privately with friends, even if it’s an imperfect one, the team has recently added a simple implementation of DMs that isn’t currently a part of the protocol. The DMs are currently using a single centralized service hosted by Bluesky (although third-party apps can access this API), and are not end-to-end encrypted. The first version also doesn’t support group chats and images, only 1-to-1 text chat – but more features are coming soon.

Eventually, the team wants to figure out and add a more full-featured, decentralized and private version of DMs (which may involve integrating with some existing private messages standard). This is however pretty far down the list at the moment, so something not likely to come this year.

GIFs & video

Another pretty obvious missing thing is a way to upload gifs (with a hard “g”) and video.

The problem with video is a lot higher bandwidth and storage use than with text and images, but more importantly, it’s also a lot more moderation work. There are all kinds of ugly things that people could upload in video form, and someone has to check it all if it’s reported… Gifs should generally be easier to do at first glance, but in practice they’re just another form of video, just shorter and without audio, so the above problems also apply.

For now, they’ve added two partial solutions to this. The first one is a way to embed e.g. YouTube videos and gifs from Giphy and Tenor in posts, which will play inline inside a post when clicked. For Giphy gifs, you need to paste a direct link to the image, and for Tenor gifs, a link to the page. This whole feature was actually implemented by a third party developer.

A more recent addition is a built-in support for adding Tenor gifs from the post compose dialog, by pressing the gif button and picking something from the gif search dialog. Here, only Tenor is supported. In both cases, they’re kind of offloading both the bandwidth/storage problem and the moderation problem to other services.

That said, they’ve recently started working on full support for (short) video and uploadable gifs. It will probably take some time, but this should be available in near future.

Post editing

This will definitely be added at some point, but it’s also a relatively complex feature, because of the need to store the previous versions of an edited post that you should be able to access somehow. They want to do it right and that will require some thinking on how to solve the problem in the most general and elegant way.

Soft-blocking / removing followers

There is an issue currently that there is no way to remove someone from your followers except by having them blocked. If you block-and-unblock them, what some people call “soft blocking”, they stay on the followers list. This is a current limitation of how follows are designed in the protocol – when someone follows you, they do it by adding a “follow record” to their account, and only they can update or delete their own records, you can’t do that from your side.

I think this is likely to get fixed at some point with some kind of workaround, but it’s not trivial to add and not high priority at the moment.

Polls

This might be a bit tricky, because we probably don’t want to have everyone’s poll choices public to everyone, and right now everything is public… But this is also one of those things that people ask about regularly, so I hope they’ll figure something out.

Showing post quotes

Bluesky has had support for quote-posting like on Twitter since the beginning and quotes are widely used on the platform. However, there’s currently no way to see a list of all quotes of a given post (although you do get notified when someone quotes you).

I’ve added a quote search to my tool Skythread – paste the link to the post into the search bar and then look for a “quotes” link below the post when it loads, and click it to see the list of all quotes. Alternatively, there is also a feed of all quotes of all your posts made by @flicknow.xyz (but this only works for your posts).

Trends

It would be nice to have some kind of “currently trending” screen like on Twitter. I think it would make Bluesky a better place for learning quickly about current events and hot topics, which was something that Twitter was always good at, and make it easier to find interesting things to read.

It should be pretty easy to implement technically – there’s already a bot that someone made at @nowbreezing.ntw.app, which posts “tag clouds” of trending words & phrases every 10 minutes, other developers have also implemented it e.g. in Graysky, Skeets or SkyFeed. The main problem is probably in deciding (automatically) which trending words to promote and which should be hidden… it will probably require a lot of manual control at first to keep it safe.

Verification

It’s hard to implement verification in a decentralized network, but the good news is – there’s no need to! The system of domain names in handles serves as a way of verifying accounts.

If someone has a handle that matches the domain of e.g. some newspaper, organization or government branch that you recognize, you can assume that the account is operated by someone who was authorized by that entity. So e.g. @wyden.senate.gov is definitely US Senator Wyden (or at least his staff), and @nytimes.com is definitely The New York Times. No one has to manually verify their documents to vouch for them.

If you’re setting up an account for some well known organization, it’s highly recommended to switch to your domain as the handle from the start to make it clear that it’s an official account.

OAuth and full 2FA

Coming soon, see the “Account security” section.

Longer posts

This seems to have been a conscious decision that the team wanted to create a medium that’s more like Twitter than like Mastodon when it comes to post length (although Jack Dorsey apparently disagreed). This isn’t a simple matter of a field length, because this affects the way people communicate, and allowing longer posts has advantages and disadvantages, it’s just a different text form. (See a comment from lead dev about this.)

So it looks like this won’t be changing – although there might later be other “apps” implemented on the AT Protocol that aren’t a part of Bluesky that will allow longer posts, even complete articles, and they might be somehow integrated into Bluesky in the future (e.g. posts bridged from Mastodon by Bridgy, which can be up to 500 characters long, include the full original content in the record data and apps may choose to display the full text inline).

Bookmarks

It’s on the list, but no timeline at the moment.

Links on the profile, pinned posts, scheduling, disabling reposts per user…

I haven’t heard much about those, but I’m assuming it’s all coming at some point once they get through the hard stuff they’re busy with now.

Other tools

Finally, here are a few tools written by third party devs that you might find useful:

Firesky – a site that shows you a live feed of every single new post made on Bluesky – feels like watching the Matrix screen
Clearsky – lets you look up the list of all people that are blocking you (or someone else), or the mute/block lists that you’ve been added to
wolfgang.raios.xyz – also shows your blockers, block statistics and can generate “interaction circle” images that show who you mostly keep in touch with
Jaz’s Profile Cleaner – lets you delete old data (old posts etc.) from your account
PLC handle tracker or internect.info – these let you look up the DID of an account and how the assigned handle has changed in the past
Jaz’s post stats (and mine)
Atlas, a “bird’s eye view” map of Bluesky (warning, takes some time to load)
Skythread – a thread reader by yours truly, mentioned earlier :]
Label Scanner, for checking if there are any labels assigned to an account or post

And some other guides (some mentioned earlier in the blog post):

Bluesky Social New User Guide (Kairi, Nov 2023 – archived)
How to get started on Bluesky (Emily Hunt, Nov 2023)
Bluesky user FAQ (Bluesky, May 2023)
The Newskies' Guide to Safety and Privacy on Bluesky (eepy, Oct 2023)
Bluesky Crash Course: Labelers (Kairi, Apr 2024 – archived)
The Guide to Feeds (Jerry Chen)
Algorithmic Choice with Custom Feeds (Bluesky, Jul 2023)
How to set your domain as your handle (Bluesky, Apr 2023)
Tips and Tricks for Bluesky Search (Bluesky, May 2024)

Thanks to Mozzius, Shreyan and Marshal for the feedback on the first draft :)

Changelog:

24 Jun 2024: removed link to Aegis (rip)

19 Jun 2024:

added info about built-in Tenor GIFs and DMs
added new section about labellers
Jack Dorsey is no longer on the board
updated some mentions about the Mastodon bridge, which is now live
some changes to feeds section - defaults for Following have changed, Discover is now much better, and you can remove the default feeds

26 Mar 2024: added mention about handle history in the Privacy section

2 Mar 2024: hashtags and word muting are now available, updated the part about longer posts

23 Feb 2024: federation is live!

21 Feb 2024: search now returns results when you search for a hashtag.

2023: Year of social media coding

2023-11-09T14:46:07Z

I had different plans for this year… then, Elon Musk happened.

Elon took over Twitter in October last year, which set many different processes in motion. A lot of people I liked and followed started leaving the platform. Mastodon and the broader Fediverse, which has been slowly growing for many years but never got anything close to being mainstream, suddenly blew up with activity. A lot of those people I was following ended up there.

Then, Twitter started getting progressively worse under the new management. Elon’s antics, the whole blue checks / verification clusterfuck, killing off third party apps and effectively shutting down the API, locking the site behind a login wall, finally renaming the app and changing the logo – each step made some of the users lose interest in the platform, making it gradually less interesting and harder to use.

Changes, so many changes… and things changing meant that I had to change my workflows, change some plans, build a whole bunch of new tools, change plans a few times again, and so on. My GitHub looks like this right now, which is way above the average of previous years:

As usual, I ended up writing way more Ruby and JavaScript than Swift, which goes a bit against my general career plans – but I’ve built so much stuff this year and I had a ton of fun doing it. So in this blog post, I wanted to share some of the things I’ve been working on lately.

The Dead Bird Site 🦤

I had a bunch of private tools written for the Twitter API. For example, I had a script that downloaded all tweets from my timeline and some lists to a local database. I was also running various statistics on tweets, e.g. which people contribute how much to the timeline and list feeds, and automatically extracted links from tweets from some selected lists.

And then Elon shut off access to the API (unless you can afford $100 per month for a “hobbyist” plan), which meant I had to try to find other ways to get that data.

I quickly got the idea that I could somehow intercept the JSON responses that the Twitter webapp (I refuse to call it the new name, sue me) is loading from the JavaScript code. The JSON responses are very complicated with a lot of extra content, but they do contain everything I need. The problem is how to get them; I wanted to get data from my personal timelines, so I couldn’t do anonymous requests, and I didn’t want to make authenticated requests for my account from some hacked-together scripts, for fear of triggering some bot detection tripwire that would lock my account.

So the approach I settled on was to passively collect the requests in the browser, using Safari’s Web Inspector, and export them to a HAR file that can be parsed and processed like the data from the public API. (It would be even better to have a browser extension that intercepts XHR calls on twitter.com automatically, but as far I can tell, there is no way for request monitoring extensions to look at the content of responses, unless you inject scripts to the site.)

I initially tried to implement it as a Mac app, which gave me a chance to start experimenting with Core Data a bit. But in the end, I rewrote it in Ruby and released it as gem I called “BadPigeon” – named after the friends who visit my balcony every day 🐦

The gem is designed to output extracted data in the same form as the Twitter API, in a way that can be plugged into the popular twitter gem, so I could use all existing tools I had written with very little changes. The obvious downside is that it needs some manual help with the recording first, but I can live with that. I’ve been using this setup since June and it works pretty well for me so far.

I had one more Twitter-related project that I sadly had to shut down though – the Rails Bot which has been running non-stop since 2013, mostly unattended, picking and retweeting tweets from some developers in the Ruby community. It requires access to the API to fetch its home timeline periodically from crontab, so I couldn’t make it work this way.

mackuba ∕ bad_pigeon

A tool for extracting tweet data from GraphQL requests made by the Twitter website 🐦

Mastodon’t 🦣

As the migration of developer communities out of Twitter started, I was initially skeptical; looking back, I guess I just had to go through the “five stages of grief” at my own pace… I also didn’t initially see the change as that bad as some others did, and to be honest I still don’t – to me, Twitter still isn’t literal hell on Earth, it’s just that month after month, it got progressively less useful, less interesting and more annoying.

So I finally started looking at Mastodon with interest. The idea of the “Fediverse”, a distributed system of many independent servers with a completely open API, where I don’t need to pay absurd prices for an access key, don’t have monthly download limits and which can’t be taken over and locked down, was appealing to me.

You see, I’m a bit crazy about data hoarding and processing information – for many years I’ve been having various ideas about tools I could write to somehow automate finding more relevant content in the noise of social media, to let me waste less time on it while still finding what’s important (the Rails Bot was a very early example of that). So I thought that maybe in this new open world, where the only limit is my imagination, I could build any tools I ever wanted and share them with others.

Well, turns out it’s not that simple…

It’s true that the Mastodon APIs are completely open and generally permissionless; for example, you can easily download any account’s complete history of “toots”, going as far as a few years back, anonymously. The problem is that there is a certain culture of the existing community of the Fediverse that was there way before the great migration, which is extremely against any kind of data collection, archiving and indexing. Making information searchable – information which is broadcasted in the open to the world – is seen as a threat to safety, and anyone who attempts that is labelled a “tech bro”, derided and attacked.

Sometime in winter I went down the rabbit hole of many, many threads discussing several of such tools, with the authors being attacked and told that they shouldn’t have built them. Just by mentioning in one of the threads that I’m thinking about building a Mac app that allows you to search the history of your home timeline, I got called out on “#fediblock” (Fediverse’s popular channel for warning about bad actors) as someone worthy of blocking.

All of this has very quickly cured me of any ideas to build pretty much any public tool for the Mastodon API. I just don’t have the energy and mental strength to deal with people attacking me this way for simply building tools on an open API that they don’t like.

What I ended up doing though was setting up my own personal Mastodon instance, martianbase.net. I joked that I’m probably the only person who hates Mastodon and also has their own Mastodon instance… But the first instance I signed up on last year was shut down unexpectedly, giving me no chance to migrate the account. That’s another thing I dislike about the ActivityPub system – your account identity and data is bound to the domain of your instance, and there is no easy way out if your admin misbehaves or disappears, or just has a different view on which other servers you should be able to talk to. So at that point I decided not to trust another instance admin, but to set up my own place, so that I can have full control over it.

Blue skies ahead 🌤

And then, just as Twitter was slowly going down and Mastodon has disappointed me – I started hearing about Bluesky.

Started as an idea of Jack Dorsey from Twitter back in 2019, with a goal of building a “decentralized Twitter” that Twitter itself could possibly one day be a part of, the project has been going on for a few years, and just as the whole Twitter chaos started, Bluesky got to the point where it could be presented to the world.

(Important note here, since media has widely promoted Bluesky as “Jack’s social network” and his name puts a lot of people off: it’s not in fact Jack’s social network. He’s not the CEO (a woman named Jay Graber is), he does not manage or control the company, and AFAIK he’s actually been very little involved in it recently, having mostly switched his interest to Nostr – to the point that he has even deleted his Bluesky profile.)

The attention and interest that Bluesky has received after lauching an invite-only beta has widely exceeded the team’s expectations, but this was both a blessing and a curse. They weren’t really prepared to run a real Twitter competitor that could accept the “refugees” escaping Elon’s playground. The thing is, they were mostly focused on the underlying protocol before, and the site itself has been launched as a bit of a demo. A lot of things that people consider pretty essential in a social networking site weren’t ready. But the team – which at that point was less than 10 developers in total, AFAIK – started adapting to the new reality, working as hard as they could to make the site usable for much larger crowds that they had been planning to.

I got access to Bluesky in late April. I don’t want to get into too much detail here about what it’s like, how it’s evolved since then and so on – I’m going to write a few more blog posts about Bluesky specifically. But long story short, I was completely hooked from day one.

Yes, it’s invite-only, has a much smaller userbase than the Fediverse, it’s an early beta, it doesn’t have videos, gifs or even hashtags. The iOS/Swift developers there are as rare as a unicorn. But it has a really nice community of users, third party developers who hack on various tools and help each other, and team members who interact with us on the site all the time. It looks and feels more like Twitter than Mastodon does, and it somehow just feels more fun to be on.

But the thing that excites me the most is the AT Protocol it’s built on and its potential. It’s a completely open federated protocol, just like ActivityPub that Mastodon uses, and it’s intended to eventually create another “fediverse” of distributed social apps (though the federation part is not live yet, but coming soon). It’s designed to take some lessons from what doesn’t work well in ActivityPub (and would be hard to change) and design the architecture better. For example, it uses “Decentralized IDs” (DID) independent of the hosting server to identify accounts, which makes it easy to migrate accounts between servers (and your handle can be any domain name you own, like @mackuba.eu).

The code it’s running on is open source, the APIs are completely open, and it all just invites you to write some tools and libraries for it – to be the first person to write a Ruby library, a Swift SDK, a command line client, a website with statistics. To be the first to plant a flag where others will come later.

I’ve been spending most of the time since April working on one Bluesky-related project after another, sometimes switching between a few in parallel. In the rest of this blog post, I wanted to show you some of the things I’ve been busy building:

Minisky

On the first day after I got in, I already started digging in the API and I wrote a small Ruby script for archiving my timeline and likes (of course I did…). This eventually evolved into a Ruby gem I called Minisky, which provides a minimalistic API client that handles logging in, refreshing access tokens, making GET and POST requests to the API and returning parsed JSON responses.

It doesn’t include any higher-level features like “get posts”, you have to know the name of the endpoint, what params to pass and what fields it returns, but it handles all the basic boilerplate for you. I use it as a base for some internal scripts, and for manually getting or sending some data to the API in the Ruby console. If you want to start playing with the Bluesky API or build some more specific tool that uses it, you can give this library a try (see the example folder for some ideas). It has no dependencies apart from Ruby stdlib.

mackuba ∕ minisky

A minimal client of Bluesky/AtProto API

Custom feeds on Bluesky

Bluesky has a really cool feature that I think is pretty unique among all the social networks. On social sites, you normally have either a reverse-chronological timeline of posts from the people you follow, or some kind of algorithmic “home” feed that mixes them up with other suggested posts, in a way that you usually don’t fully understand and may not like (or both of these feeds).

Bluesky has both of these, but it also lets anyone build a custom feed that selects and orders posts however you like, and most importantly, lets you make this feed available to everyone else. Custom feeds are a core feature of the app; it lets you browse popular feeds from other people, feeds are listed in a separate tab on the feed author’s profile, and you can “pin” the feeds you use often, which puts them in the top bar in the mobile app, as if it was another built-in timeline. People build all kinds of feeds – thematic feeds like various scientific or art or NSFW feeds, feeds for specific communities like “Blacksky”, general “top posts this week” feeds, or different variations of an algorithmic “home feed” using various approaches.

The way the feeds work is that you need to provide an HTTP service on your server which implements a couple of endpoints. The Bluesky server then makes a request to your service on user’s behalf when they want to view the feed, and your service should respond with a JSON that includes a list of post URIs. Bluesky then takes these URIs and turns them into full post JSONs that it returns to the client.

When the team launched this feature back in May, they included a sample feed service project implemented in TypeScript. But I’m not a big fan of JS/TS and Node, so of course I had to reimplement it all in Ruby :]

I’ve spent quite a lot of time working on the feeds and related code this summer, and the result of this is three separate Ruby projects that I’ve open sourced on GitHub (in addition to my main project which is private).

BlueFactory

The first part is an implementation of the feed service itself. I based it on Sinatra, and it implements the three API endpoints required from a feed service. You need to provide some configuration (hostname, DID of the owner etc.) and your custom class to call back to in order to get the list of post URIs and the feed metadata. If you want, you can further customize the server using the Sinatra API, e.g. adding some custom routes with HTML content.

Feeds can generally be divided into two categories: general and thematic feeds that return the same content for everyone, and personalized feeds that show the feed from a specific user’s perspective. The latter are usually much more complicated to build, since you will often need much more data of different kinds to generate the response, depending on your algorithm. If you want to build a personalized feed, the request includes a JWT token that you can use to get the requesting user’s DID, and the gem can pass that as a param to your class (although note that at the moment it does not verify the token, so it can be easily faked).

mackuba ∕ blue_factory

A simple Ruby server using Sinatra that serves Bluesky custom feeds

Skyfall

To return the post URIs from the feed service, first you need to get the posts from somewhere. You could possibly get them from the API, but realistically, a much better option is to connect to a so-called “firehose” web service and stream and save them as they are created, keeping a copy in a local database.

The firehose streams every single thing happening on the network, live – every new and deleted post, follow, like, block, and so on. Depending on your specific feed idea, you will usually only need to keep a small fraction of this data, e.g. only posts and only those that match some regexps – but you need to parse it all first to know what to keep. What further complicates things is that the firehose data does not come in a JSON form, but instead uses a bunch of binary protocols originated from IPLD/IPFS.

The second Ruby gem is meant to simplify this for you. It uses an existing CBOR library to do some of the binary protocol parsing and faye-websocket for the websocket connection. It connects to the firehose websocket on a given hostname and returns parsed message objects with the info about specific add/remove operations and relevant JSON records.

The firehose (and the Skyfall gem) isn’t only useful for creating feed services – you could possibly use it for any other project that needs to track some kind of records from the network in real time, whether it’s follows (to create a connection graph of the whole network, or to track when a follower unfollows you), or blocks (to find out who is blocking you), or to monitor when you or your company or project are mentioned by anyone anywhere. I’ve also included an examples folder with some sample scripts in the repo.

mackuba ∕ skyfall

A Ruby gem for streaming data from the Bluesky/AtProto firehose

Bluesky feeds template

This project puts the previous two together and combines them into an example of a complete Bluesky feed service, which reads posts from the firehose, saves them to an SQLite database and serves them on a required endpoint – basically a reimplementation of the official TypeScript example in Ruby.

This is a “template” repo, which means it’s not meant to be used as-is, but instead forked and modified in your own copy. The reason is there are simply too many things that you may want to do differently – deployment method, chosen database, specific data to keep etc., and making this all configurable would be an impossible task. Instead, I’ve extracted the “input” and “output” parts as separate gems that can be used directly, and you build the parts in the middle – but you can use this template project as a good starting point.

My own feed service project is a private repo, but I’m keeping it in a similar structure to this template and I’m manually backporting some fixes and new features from time to time.

mackuba ∕ bluesky-feeds-rb

Template of a custom feed generator service for the Bluesky network in Ruby

My feeds

And now we get to the part that all of this was for – building my own custom feeds.

I mentioned earlier that I often think about and experiment with various ways to find most relevant content to me on social media. So when I heard about the custom feeds feature, I immediately had an idea to build a feed for Mac/iOS developers that filters only posts on this topic, using a long list of keywords and regexps (I’ve actually reused a lot of work I’ve done a while ago for an unfinished thing I played with on Twitter).

It took me a couple of months to build all the pieces of the “feed generator”, but I’ve launched the Apple Dev feed in July. It isn’t very busy so far, to put it mildly, because there still aren’t that many iOS devs on Bluesky 😅 But as of today, it has 35 likes – only 50 likes less than the other Swift feed :]

Apart from the iOS dev feed, I’ve also made a more general macOS users feed and a couple of other feeds that were mostly a proof of concept / playground while building the service, but a lot of people seem to find them useful anyway, so I’ve left them running:

Skythread

The last one of my Bluesky-related projects, also with a “sky” in the name (most of the third party projects so far have either the word “blue” or “sky” as part of the name 😄). And this one is written in JavaScript for a change.

If you use Twitter and/or Mastodon a lot, you probably have the experience of reading some complicated thread and getting lost, not knowing who replies to whom or if you haven’t missed a whole part of the discussion. These two display branching out threads a bit differently – Twitter hides some of the branches, while Mastodon shows all direct and indirect replies in one flat list. In both cases, it’s not a perfect solution for reading some heated “hellthreads” that branch out endlessly. For me, a UI more like the one on Reddit would be ideal. (Bluesky has recently a thread view with limited nesting, as an experimental feature.)

So that’s what I’ve built, as a web tool. You enter a URL of the root of the thread on bsky.app, and it renders the whole thread as a tree. You can use the +/– buttons to collapse and expand parts of the tree, just like on Reddit, and if you log in, you can also click the heart icons below a comment to like it:

The initial version of Skythread required logging in first to see anything, but I’ve recently switched it to a different API that allows me to load whole threads without an access token. Note that the official Bluesky web app currently does not allow viewing any content unauthenticated – just like Twitter after the recent changes – so tools like Skythread, and other similar ones (e.g. Skyview) are the only way right now to share links to posts and threads with people who don’t have an account; but this is a temporary situation and Bluesky should be open to the world (for reading at least) in near future.

mackuba ∕ skythread

Thread viewer for Bluesky

One app to rule them all

So where can you find me now on social media? As you might have guessed from the earlier sections, I’m spending most of the time on Bluesky now; which may be a bit strange, because that’s not where most of my friends and follows from Twitter ended up. A large part of the iOS/Mac/Swift programming community has moved to Mastodon and stayed there, with some stubbornly sticking to Twitter or posting to both. Possibly also to Threads, which I don’t even have access to.

But there’s something about Bluesky and the AT Protocol that really draws me to it… I think it’s some combination of a nicer UI/UX, tech/architecture that I like more, a new community that is only just forming, and having this feeling like I’m blazing the trail, being able to build all the tooling that doesn’t exist yet. I like being part of something that’s being created around me, flying on that plane that’s being built in the air, watching the devs build it live and feeling like I’m part of it all. I enjoy being there, I really want it to succeed, and I want to help with that as much as I can.

So I have friends on all three platforms, and even though I spend most time on Bluesky, I check all three everyday, for slightly different content – Twitter for news, Mastodon for Swift programming, Bluesky for… dopamine? And since some people only follow me here and some only there, I end up manually cross-posting a lot of things to 2 or 3 websites.

Wouldn’t it be nice to have a tool, kind of like Buffer, that can let you post to Twitter, Mastodon and/or Bluesky in parallel? There doesn’t seem to be, so I’ve decided to build one myself :] This one isn’t available yet and it still needs a lot of work before I can call it an “MVP”, but it’s going to look something like this:

In the meantime, you can follow me here on any of these platforms – listed in the order of preference :)

Social media update - Elon's Twitter and Mastodon

2022-12-22T16:21:01Z

Update 01.03.2023: Updated Mastodon address - my previous instance has been unexpectedly shut down and I had to make a new account. I’ve decided to set up my own server to make sure it won’t happen again.

Update 09.11.2023: I made a follow-up post which talks about the social media related projects I’ve been working on this year, and about Bluesky, where I’m spending most of the time now.

This is just a small update about Twitter and Mastodon, since things have been… very unstable and chaotic in the last few weeks, as you’ve surely noticed if you log in to these even occassionally.

Twitter has been my internet home for over 13 years now. I started using it when my colleagues from Lunar Logic showed it to me, and especially in the recent years it’s been my main source of information and news. It’s where I went to keep track of what was happening in the Apple/Swift world, find useful tips about UIKit, SwiftUI or Xcode, follow the news, rumors and dramas on the Crypto Twitter, and find out every day what important thing was happening in the world, including following the Covid pandemic and the Russian invasion of Ukraine this year.

Like most of the people I’m following, I’m not very happy about Elon’s takeover and his actions, how he randomly makes changes to the rules based on his current mood, blocks journalists who write about him and how he fired or scared away most of the people who kept the site working. I’m worried about how the future looks for the platform, if Twitter will even exist in this form a year or two from now. I wish this all hadn’t happened, and I’m angry at the people who made it happen for their own gain.

But so far, Twitter is still working and is still a great place to get the news, tips and information about so many things. I’m not ready to give up on this site as long as the feed is loading and there are some tweets left to read.

I’ve been trying out Mastodon like everyone else and I slowly get more comfortable there, but it still feels a bit alien to me. It feels like when you move in to a new apartment and everything is different there than you’re used to, some things are missing, some things are better, some things are worse than in your old place, but a lot of your subconscious habits and muscle memory stop working. I had some ways of using Twitter that worked for me and a bunch of private tools I wrote for myself to help me automate some things - I will have to figure this all out again now.

So I am on Mastodon, if only because I don’t want to miss out on things, but I am still on Twitter and I’m planning to stay and keep posting there, as long as it stays usable. I will probably be posting more on Twitter than Mastodon, because I feel more comfortable there. I hope some of my friends and people I follow stay on the platform, or at least check in from time to time.

So here’s where you can find and follow me (updated 09.11.2023):

New edition of the "Guide to NSButton styles"

2021-12-30T14:28:59Z

Note (Oct 2023): The names of the buttons have been changed again in the SDK in macOS Sonoma - I will update the blog post again once I have Sonoma on one of my Macs :)

Back in October 2014 I wrote a post about different styles of NSButtons.

That was in the era of OS X Yosemite and Xcode 6. I started researching what each kind of button available in Interface Builder was for, because I couldn’t figure that out from Xcode and the built-in documentation - I dug a bit into the Human Interface Guidelines, some older documentation archives and into Apple apps themselves. I collected everything into a long post that went through all the button styles and described what I could find about each one.

It seems that a lot of people also had the same problem, because the post turned out to be extremely popular. It’s around #3 in total page views on this blog, and 7 years and 7 major macOS versions later it still usually comes out #2 in monthly or yearly stats and still gets a couple hundred visits a month. Even with greatly improved documentation in Xcode and much expanded content in the modern HIG, there’s clearly demand for this kind of information collected in one place.

However, the post was kind of asking to be updated for a long time now… The original screenshots were made in 1x quality, since I didn’t get a Mac with a Retina screen until the end of 2016. Big Sur was released in the summer of 2020, significantly changing the design of the OS, and making Catalina suddenly look outdated (to the point that I’ve seen some people already call the Yosemite-Catalina era design “classic macOS”!). Some new button variants were added, some older buttons were no longer used in system apps the way I presented them, and the button styles available in Xcode were no longer shown and described as shown on screenshots from Xcode 6.

The Big Sur launch seemed like a great moment to give that post a refresh, and I started working on it at the end of last year, but then 2021 came and this year turned out to be kind of rough - surprisingly more so than 2020… as it was for a lot of people, I suppose. I only managed to get back to this project this month.

I thought it would take maybe a week or two… it took around three in total 😬 That included setting up new Mavericks and Yosemite installations in VirtualBox to get updated Retina screenshots from there, building a number of versions of a sample app full of all kinds of buttons that I took a ton of screenshots of on several macOS versions, cutting every screenshot pixel-perfect to size a few times, merging different versions of the same information from a few different sources, including versions of HIG going as far back as 2006, looking through Apple apps searching for buttons, and view-debugging some of them with SIP turned off to check what controls were used there… whew 😅

I’m really happy with the result though. This is now by far the longest post on the blog, with around 11k words total (although around 1/3 of that is just quotes) and around a hundred images. I expanded a lot of the content, adding some things I hadn’t thought about last time and clarifying some that I hadn’t fully understood after I found some new information - and each button now has three different screenshots, sometimes even four:

Of course I’ve also learned a few new things myself and organized the information better in my head again, which is always my primary motivation when writing this kind of blog posts :) After Big Sur I don’t expect a next massive redesign for another few years, so I probably won’t need to repeat this anytime soon - but if macOS 13 or 14 changes some minor things here and there, I’ll try to keep the post up to date.

Read the updated blog post here - if you want to see the old version for some reason, you can find it in the Web Archive.

TypeScript on Corona Charts

2020-10-15T15:43:06Z

Back in spring I built a website that lets you browse charts of coronavirus cases for each country separately, or to compare any chosen countries or regions together on one chart. I spent about a month of time working on it, but I mostly stopped around early May, since I ran out of feature ideas and the pandemic situation was getting better (at least in Europe). The traffic that was huge at the beginning (over 10k visits daily at first) gradually fell to something around 1-1.5k over a few months, and I was only checking the page myself now and then. So it seemed like it wouldn’t be needed for much longer…

“Oh, my sweet summer child”, I kinda want to tell the June me 😬

So now that autumn is here and winter is coming, I suddenly found new motivation to work on the charts site again. But instead of adding a bunch of new features right away, I figured that maybe some refactoring would make sense first. I initially built this page as a sort of hackathon-style prototype (“let’s see if I can build this in a day”), but it grew much more complex since then, to reach around 2k lines of plain JavaScript – all in one file and on one level.

I started thinking about how I can make this easier to manage, and somehow I got the idea to try TypeScript.

Why add static typing?

I used to believe that static typing was just unnecessary complication.

My first programming experiments back in school were in Pascal and very bad C++. At the university, pretty much everything was either plain C or Java (or C#, depending on which group you picked). It was only near the end of the studies that I suddenly discovered Python and later Ruby, and it was like a breath of fresh air. I also read Paul Graham’s book “Hackers and Painters”, which made a big impression on me, steered me away from big corpos towards the startup world (for which I’m forever grateful), and also showed me how much better dynamically typed languages (specifically Lisp) were than statically typed ones.

I spent the next few years writing mostly Ruby and some JavaScript for the frontend, and I loved it. I still love Ruby and to this day I use it for all my scripting and server-side code.

However, at some point I also started building Mac and iOS apps, first in ObjC, and then in Swift. ObjC just felt like so much unnecessary boilerplate, and it really was. Then Swift came and simplified everything, but it exchanged the boilerplate for a very strict type system, much stricter than anything I’ve seen before. It was annoying to have to explain the compiler which property can be nil and when and what to do with it, or what to do if this JSON array does not contain what I think it does.

But after using Swift for a few years, I really appreciate the feeling of safety it gives you. You have to put in more work up front, but once you do, and once it compiles, you can be sure that whole categories of possible errors have already been eliminated before you even run the app. You have to do fewer build – run – find an error – fix the error cycles while building new features, and it’s also great while refactoring. And most importantly, it makes it harder to break one part of the code while changing another – we don’t always test every part and every single path in the app after every change, so such accidentally introduced errors can make their way to production and to users before they’re discovered.

Long story short, I miss this feeling a bit when working with Ruby and JavaScript now. It would be nice to have someone or something look over my code as I’m working on it, and not only the parts that are currently executed.

Learning TypeScript

TypeScript is not a difficult language, it’s not even a completely new language – it’s like JavaScript with some extra features and a compiler. So if you know JavaScript, you just need to learn the syntax for adding types, and the type declarations is the only thing you need to change in your code.

The official TypeScript site has a great docs section, and you can learn everything you need there. Start with the TypeScript for JS programmers intro and then go through the whole handbook and possibly the reference part if you want more, and that’s it.

Setting up the editor

A normal person would just download VS Code… however, that’s not me. I just refuse to run any IDE or editor without a fully native UI look & feel, so that leaves me with very little choice for those moments when I’m not using Xcode. For Ruby and JavaScript, I use TextMate, which I’ve been using non stop since 2008 (now the version 2 for the last few years).

There is a TextMate bundle for TypeScript, however, it only provides code highlighting and formatting. To simplify running the compiler while I’m in the editor, I manually added two actions using the bundle editor so that I don’t need to switch to the terminal to run npx tsc every time:

1) Compile to first error (shows output in a tooltip):

#!/usr/bin/env ruby18
require ENV['TM_SUPPORT_PATH'] + '/lib/textmate'

tsc = File.expand_path(File.join(ENV['TM_PROJECT_DIRECTORY'], 'node_modules', '.bin', 'tsc'))

ENV['PATH'] += ':/usr/local/bin'

result = `#{tsc} --noEmit`
first_line = result.each_line.first

if first_line.to_s.strip.length > 0
  puts first_line

  if first_line =~ /\((\d+)\,(\d+)\)\:/
    TextMate.go_to :line => $1.to_i
  end
else
  puts "Build OK"
end

2) Compile file (shows output in a special new window):

#!/usr/bin/env ruby18
require ENV['TM_SUPPORT_PATH'] + '/lib/textmate'
require ENV["TM_SUPPORT_PATH"] + "/lib/tm/executor"

tsc = File.expand_path(File.join(ENV['TM_PROJECT_DIRECTORY'], 'node_modules', '.bin', 'tsc'))

ENV['PATH'] += ':/usr/local/bin'

TextMate::Executor.run(tsc, '--noEmit')

This is a bit hacky, but it works for me. It only supports a scenario with one TypeScript file for now – there’s apparently no way to make tsc both use the tsconfig.json config to configure compiler options, but also specify a specific filename on the command line. And I’d love to have real autocompletion too, but you can’t have everything…

(If you know a good programmer’s editor with a native Mac UI, please let me know!)

Setting up the compiler & build

Once you download the TypeScript compiler node module, you can run npx tsc --init to create a tsconfig.json file at the root of your project. In this file you can specify where to look for .ts files, how modern JavaScript it should output (I chose es2018 since I don’t need to support any old browsers), and turn specific checks on and off. I’ve experimented a lot with the compiler options, and eventually I’ve left everything on except strict, strictNullChecks and strictPropertyInitialization (which requires strictNullChecks). The null checks add a ton of additional errors everywhere, and would require me to unwrap everything with ! like in Swift on every step (e.g. every call to querySelector, querySelectorAll, parentNode and such things), and I decided it’s just not worth the effort. It could possibly make sense if I was using some framework that was abstracting all interaction with DOM like React.

If you use any external libraries, like Chart.js in my case, you will also want to download their .d.ts definition files before you start working on your code – otherwise the compiler will keep telling you “I have no idea what this chart thing is and whether it has such property”.

As for running the build, npx tsc does everything once you configure it in tsconfig.json – the problem is how to make it run when it needs to, and what to do with what it outputs…

Again, a normal person would just set it up in some Gulp, Grunt, Webpack or whatever it is that people use in JavaScript land this month 😛 In my case however, I have a Ruby project built on top of Sinatra that has no JavaScript build system (since I have very little JavaScript in general outside of the Corona Charts page) and even no proper asset pipeline configured. So I could either set up some new build system just for this, or write some kind of hack. You can guess what I picked.

Since I only have one TypeScript file for now, and it’s only used on one page, I realized I can just manually check the timestamp in the controller action and rebuild if the .ts file is newer:

get '/corona/' do
  # ...
  unless production?
    original = 'public/javascripts/corona.ts'
    compiled = 'public/javascripts/corona.js'

    if File.mtime(original) > File.mtime(compiled)
      puts "Compiling #{original}..."
      `npx tsc`
      puts "Done"
    end
  end

  erb :corona, layout: false
end

That’s for development – for production, I simply run it as one of the deployment phases in my Capistrano script:

after 'deploy:update_code', 'deploy:install_node_packages', 'deploy:compile_typescript'

task :install_node_packages do
  run "cd #{release_path}; npm install"
end

task :compile_typescript do
  run "cd #{release_path}; ./node_modules/.bin/tsc"
end

Updating the code

It took me a good day or two to update all the code to silence all TypeScript errors. The good thing is that even though you get errors, the TypeScript compiler still outputs proper JavaScript that looks like what you had before (as long as it makes any sense at all), it just can’t promise it will work, so you could possibly deploy it as is, treat the errors like warnings in Xcode and get rid of them gradually. But ideally you want to not have any errors at all, since just like with warnings in Xcode, once you have too many of them, you stop noticing the important ones.

The changes I had to make can be grouped in a few categories:

deleting some unused code, variables and parameters (that I haven’t realized were unused)
creating type definitions for all informal data structures used in the code – e.g. declaring that a DataSeries is a hash mapping a string to an array of exactly 4 numbers, what the structure of the downloaded JSON is, or that the valueMode parameter can only be “confirmed”, “deaths” or “active” (it’s so cool that you can have such specific types!):
```
type ChartMode = "total" | "daily";
type ValueMode = "confirmed" | "deaths" | "active";
type ValueIndex = 0 | 1 | 2 | 3;

type RankingItem = [number, Place];
type DataPoint = [number, number, number, number]
type DataSeries = Record<string, DataPoint>;

interface DataItem {
  place: Place;
  data: DataSeries;
  ...
}
```

defining all global variables as explicitly typed properties on Window:

interface Window {
  colorSet: string[];
  coronaData: DataItem[];
  chart: Chart;
  ...
}

declaring all custom properties I set on built-in objects like DOM elements, or method extensions added to built-in types like Object or Array:
```
interface HTMLAnchorElement {
  country: string;
  region: string;
  place: Place;
}
```

declaring class variables and their types:

class Place {
  country?: string;
  region?: string;
  title?: string;
  ...
}

declaring the type of all function parameters (you don’t usually need to specify return types, those are inferred):
```
function datasetsForSingleCountry(place: Place, dates: string[], json: DataSeries) {
  ...
}
```

casting some DOM objects to a more specific type like HTMLInputElement when I want to use the value:

let checkbox = document.getElementById('show_trend') as HTMLInputElement;
window.showTrend = checkbox.checked;

providing a type for local vars initialized with [] or {}:

let ranking: RankingItem[] = [];
let autocompleteList: string[] = [];

It’s a lot of changes in total when you look at the diff, but most of it is things I needed to write once somewhere at the top. When I write a new function now, I usually just need to add types to the parameters in the function header.

Was it worth it?

So far – I’d say, absolutely. Like I wrote above, when adding new functions I usually just need to declare parameter types, unless I start adding completely new types, but most of the time I operate on the ones I already have. Like in most modern languages, you usually don’t need to define a type for a local variable like let thing = getThing(), because the compiler knows that it’s of type Thing. And if you return it, it knows this function always returns a Thing when it’s called elsewhere.

So it doesn’t add much overhead for new code, but it does give me this nice feeling that someone is checking what I write. I’ve done one refactoring since then, modifying the structure of the JSON file to make it smaller, since it naturally got way larger over the last few months (1.2 MB uncompressed, although I managed to compress it to 190 KB now using Brotli compression set at max level).

I changed the declaration of window.coronaData at the top to be an object instead of an array, and the DataSeries to be an array instead of a hash. And the compiler immediately showed me every single place in the code that was using these objects and had to be updated to the new format. I didn’t have to use the editor search to hunt down every single place of use, and worry that I might have missed one that I’ll only discover after some thorough testing (or a complaint from a user). Once it compiled, it was basically done and it worked from the first run.

So am I going to use TypeScript now for every 1-page-long piece of JS that adds some animations to a blog? Of course not. But does it make sense to use it in a webapp with dozens of features that builds and manages the whole UI in JavaScript? I think it does.

WatchKit Adventure #4: Tables and Navigation

2020-09-10T11:36:23Z

< Previously on WatchKit Adventure…

Two weeks ago I posted the first part of a tutorial about how to build an Apple Watch app UI using WatchKit, using a WKInterfaceController and a storyboard. We’ve built the main screen for the SmogWatch app, showing a big colored circle with the PM10 value inside and a chart showing data from the last few hours.

Here’s the second part: today we’re going to add a second screen that lets the user choose which station they want to load the data from. So far I’ve used a hardcoded ID of the station that’s closest to me, but there are 8 stations within Krakow and the system includes a total of 20 in the region, so it would be nice to be able to choose a different one.

(I initially wanted to also include a selection of the measured pollutant – from things like sulphur oxides, nitrogen oxides, benzene etc. – and I’ve actually mostly implemented it, but that turned out to be way more complex than I thought, so I dropped this idea.)

The starting point of the code (where the previous part ends) is available here.

Preparing the data

Since the list of stations doesn’t change often, we can hardcode a list of stations with their names, locations and IDs in a plist file that we’ll bundle inside the app. The list is generated using a Ruby script, in case it needs to be updated later – you can just download the plist and add it to the Xcode project.

At runtime, the list will be available in the DataStore:

struct Station: Codable {
    let channelId: Int
    let name: String
    let lat: Double
    let lng: Double
}

class DataStore {
    // ...

    lazy private(set) var stations: [Station] = loadStations()

    private func loadStations() -> [Station] {
        let stationsFile = Bundle.main.url(forResource: "Stations", withExtension: "plist")!
        let data = try! Data(contentsOf: stationsFile)

        return try! PropertyListDecoder().decode([Station].self, from: data)
    }
}

Handling secondary screens

When we want to add an additional screen to the app that shows some secondary information or less commonly used feature like this, there are generally three ways we can handle it:

we can add an explicit button somewhere on the screen that opens it (usually in the bottom part)
we can put it on another page in the page-based layout (e.g. like sharing and awards in the Activity app)
or we can put it as an action in the menu accessed through Force Touch

The third option (Force Touch menus) is going away now. In the watchOS 7 betas, Apple has removed all Force Touch interactions from the OS and their own apps, the APIs for using it in third party apps (addMenuItem in WKInterfaceController) are deprecated, and it’s highly likely that the upcoming Series 6 watch will not include it as a hardware feature.

Hiding some actions in a menu had the advantage that it didn’t clutter the main view, but it also made those actions less discoverable and harder to use for those who need them. I personally always had a problem with the Force Touch menus in that I rarely remembered that they exist, and I often not realized that an app had some extra features if it put them there… So I guess it’s for the better, although it will probably take some time to adjust.

Using a page view controller and putting settings on the second page could work, but it doesn’t feel to me like this feature is important enough to get its whole new section in the main app navigation. I don’t think this is something people will do often – normally they should just select a station close to their home and never change it again. There will probably be some users who might want to often switch between stations to compare the values, but that would rather be a minority. (If you do want to use a page view controller, adding it is kind of unintuitive: there is no “Page View Controller” in the library, but instead you drag a segue from the first screen to the second and choose “Next page”.)

So I’ve decided that in this case it’s not a problem to have an additional button at the bottom of the main screen, which opens the list in a separate view.

The second choice is how to show the screen: do we show it as a modal, or push it onto the navigation stack (the latter only possible if we aren’t using a page-based layout)? Again, both could work and it’s mostly a matter of preference. But I think in this case a pushed view integrates better with the rest of the app.

Opening the list view

So let’s look at the storyboard again. We’d like to have a button below the chart that looks like a single table cell, which says “Choose Station” and shows the current station below, and opens a selection dialog when pressed.

In WatchKit, buttons work in an interesting way: a button can show a text or an image as its title, but it can also include… a group, which itself can contain any structure you want, however complex. You could even wrap the whole screen in one group which acts as a button if you want (though I’m not sure what happens if you put a button into a group in a button – it might be like when you type Google into Google…). By the way, SwiftUI, which started its life on watchOS, kind of took over this idea – the Button takes a closure that returns its label and you can also put almost anything there.

So let’s add a button at the bottom of the view here, and change its Content type to Group. The group is horizontal by default, so change its Layout to Vertical. Next, drag two labels inside: a top label “Choose Station”, with a Body font, and a bottom label that shows the name of a station, with a Footnote font and Light Gray color. Like on iOS, you can also configure labels so that they’re able to shrink if the text is too long – lower the Min Scale slightly to 0.9, since the station names are kind of long.

Notice that while a button normally has a dark gray background by default when showing a text, it lost the background when we switched it into the group mode. I’d like it to look like the standard buttons used e.g. in the Settings app’s various dialogs, but I don’t think there is any way to restore this default shape and color other than trying to manually recreate it. (Technically, we could probably implement it as a one-row table instead… but that would be too much extra work.)

So here’s how we’ll do it: add another plain button to the view. Select the new group, open the select field for the Color property (not Background – that’s used when you have an image background) and choose “Custom”. Now, in the system color picker use the “eyedropper” tool at the bottom to read the color value from the standard button:

Now you can delete the plain button. Let’s also give the group button custom insets to have some padding around the text: 8 on the top, bottom and right, and 10 on the left. And connect the lower label to an outlet in the InterfaceController, since we’re going to need it later:

@IBOutlet var stationNameLabel: WKInterfaceLabel!

Pushing the list view

Now, we’re going to add a second screen to our app. Drag a new interface controller from the library and put it on the storyboard on the right side of the main screen. Then, drag a segue from the button to the new screen – you’ll probably have to use the element sidebar on the left, since if you drag from the button’s rendering in the scene, it selects the group and not its parent button. Select the “Push” segue type (for a modal, you’d do it the same way, but with a “Modal” type segue instead).

Alternatively, we could leave the new screen disconnected, assign it an identifier, and then open the screen manually in code using the pushController(withName:context:) method, or presentController(withName:context:) in case of a modal, from the IBAction triggered from the button. But this sounds like more work, and I generally like to use segues whenever possible, since the storyboard then shows a clearer picture of the whole flow of the app.

The pushed view shows a “<” back button at the top, and you can put a title there. However, these titles work differently than on iOS: on iOS, you usually have a “< Back” button on the left, and a title in the center. On the Watch, there isn’t enough space for that – so the title shown after the “<” sign is supposed to be the name of the current view, not the view that you can get back to.

In this case, let’s make it say simply “Station”, since “Choose Station” is a bit too long (you need to leave space for the clock on the right). You can type it into the Title field, or just double-click the top area where the title should be (though it won’t be displayed on the storyboard).

Designing table cells

To display a list of things from which you can select one, the obvious choice is a table view. On watchOS it works somewhat similarly to iOS, with some exceptions – there are no sections, there’s only one single section of cells (although you could simulate sections by making different cells that act as section headers). But like on iOS, you use custom classes to handle the cells – like UITableViewCell, here they’re called “Row Controllers”; cells also have identifiers, and you can use different kinds of cells in one table.

To start, drag a table from the library into the second view. You automatically get one standard row type created for you, but you can add more.

Add a label to the table row’s group, use a standard Body font, but set Min Scale to 0.8 to accomodate longer names. By default the label will put itself in the top-left corner, so set its Vertical Alignment to center.

We need one more thing though: it would be nice to show a checkmark symbol on the right when you select a cell – just like in the Settings app:

Unfortunately, there doesn’t seem to be any equivalent of UITableViewCell.AccessoryType here – if you want to have a checkmark, you need to add it manually as a normal label.

So, add another label to the same row group, set its title to the unicode symbol “✓” (which looks very similar to the checkmark in the settings), and “borrow” the green color from the system checkmark in the Settings using the same eyedropper method as before. Set its Vertical Alignment to center too.

We have one problem though: the first label takes all available space, and the checkmark is pushed to the edge:

Sadly, there are no “compression priorities” here like in AutoLayout, so there’s no way to tell WatchKit to give the checkmark all the space it needs and then leave the rest to the title. What we can do instead is assign the checkmark a Fixed width which is then enforced – 15 seems about right; it’s not an elegant solution, but it works. Set also its internal Alignment (the text alignment, in the Label section, not the position alignment) to right so that the symbol stays at the right edge, even if we gave it too much space.

Handling the channel ID

Let’s look at our data & networking code for a moment. When the user picks a station, we’re going to store the channel ID in the DataStore. We also need to make sure that when the channel ID is changed, the old data is reset, because it was loaded from another station so it’s no longer relevant:

private let selectedChannelIdKey = "SelectedChannelId"

class DataStore {
    // ...

    var selectedChannelId: Int? {
        get {
            return defaults.object(forKey: selectedChannelIdKey) as? Int
        }
        set {
            if newValue != selectedChannelId {
                defaults.set(newValue, forKey: selectedChannelIdKey)
                invalidateData()
            }
        }
    }

    func invalidateData() {
        defaults.removeObject(forKey: savedPointsKey)
        defaults.removeObject(forKey: lastUpdateDateKey)
    }
}

We also need to actually use the new channel ID when making the request for the data. This is a bit too long to paste here, so here’s the relevant change in the KrakowPiosDataLoader class. Instead of the hardcoded ID of one specific station that I’ve used before, we’ll now be passing the ID of the selected station to the query.

The table controller

We’ll handle the table view in code in a new interface controller, which we’ll call StationListController. Create such class in Xcode (inherit from WKInterfaceController – there’s no special “table view controller”) and assign it to the new scene on the storyboard. Also add this outlet and connect it:

@IBOutlet weak var table: WKInterfaceTable!

We’ll also need a row controller class (it’s required, and there is no default base class with standard outlets like UITableViewCell that we could use anyway). Use NSObject as the base class and call it StationListRow – like table view cells, it will be very simple:

class StationListRow: NSObject {
    @IBOutlet weak var titleLabel: WKInterfaceLabel!
    @IBOutlet weak var checkmark: WKInterfaceLabel!

    func showStation(_ station: Station) {
        titleLabel.setText(station.name)
        checkmark.setHidden(true)
    }

    func setCheckmarkVisible(_ visible: Bool) {
        checkmark.setHidden(!visible)
    }
}

Assign the class name to the row on the storyboard and connect the outlets. A row also needs an identifier – call it BasicListRow (yes, there will be another :).

Now, in the StationListController, the interesting stuff happens in the awake(withContext:) method. What is a context, you might ask? It’s a cool idea that Apple kind of expanded on in the iOS 13 SDK, in the form of UIStoryboard.instantiateViewController, which lets you have a custom initializer in a UIViewController in which you can receive any required data, while still using storyboards and segues to navigate to the view controller.

In WatchKit, instead of custom initializers you have a single context object – but this context could be anything you want, including any complex structure and non-ObjC types. You can use this object to pass all required data from the parent/presenting controller to the presented controller, and extract it in awake(withContext:).

We’ll use the context to pass the new view controller the list of all stations and the id of the currently selected one (if any). And it turns out that it’s also possible to pass blocks this way, so we can include a simple block that will act as a selection callback – this way we can avoid building a “delegate protocol” to pass the response back.

Let’s prepare a simple struct for the context data:

struct StationListContext {
    let items: [Station]
    let selectedId: Int?
    let onSelect: ((Station) -> ())
}

The selection controller will get this data from the main interface controller, which assigns it in the contextForSegue(withIdentifier:) method:

override func contextForSegue(withIdentifier segueIdentifier: String) -> Any? {
    if segueIdentifier == "ChooseStation" {
        return StationListContext(
            items: dataStore.stations,
            selectedId: dataStore.selectedChannelId,
            onSelect: { _ in }
        )
    }

    return nil
}

For this to work, you need to select the segue on the storyboard and assign it the identifier ChooseStation.

In the StationListController, we’ll receive the data from the context in awake(withContext:):

class StationListController: WKInterfaceController {
    var selectedRowIndex: Int? = nil
    var items: [Station] = []
    var selectionHandler: ((Station) -> ())?

    override func awake(withContext context: Any?) {
        let context = context as! StationListContext

        items = context.items
        selectionHandler = context.onSelect
        ...

Notice that we don’t need to call super() in awake(withContext:) – the same is true for willActivate, didAppear etc. If you look at the documentation of those, it always says “The super implementation of this method does nothing” there.

To initialize the table, we call the setNumberOfRows method to set the row count, and then we iterate over the rows to initialize their contents (there is no “cell reuse” and initializing cells during scrolling, it’s all done up front). If you wanted to have multiple types of rows in one table, then you need to call setRowTypes instead and pass it an array with as many repeated identifiers as you want to have rows.

table.setNumberOfRows(items.count, withRowType: "BasicListRow")

for i in 0..<items.count {
    let row = table.rowController(at: i) as! StationListRow
    row.showStation(items[i])
}

We’ll also preselect the row of the currently selected station, if we can find it (we pass the channel ID from the parent controller, but here we’ll store the index of the row, so that we can later deselect it easily).

if context.selectedId != nil {
    if let index = items.firstIndex(where: { $0.channelId == context.selectedId }) {
        let row = table.rowController(at: index) as! StationListRow
        row.setCheckmarkVisible(true)
        selectedRowIndex = index
    }
}

To handle row selection, we’ll implement table(_:didSelectRowAt:) (you don’t need to assign any delegate/data source properties to the table or add any protocols, it works automatically):

override func table(_ table: WKInterfaceTable, didSelectRowAt rowIndex: Int) {
    if let previous = selectedRowIndex, previous != rowIndex {
        listRowController(at: previous).setCheckmarkVisible(false)
    }

    listRowController(at: rowIndex).setCheckmarkVisible(true)
    selectedRowIndex = rowIndex

    selectionHandler?(items[rowIndex])
}

func listRowController(at index: Int) -> StationListRow {
    return table.rowController(at: index) as! StationListRow
}

As you can see: we manually hide the checkmark in the previously selected row whose index we’ve saved, we show the checkmark on the current row, we store the row index, and we pass the Station back through the callback block.

Finally, we need to handle the selection in the parent controller when the callback is called. Specifically, we’ll need to:

save the channel ID of the new station in the DataStore, so that further requests to the web service will load data from that station
update the displayed station ID in the button at the bottom
show in the UI that we have no data from that station yet
request to reload the data immediately

Here’s how we do it:

func setSelectedStation(_ station: Station) {
    dataStore.selectedChannelId = station.channelId
    stationNameLabel.setText(station.name)

    updateDisplayedData()
    gradeLabel.setText("Loading")

    KrakowPiosDataLoader().fetchData { success in
        self.updateDisplayedData()
    }
}

And remember to call this in the callback block from StationListContext:

return StationListContext(
    items: dataStore.stations,
    selectedId: dataStore.selectedChannelId,
    onSelect: { station in
        self.setSelectedStation(station)
    }
)

The end result should look like this 🙂

And one more thing: we need to also remember to initialize the selected station label when the view is first loaded. We’ll make it say “not selected” if nothing was selected yet:

// call in awake(withContext:)

func updateStationInfo() {
    guard let channelId = dataStore.selectedChannelId else { return }

    if let station = dataStore.stations.first(where: { $0.channelId == channelId }) {
        stationNameLabel.setText(station.name)
    } else {
        stationNameLabel.setText("not selected")
    }
}

User location

There’s still something we could do to improve the user experience: why ask the user which station they want to load the data from, when in the majority of cases they’ll only be interested in the one that’s closest to them? And why make them scroll through the whole list, if some of the stations are 100 km away from them?

We can solve this if we ask the user for location access – after all, almost every Apple Watch has built-in GPS, and those that don’t are connected to an iPhone that has one.

On watchOS we ask for location exactly like on iOS – so we can follow the instructions I wrote here a few years ago:

add an NSLocationWhenInUseUsageDescription key to the Info.plist (e.g. “SmogWatch uses location data to pick a station that’s closest to you.”)
add a reference to a CLLocationManager in the InterfaceController and make it its delegate
ask for location access when the main screen opens:

var userLocation: CLLocation?

override func willActivate() {
    askForLocationIfNeeded()
}

func askForLocationIfNeeded() {
    guard userLocation == nil, CLLocationManager.locationServicesEnabled() else { return }

    switch CLLocationManager.authorizationStatus() {
    case .notDetermined:
        locationManager.requestWhenInUseAuthorization()
    case .authorizedAlways, .authorizedWhenInUse:
        locationManager.requestLocation()
    default:
        break
    }
}

We’re going to store the location in userLocation when we find it, so that we can use it in the station selection screen.

⚠️ One warning here – I initially added askForLocationIfNeeded() to didAppear so that we only ask for location once the UI appears, and I was expecting didAppear to always be called following willActivate – but it doesn’t seem to work this way. From my testing right now, it seems that didAppear is only called when the app is launched and when you return to the interface controller from the pushed view, but not when the app is closed and reopened. If you add something to one of these two methods, make sure you test exactly in which cases they get called.

Next, if the user grants us location access after the launch, we ask for location data then:

func locationManager(
  _ manager: CLLocationManager,
  didChangeAuthorization status: CLAuthorizationStatus)
{
    switch CLLocationManager.authorizationStatus() {
    case .authorizedAlways, .authorizedWhenInUse:
        locationManager.requestLocation()
    default:
        break
    }
}

We only ask for a single location, we don’t need to track it continuously. And we can also set desiredAccuracy to kCLLocationAccuracyHundredMeters when setting up the CLLocationManager – we won’t need more precision than that, and we should get the location much faster this way.

When we get the location, we save it in the property userLocation mentioned earlier (we also need to handle an error case – you actually get an exception immediately if you don’t). Also, most importantly, if there is no station selected yet, but we have the user location, we can preselect the closest one automatically – that way, the user will see some data almost immediately, without having to configure the app first, and it’s very likely it will be exactly the data that they want 👍

func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
    guard let currentLocation = locations.last else { return }

    userLocation = currentLocation

    if dataStore.selectedChannelId == nil {
        let closestStation = stationsSortedByDistance(from: currentLocation).first!
        setSelectedStation(closestStation)
    }
}

func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
    NSLog("CLLocationManager error: %@", "\(error)")
}

func stationsSortedByDistance(from userLocation: CLLocation) -> [Station] {
    return dataStore.stations.sorted { (s1, s2) -> Bool in
        let d1 = CLLocation(latitude: s1.lat, longitude: s1.lng).distance(from: userLocation)
        let d2 = CLLocation(latitude: s2.lat, longitude: s2.lng).distance(from: userLocation)

        return d1 < d2
    }
}

We can then pass the saved location to the stations list, where we’ll use it to show the distance to each station, and we can also pass it a list of locations sorted by location:

override func contextForSegue(withIdentifier segueIdentifier: String) -> Any? {
    if segueIdentifier == "ChooseStation" {
        let stations: [Station]

        if let currentLocation = userLocation {
            stations = stationsSortedByDistance(from: currentLocation)
        } else {
            stations = dataStore.stations
        }

        return StationListContext(
            items: stations,
            selectedId: dataStore.selectedChannelId,
            userLocation: userLocation,
            onSelect: { station in
                self.setSelectedStation(station)
            }
        )
    }

    return nil
}

Add a userLocation: CLLocation? property to the SelectionListContext, from which we’ll read it in the controller’s initializer.

Showing distances in the list

Let’s look back on our storyboard again. We want to have a second label below the station title that shows the distance to the station – that is, if we know user’s location, otherwise we show the old version.

It’s possible that we could somehow make this work with a single cell type, but I figured that a much easier way would be to have two different cells managed by the same class. So make a duplicate of our BasicListRow, give it an identifier ListRowWithDistance and keep the same class name.

In order to have 3 elements in the cell positioned correctly, we’re going to need two groups: one horizontal, dividing the checkmark on the right from the two labels on the left, and then an inner vertical group that arranges the two labels. So change the cell this way:

Wrap the left label in a Vertical group.
Add a second label inside that inner group. Make sure it’s below the first one (you can set their vertical alignment, or you can just make sure they’re in the right order in the view tree).
The table row’s main group has a fixed “Default” height configured when created – but with two labels, this default height is too little. So change the height setting to Size to fit.
Give the lower label a Light Gray color and a Footnote font. Make it say e.g. “3.2 km”, and assign it to an outlet in the StationListRow:

@IBOutlet weak var distanceLabel: WKInterfaceLabel!

Give the vertical group Insets of 3 at the top and bottom, and change its Width setting to “Size to fit content” – otherwise it will take whole cell width by default and push the checkmark out.
Customize the outer (horizontal) group’s Spacing to 0; we can allow less space between the checkmark and the edge of the title label now, because the checkmark will be positioned in the vertical center, so slightly lower than the label.
The checkmark’s properties should stay as before.

We can then add another helper method to StationListRow to set the distance. We’re going to use MeasurementFormatter here in order to automatically display kilometers or miles, and we’ll also make sure to only print 1 decimal digit, since we asked for a slightly less precise location (the default is something like “2.456 km”):

let measurementFormatter: MeasurementFormatter = {
    let numberFormatter = NumberFormatter()
    numberFormatter.maximumFractionDigits = 1

    let measurementFormatter = MeasurementFormatter()
    measurementFormatter.numberFormatter = numberFormatter
    return measurementFormatter
}()

func setDistance(_ distance: Double) {
    let text = measurementFormatter.string(
        from: Measurement(value: distance, unit: UnitLength.meters)
    )
    distanceLabel.setText(text)
}

And now in the awake(withContext:) method in StationListController we can choose between the two types of cells depending on whether we have the location or not, and if we do, calculate the distance to each station and show it in the lower label:

let rowType = (context.userLocation == nil) ? "BasicListRow" : "ListRowWithDistance"
table.setNumberOfRows(items.count, withRowType: rowType)

for i in 0..<items.count {
    let row = listRowController(at: i)
    row.showStation(items[i])

    if let location = context.userLocation {
        let itemLocation = CLLocation(latitude: items[i].lat, longitude: items[i].lng)
        row.setDistance(location.distance(from: itemLocation))
    }
}

You should now see something like this:

We’ve reached the end of this tutorial. For the next episode, I will try to rewrite the whole UI again from scratch in SwiftUI and compare how much effort it requires to build the same kind of UI in the new framework :)

The final version of the code after a completed tutorial is available on a branch here, and the slightly different real version on the master would be more or less at this commit.

WatchKit Adventure #3: Building the App UI

2020-08-26T13:25:41Z

< Previously on WatchKit Adventure…

This is the third part of my series about building a WatchKit app that shows current air pollution level on the watch face (it started here). In this episode, we’re going to build the app’s main UI. I will be building on top of some data handling & networking code written in the previous episode about complications, so if you haven’t seen that one, you might want to at least skim through it to get some idea about what this is about. Browse through the WatchKit category to see the whole list.

We’re venturing into a somewhat uncharted territory now… The WWDC talks about WatchKit are an amazing source of information and they’re great to get started (I definitely recommend watching them, especially the earlier ones, from 2015 & 2016), but once you actually start building things and run into a problem, there’s surprisingly little help available. Even StackOverflow isn’t of much use. There aren’t many books out there either that are up to date – I got one from raywenderlich.com, but it doesn’t really answer the hard questions, and it wasn’t updated since watchOS 4; Paul Hudson has another, and that’s pretty much it.

I’ve tried to figure out some things myself, but some questions are left unanswered. If you know how to solve anything better than I did, please let me know in the comments.

The two frameworks

watchOS SDK launched first in 2015 with a new UI framework called WatchKit. It was a very different framework than what we knew from macOS and iOS, a framework specifically designed for the Watch and all its inherent and temporary limitations – and also limited in what it could do and what you could do with it. It got people excited, but also very quickly frustrated, once they’ve run into these limitations. It didn’t help that Apple’s own apps were very obviously doing some things in the UI that weren’t possible to external developers, clearly using some internal APIs Apple needed to build more powerful apps, but which they didn’t want to share with us.

So of course the hearts of Watch developers started beating faster when we heard the brief mention “… and a new native UI framework” during the 2019 keynote – said almost as if we were supposed to miss it. Of course about two hours later we’ve learned that this new framework was SwiftUI, built not only for watchOS (although that’s how the whole thing started, apparently!), but for all Apple platforms. A thing that would completely change Apple platform development.

However, as people who have rushed to try out this new framework quickly discovered, SwiftUI as released in the iOS 13 SDK was “a pretty solid version 0.7” – a massive step forward of course, especially on watchOS, but still more of a beta. The “version 2.0” released this June seems like a very decent update, but it’s not stable yet and at this point it’s still unclear if it solves most of the issues that people had with the first release.

So here we are, with two frameworks, an old one that’s very limited, and a new one that’s still kind of unfinished. Which one should I use to build an app right now? Which one should I learn?

Well… ¿Por qué no los dos? 😎

Seriously speaking, my intuition tells me that if you’re starting to build a new Watch app right now, it probably makes more sense to go with SwiftUI. Since the platform was much more limited previously, the gain from using SwiftUI compared to the old way is probably much bigger than on iOS, and while on iOS you’re likely to often run into things you can’t do with SwiftUI that you could with UIKit, it’s probably more of the opposite on watchOS.

But since I haven’t really built anything with the plain old WatchKit before, I still want to have this experience, if only just to have a broader knowledge of the platform. So let’s build the app in the classic WatchKit now, and then we’ll do the same thing again in SwiftUI and compare.

Design

Before you start writing code, it’s good to spend some time first designing and thinking about what you’re actually planning to build, how it should look and work and why. Perhaps even away from the computer, with a pen and a piece of paper. This is true for any kind of app, but especially for Apple Watch apps. Watch apps are designed for extremely quick interactions, on the order of a few seconds – the user should be able to open your app, find the information they need and leave, without spending too long trying to understand your app’s layout and navigation. So it’s worth spending some time to make sure that your app really works this way.

I started by listing the things the user might want to see and do in this app:

see the current pollution level
view a history chart with earlier values
select the monitoring station
select the specific parameter

Next, I looked through the apps I have installed on my Watch (mostly first-party ones) to get some idea and inspiration about what layout and navigation they use and find something somewhat similar to what I want to build. In the end, I think the Activity app looked closest to what I imagined: a big circle with the 3 colored arcs, showing you the most important information at a glance, and then by scrolling down you can access some additional information like per-hour charts, steps count and so on.

I got a piece of paper and did some planning and drawing, and ended up with something like this :)

The option 2 is what I went with – I figured that having a big colored circle with the PM value on the first screen would fit the idea of making the app “glanceable” by providing the most important information first, same as in the Activity app.

I managed to build the complete app in about 4-5 days. I want to describe the whole process here, but this got a bit long so I broke it into two parts: the main screen and the list that lets you select the measuring station.

The status screen

Like from the beginning, I’m doing anything in the open, in a repo on GitHub – licensed under WTFPL, so you’re free to reuse any piece of code for anything you want. If you want to follow with me in Xcode, here is the commit from which we start, and here’s the complete version (after this first part of the tutorial).

Open our Interface.storyboard. Let’s remove the notification scenes added by the template for now to clear up some space.

Let’s start with something I completely missed until the moment I had the app finished and this blog post ready to ship – you can learn from my mistakes 😅 Here it is: a Watch app needs to have a title label!

Look at some of the system apps – they all show their name in the top bar next to the clock:

This is not CFBundleDisplayName or something else that happens automatically – you need to set it as the title of your main interface controller. Set it either in the Attributes inspector (the “Title” field), or by double-clicking the top bar area on the storyboard (the title won’t be displayed there, only when the app runs).

If you have some kind of brand color that you use in your icon and logo that the users associate with your app or service, you should also set it on the storyboard as the “Global Tint” (in the File inspector – first tab), then it will be used to color that title label. I’m going to keep the default gray tint color.

The value circle

Now, we’re going to work on the thing that the user will see when they first open the app – the big circle showing the measured value.

Drag the first item from the Library to the view – a label. Make it say “PM10” and use the Title 3 font style. In general, you should try to use one of the 10 standard semantic font styles if possible, to take advantage of Dynamic Type and have all fonts adapt to user’s chosen text size.

Notice that you can’t really position the label wherever you want in the view by dragging – the way you position things in WatchKit is by using the “Alignment” and “Size” properties in the Inspector, and by wrapping items in Groups which act like stack views on macOS/iOS. Position this label to Center horizontally. (In this case, you could achieve the same effect by setting its size to 100% of the container width and then setting its internal text alignment – the one in the “Label” section – to centered.)

Add another label (or you can make a copy of the first one), make it say “Good”, use the same Title 3 font and also position it to Center horizontally.

Next, we need the main circle. We could use an image, but we can also use a group and set its background and corner radius so that the four corners form a circle.

Drag a group into the view between the two labels, and a label inside it. Set the group’s Color to e.g. light gray or green, and the label’s text to some number like “32”, its font to System 42 (we won’t be using Dynamic Type for this one since it should be large enough for everyone), its Text Color to black with 80% alpha, and position it to Center/Center inside the group.

Now, we run into two problems:

first, I’d like to position the top & bottom labels and the circle so that they always take whole height of the screen: the two labels take as much as they need, and the circle takes whatever is left
second, I’d like to have the circle always keep a 1:1 aspect ratio, so that its width is equal to whatever height it’s allowed to have

Unfortunately, this doesn’t seem to be possible in WatchKit. You can position something at the top and bottom, but there isn’t really such width or height setting as “take whatever is left”. There is also no aspect ratio constraint (since there are no constraints in general). You can only size a thing to fit its content (not helpful here, since we want to make the circle big, with plenty of space around the number), size it relatively to the container – but ignoring whatever else is inside it, or use a fixed size.

So I think the best we can do here is to use a fixed size. Make the circle group 100×100 in size and give it a Corner Radius of 48. Also center the group horizontally in the view.

Notice that it would probably be nice to have some more spacing between the labels and the circle. We can add spacing using groups. The top level view is actually a group itself – if you select the Interface Controller, you can set e.g. its background, insets and spacing – but you can only set one consistent spacing per group, and we might want to use different spacings further down.

So instead lets wrap the three elements in a new vertical group – you can do that by selecting them and using the “embed” button in the bottom toolbar:

Now give the group a Spacing of 7. Also, override the default Insets and set Top to 8 in order to add some margin from the title in the title bar – which you don’t see now, but you will once you run the app.

Looks good! Because of the limitations I’ve mentioned it won’t always look perfect depending on the watch and selected text size, but it seems to work well enough in most cases. The difference between the smallest and largest text sizes isn’t as drastic here as on iOS.

Interface controller

Now, let’s write some code to show the right values. We’ll be adding it in our InterfaceController, which is WatchKit’s equivalent of a view controller. First, add these 3 outlets:

@IBOutlet var valueCircle: WKInterfaceGroup!
@IBOutlet var valueLabel: WKInterfaceLabel!
@IBOutlet var gradeLabel: WKInterfaceLabel!

Connect them on the storyboard to the elements we’ve added: the circle, the label inside it, and the bottom label, respectively. We’ll also need a reference to the DataStore that we’ll load values from (see Episode 2).

let dataStore = DataStore()

Now we need to have some logic for how to interpret the raw numbers we get from the web service – how much is good enough, and how much is not? Let’s add an enum SmogLevel which will cover this.

⚠️ Note: the ranges configured below are my personal subjective interpretation of how I feel about the given pollution levels. They are somewhat skewed by the fact that the smog levels in southern Poland during winter are more often above the safety limits than within them (although it got much better in the last year or two, fortunately). In theory, anything above 50 µg/m³ should be considered bad.

enum SmogLevel: Int, CaseIterable {
    case great = 30,
        good = 50,
        poor = 75,
        prettyBad = 100,
        reallyBad = 150,
        horrible = 200,
        extremelyBad = 10000,
        unknown = -1

    static func levelForValue(_ value: Double) -> SmogLevel {
        let levels = SmogLevel.allCases
        return levels.first(where: { Double($0.rawValue) >= value }) ?? .unknown
    }

    var title: String {
        switch self {
        case .great: return "Great"
        case .good: return "Good"
        case .poor: return "Poor"
        case .prettyBad: return "Pretty Bad"
        case .reallyBad: return "Really Bad"
        case .horrible: return "Horrible"
        case .extremelyBad: return "Extremely Bad"
        case .unknown: return "Unknown"
        }
    }
}

We’ll also use different colors for each range – for simplicity, we’ll use the HSB system and use colors of the same saturation and brightness, differing only in the hue.

var color: UIColor {
    let hue: CGFloat

    switch self {
    case .great: hue = 120
    case .good: hue = 80
    case .poor: hue = 55
    case .prettyBad: hue = 35
    case .reallyBad: hue = 10
    case .horrible: hue = 0
    case .extremelyBad: hue = 280
    case .unknown: hue = 0
    }

    if self == .unknown {
        return UIColor.lightGray
    } else {
        return UIColor(hue: hue/360, saturation: 0.95, brightness: 0.9, alpha: 1.0)
    }
}

Finally, let’s add a method that reloads the values in the UI, and call this method from awake(withContext:):

func updateDisplayedData() {
    let smogLevel: SmogLevel

    if let amount = dataStore.currentLevel {
        let displayedValue = Int(amount.rounded())
        valueLabel.setText(String(displayedValue))
        smogLevel = SmogLevel.levelForValue(amount)
    } else {
        valueLabel.setText("?")
        smogLevel = .unknown
    }

    valueCircle.setBackgroundColor(smogLevel.color)
    gradeLabel.setText(smogLevel.title)
}

Looks pretty nice already, doesn’t it? (This is a real live value from a nearby air monitoring station.)

Last update time

We could also add a label showing last update time, so that you can easily see if the value is up to date.

Add another group below the previous one (it’s sometimes hard to position a new thing in the right place, so that it’s added at the root level and not into an exising group – you need to have some patience), make sure that its Layout is Horizontal. Add two labels inside, which will be arranged left to right. Give them a font style of Caption 1 and make them say “Updated:” and e.g. “15:00” (we’ll use a formatter to print time in the right format).

Change the group’s Width to Size to fit content and its Horizontal Alignment to Center. Note, that’s something different than horizontal layout: layout means how the group arranges its child elements, and alignment means how the group positions itself inside the parent, which is the root container here. (For extra confusion, labels also have an additional text alignment property…)

Override also the group’s insets and set the Top and Bottom to 2 to keep some spacing from the “Good” label and from what we’ll add below.

You might notice a WKInterfaceDate item in the library that seems to be a customized label for showing date:

Why not use that one, sounds like a perfect place to use it? I’ve actually tried to do that at first, but I couldn’t find a way to set its date… Turns out, if you read the description carefully, you can see it says that it’s only meant for showing current date 😉 It’s a way to avoid using an NSTimer to keep the date label updated if it’s meant to show the current time which constantly changes – but in our case, we’re showing a past time that will only change when the data is refreshed. So we can just use a plain label and manually format the time once using a DateFormatter – which also gives us more options for customizing the format than the date label would.

In the interface controller, add two more outlets and connect them on the storyboard to the right label and the whole group:

@IBOutlet var updatedAtLabel: WKInterfaceLabel!
@IBOutlet var updatedAtRow: WKInterfaceGroup!

We’ll also need the date formatter. I’ve been thinking what would be the best way to show the time: should I include just the hour, day, or full date? But then I realized: if the data is more than a few hours old, it’s useless anyway! What does it matter if the pollution was high or low a week ago?

So there are really two cases: either the data was updated at most a few hours ago today, or it’s e.g. 2am and it was updated shortly before midnight yesterday. If it’s more than a few hours old, we’re going to treat it as if we had no data at all, because doing otherwise could just be misleading.

So we’re going to use two different time formats: when the data was updated earlier today, we’ll only show the time, and if it was yesterday, we’ll add the short day name for clarity. We’re using the DateFormatter.dateFormat method here which generates an appropriate specific format string that includes the listed fields for your current locale – so depending on your settings the hour might be in the 24- or 12-hour system, 0-padded or not, and so on.

let dateFormatter = DateFormatter()

let shortTimeFormat = DateFormatter.dateFormat(
  fromTemplate: "j:m", options: 0, locale: Locale.current
)
let longTimeFormat = DateFormatter.dateFormat(
  fromTemplate: "E j:m", options: 0, locale: Locale.current
)

We’ll also hide the whole updatedAtRow if we have no data to show. The updated updateDisplayedData() method will look like this:

func updateDisplayedData() {
    var smogLevel: SmogLevel = .unknown
    var valueText = "?"

    if let updatedAt = dataStore.lastMeasurementDate {
        updatedAtRow.setHidden(false)

        dateFormatter.dateFormat = isSameDay(updatedAt) ? shortTimeFormat : longTimeFormat
        updatedAtLabel.setText(dateFormatter.string(from: updatedAt))

        if let amount = dataStore.currentLevel, Date().timeIntervalSince(updatedAt) < 6 * 3600 {
            smogLevel = SmogLevel.levelForValue(amount)
            valueText = String(Int(amount.rounded()))
        }
    } else {
        updatedAtRow.setHidden(true)
    }

    valueCircle.setBackgroundColor(smogLevel.color)
    valueLabel.setText(valueText)
    gradeLabel.setText(smogLevel.title)
}

func isSameDay(_ date: Date) -> Bool {
    let calendar = Calendar.current
    let updatedDay = calendar.component(.day, from: date)
    let currentDay = calendar.component(.day, from: Date())

    return updatedDay == currentDay
}

The app should now look like this:

History chart

Now we’re getting to the exciting part: we’re going to do some drawing!

At this point I took a break from coding to research the options. The main problems: there is no UIView.drawRect: in WatchKit, and there’s no UIScrollView that would let you scroll parts of the screen independently. I initially imagined some kind of chart that can be scrolled horizontally to show more points than fit on the screen. I could possibly simulate the scrolling with some horrible hacks, but I’ve realized that this would probably be both unnecessary and possibly confusing in terms of UX. I usually don’t care about the numbers from yesterday or earlier, and if I do, I can check them on the web – it would be enough to show the last few points, say, 6-8, so that you get the idea of what the trend is and if you should expect the value to rise or fall.

Like I said, there is no drawRect: – however, there is a WKInterfaceImage and it accepts dynamically generated images, and we can generate one with Core Graphics. UIGraphicsImageRenderer is not available, but you can use the older function-based API and capture an image using UIGraphicsGetImageFromCurrentImageContext().

Alternatively, I could use a WKInterfaceSKScene and draw the chart using SpriteKit – it’s a framework made mainly for games, but Apple have said explicitly in their WatchKit talks that it can be used for things like animations inside apps.

That said, I have zero experience with SpriteKit, so I would have to spend some additional time learning it from scratch – and I have a feeling that this would be an overkill for something like this. However, it’s still something to keep in mind if you need to do some more advanced drawing on watchOS, or especially animations. (Although at this point building it in SwiftUI might be a better idea – even if you just embed one tiny piece of it in a classic WatchKit interface.)

Getting the data

First, we’ll need to store some more data – right now we only store a single point (a value and a date). Luckily, we don’t need to change that much – we’re already getting all points from the given day in the response, it’s just that we’re discarding all except the last one, and now we need to keep them. In some cases we might also need to load data from the previous day, so that you don’t see an empty chart at 2am – normally we’ll simply remember old points from previous requests, but this will be needed later once we add a way to change the station we get data from.

However, this is a lot of code and it’s kind of not relevant to the topic of building a UI, so just assume that we now have an updated DataStore with an interface like this:

struct DataPoint {
    let date: Date
    let value: Double
}

class DataStore {
    var currentLevel: Double? {
        points.last?.value
    }

    var lastMeasurementDate: Date? {
        points.last?.date
    }

    var points: [DataPoint] { ... }  // keeps last 8 points
}

You can see the full (final) implementation on GitHub here:

DataStore – stores and retrieves the data to/from UserDefaults
KrakowPiosDataLoader loads the data from Krakow’s regional air monitoring service
DataManager decides when to load which data, and makes sure that complications are reloaded when needed

Or alternatively, copy the version of DataStore and KrakowPiosDataLoader from this commit that adds just the changes needed for this part.

It would also be nice to be notified in the UI when the loader loads the data in the background. To achieve that, we’ll send a notification from ExtensionDelegate when the data is received:

NotificationCenter.default.post(name: DataStore.dataLoadedNotification, object: nil)

And in the InterfaceController, we’ll subscribe to this notification:

override func awake(withContext context: Any?) {
    super.awake(withContext: context)

    updateDisplayedData()

    NotificationCenter.default.addObserver(
        forName: DataStore.dataLoadedNotification,
        object: nil,
        queue: nil
    ) { _ in
        self.updateDisplayedData()
    }
}

Adding a chart container

Add another group into the view, below the update time label, and add an Image into the group. Set the group’s Insets to 15 at the top and 15 at the bottom. Leave the size settings at the default (size to fit content + the group filling whole container width) – we’ll specify the image dimensions in the code.

Bind the image on the storyboard to an outlet in the InterfaceController:

@IBOutlet var chartView: WKInterfaceImage!

One problem with WatchKit that I’ve run into a few times is that all the view objects only have setters and no getters. It might have something to do with the fact that the UI is technically running in another process, or rather a subprocess now since watchOS 4. So reading information from the view would involve something more than simply accessing some place in the process memory. If you look at the documentation of e.g. WKInterfaceLabel, you can see that it has methods like setText, setTextColor and other inherited from WKInterfaceObject – but they don’t have matching getters like textColor. Which means that you can’t ask any view element at runtime what its current text or color is, and specifically you can’t ask it what its current size is. So if we want to render the image in code for a specific size, this size needs to be hardcoded in the code.

The only exception is that an interface controller can call the method self.contentFrame, which returns the frame of the whole view it manages – which we will be using here to at least get the width of the rendered image, since that will depend on the size of the watch (we’ll keep the same height for all sizes).

Drawing the chart

This will be quite a lot of code, so let’s put it in a separate class to avoid the Massive View Controller pattern. However, there’s an important difference here from iOS and UIKit – you’re not really supposed to subclass view classes in WatchKit. Again, if you look at the documentation for WKInterfaceLabel, WKInterfaceImage etc., they all say: “Do not subclass or create instances of this class yourself”.

But we can always have a separate class that just handles rendering a chart to a UIImage, and that’s what we’re going to do:

class ChartRenderer {

    let chartFontAttributes: [NSAttributedString.Key: Any] = [
        .foregroundColor: UIColor.lightGray,
        .font: UIFont.systemFont(ofSize: 8.0)
    ]

    let leftMargin: CGFloat = 17
    let bottomMargin: CGFloat = 10
    let rightMargin: CGFloat = 10

    func generateChart(points: [DataPoint], size chartSize: CGSize) -> UIImage? {
        ...
    }
}

We’re going to call this class from InterfaceController, at the end of the updateDisplayedData method:

let chartRenderer = ChartRenderer()

let points = dataStore.points
let chartSize = CGSize(width: self.contentFrame.width, height: 65.0)

if points.count >= 2, let chart = chartRenderer.generateChart(points: points, size: chartSize) {
    chartView.setImage(chart)
    chartView.setHidden(false)
} else {
    chartView.setHidden(true)
}

In the generateChart method, first we need some boilerplate to get the context and then capture the image at the end:

UIGraphicsBeginImageContextWithOptions(chartSize, true, 0)
guard let context = UIGraphicsGetCurrentContext() else { return nil }

let width = chartSize.width
let height = chartSize.height

// ... drawing ...

let image = UIGraphicsGetImageFromCurrentImageContext()
UIGraphicsEndImageContext()
return image

Next, let’s draw the Y axis on the left and the X at the bottom:

context.setStrokeColor(UIColor.lightGray.cgColor)
context.move(to: CGPoint(x: leftMargin, y: 0))
context.addLine(to: CGPoint(x: leftMargin, y: height - bottomMargin))
context.addLine(to: CGPoint(x: width - rightMargin + 2, y: height - bottomMargin))
context.drawPath(using: .stroke)

Next, we’ll print the min and max value on the left side of the Y axis. For that we’ll make a helper function drawText that can print text towards the left or right, or centered on the given point (in this case, these two labels will be right-aligned):

enum TextAlignment {
    case left, right, center
}

func drawText(_ text: String, x: CGFloat, y: CGFloat, alignment: TextAlignment = .left) {
    var leftPosition = x

    if alignment != .left {
        let width = text.size(withAttributes: chartFontAttributes).width
        leftPosition -= (alignment == .right) ? ceil(width) : ceil(width / 2)
    }

    text.draw(at: CGPoint(x: leftPosition, y: y), withAttributes: chartFontAttributes)
}

And we print the values like this:

let values = points.map { $0.value }
let minValue = Int(values.min()!.rounded())
let maxValue = Int(values.max()!.rounded())

drawText(String(maxValue),
         x: leftMargin - 2,
         y: -2,
         alignment: .right)
drawText(String(minValue),
         x: leftMargin - 2,
         y: height - bottomMargin - 10,
         alignment: .right)

Finally, we’ll calculate the position of each point based on the values from the DataStore and draw a line through them, and print matching hour labels exactly below the points, below the X axis. We’ll need two more helper functions for this:

func chartPosition(forPointAt index: Int, from values: [Double], chartSize: CGSize) -> CGPoint {
    let xPadding: CGFloat = 3
    let yPadding: CGFloat = 3
    let innerWidth = chartSize.width - leftMargin - 2 * xPadding - rightMargin
    let innerHeight = chartSize.height - bottomMargin - 2 * yPadding

    let minValue = values.min()!
    let maxValue = values.max()!

    let xOffset = innerWidth * CGFloat(index) / CGFloat(values.count - 1)
    let yOffset = innerHeight * CGFloat(values[index] - minValue) / CGFloat(maxValue - minValue)

    return CGPoint(
        x: leftMargin + xPadding + xOffset,
        y: chartSize.height - bottomMargin - yPadding - yOffset
    )
}

func hour(for point: DataPoint) -> Int {
    return Calendar.current.component(.hour, from: point.date)
}

Next, we set some line properties to make it look better at the joints:

context.setLineWidth(1.0)
context.setLineCap(.round)
context.setLineJoin(.bevel)

And we draw the line by starting at the first point and then jumping through the rest one by one (while also printing the hours below):

let firstPosition = chartPosition(forPointAt: 0, from: values, chartSize: chartSize)
context.move(to: firstPosition)

drawText(String(hour(for: points[0])),
         x: firstPosition.x,
         y: height - bottomMargin,
         alignment: .center)

for i in 1..<values.count {
    let position = chartPosition(forPointAt: i, from: values, chartSize: chartSize)
    context.addLine(to: position)

    drawText(String(hour(for: points[i])),
             x: position.x,
             y: height - bottomMargin,
             alignment: .center)
}

context.setStrokeColor(UIColor.white.cgColor)
context.drawPath(using: .stroke)

Voila 😄

(I suppose we could use a time formatter to print the hour labels here in a 12-hour format if the device uses one… but let’s leave that as an exercise for the reader ;)

Testing on different screen sizes

There are currently 4 different Apple Watch screen sizes, and we need to make sure that our app works on each of them. Fortunately, in our case it seems to mostly work fine on any screen and also with different text sizes set in the Settings. I’ve built the storyboard and tested the app mostly on the 42mm variant, since I’m using a Series 3 42mm Watch right now, and I think that in general, just like on iOS, it’s a good strategy to design for compact/medium-sized devices first, and then scale up to larger ones and down to the smallest ones. 40mm is more or less the same, 44mm has more space but usually fills it in the right way automatically, and 38mm might require some minor tweaks.

In this case, we’ll adapt a few things on the main screen for the 38mm:

The main circle is a bit too large there. Select the circle group, and in the inspector where you have the width & height set to 100, there is a tiny “+” on the left side – if you press it, you can add an exception for any property. Override the circle’s size to 90×90 on the 38mm (it’s good to do this when you have the storyboard set to render the scenes on this specific device, in the toolbar at the bottom, so that you see the effects immediately).

Also, in the circle group, make the radius 43 on the 38mm watch, otherwise the circle is going to look funny.
For the number label inside the circle, make the font slightly smaller too, 40pt let’s say.

Left: before the change, right: after the tweaks

Another tiny change I made was that on the new-style watches (40mm and 44mm) I changed the top spacing for the first group from 8 to 5 – these watches seem to automatically have some larger margin at the top, so we don’t need to add that much, and on the 44mm watch this allows us to fully see the update time label below.

The rest should look ok – 38mm watches also have a smaller default text size than the larger ones (although you can change it of course), and 44mm has a larger default text size.

We could possibly make the chart height slightly smaller or larger depending on the width (that would have to be changed in code, since that’s where we hardcoded it), but it looks ok as it is.

42mm, 40mm & 44mm

You’re going to have a bit more work if you use static images in your app. In that case, images will usually be scaled exactly as they are saved in the file, and they will not change their size automatically based on the screen size (unless you set their widths relatively to the container). So it would probably make sense to have different variants of the same image for each screen size. Since watchOS 6, App Store uses app thinning to only download assets for a given Watch size, so it doesn’t make the bundle larger for your users, and by providing smaller image variants you can save some space on smaller devices.

There are also some gotchas related to the rounded corners, safe areas and margins on the Series 4+ watches, but this should mostly be handled automatically if you’re using system controls, and you might only run into problems if you’re using SpriteKit/SceneKit views. You can learn about that from this 9-minute talk on Apple’s site.

The main app screen is complete now and we’ve reached the end of the first part of the tutorial. If you want to look at the code on GitHub, the version after this part is available here.

In the second part, we’ll build a second screen for choosing the station providing the data from a list of available stations.

Next post: #4 Tables and Navigation >

SwiftUI betas - what changed before 1.0

2020-08-17T12:26:14Z

In the last few weeks I’ve been trying to catch up on SwiftUI - watching WWDC videos, reading tutorials. Not the new stuff that was announced 2 months ago though - but the things that people have been using for the past year.

Last June, like everyone else I immediately started playing with SwiftUI like a kid with a new box of Legos. In the first month I managed to build a sample Mac app for switching dark mode in apps. However, after that I got busy with some other things, and never really got back to SwiftUI until recently, so by the time the “version 2” was announced at the online-only WWDC, I’ve already forgotten most of it. So in order to not get this all mixed up, I decided to first remember everything about the existing version, before I look at the new stuff.

Back then, when I was watching all the videos and doing the tutorial, I was taking a lot of notes about all the components, modifiers and APIs you can use, every single detail I noticed on a slide. However, I was surprised to see how many of those things I wrote down don’t work anymore. After the first version that most people have played with and that the videos are based on, there were apparently a lot of changes in subsequent betas (especially in betas 3 to 5). Classes and modifiers changing names, initializers taking different parameters, some things redesigned completely.

And the problem is that all those old APIs are still there in the WWDC videos from last year. But WWDC videos are usually a very good source of knowledge, people come back to them years later looking for information that can’t be found in the docs, Apple even often references videos from previous years in new videos, because they naturally can’t repeat all information every year.

This was bothering me enough that I decided to spend some time collecting all the major changes in the APIs that were presented in June 2019, but were changed later in one place. If you’re reading this in 2021 or 2022 (hopefully that damn pandemic is over!), watching the first SwiftUI videos and wondering why things don’t work when typed into Xcode - this is for you.

Here’s a list of what was changed between the beta 1 from June 2019 and the final version from September (includes only things that were mentioned in videos or tutorials):

NavigationButton

Appeared in: “Building Lists and Navigation” tutorial, “Platforms State of the Union”

ForEach(store.trails) { trail in
    NavigationButton(destination: TrailDetailView(trail)) {
        TrailCell(trail)
    }
}

Replaced with: NavigationLink

ForEach(store.trails) { trail in
    NavigationLink(destination: TrailDetailView(trail)) {
        TrailCell(trail)
    }
}

PresentationButton / PresentationLink

Appeared in: “Composing Complex Interfaces” tutorial, “Platforms State of the Union”

.navigationBarItems(trailing:
    PresentationButton(
        Image(systemName: "person.crop.circle"),
        destination: ProfileScreen()
    )
)

Replaced with: PresentationLink, which was later removed and replaced with .sheet:

.navigationBarItems(trailing:
    Button(action: { self.showingProfile.toggle() }) {
        Image(systemName: "person.crop.circle")
    }
)
.sheet(isPresented: $showingProfile) {
    ProfileScreen()
}

SegmentedControl

Appeared in: “Working With UI Controls” tutorial

SegmentedControl(selection: $profile.seasonalPhoto) {
    ForEach(Profile.Season.allCases) { season in
        Text(season.rawValue).tag(season)
    }
}

Replaced with: Picker with SegmentedPickerStyle()

Picker("Seasonal Photo", selection: $profile.seasonalPhoto) {
    ForEach(Profile.Season.allCases) { season in
        Text(season.rawValue).tag(season)
    }
}
.pickerStyle(SegmentedPickerStyle())

TabbedView and tabItemLabel

Appeared in: “SwiftUI Essentials”, “SwiftUI on All Devices”

TabbedView {
    ExploreView().tabItemLabel(Text("Explore"))
    HikesView().tabItemLabel(Text("Hikes"))
    ToursView().tabItemLabel(Text("Tours"))
}

Replaced with: TabView and tabItem:

TabView {
    ExploreView().tabItem { Text("Explore") }
    HikesView().tabItem { Text("Hikes") }
    ToursView().tabItem { Text("Tours") }
}

DatePicker(selection:minimumDate:maximumDate:displayedComponents:)

Appeared in: “Working With UI Controls” tutorial

DatePicker(
    $profile.goalDate,
    minimumDate: startDate,
    maximumDate: endDate,
    displayedComponents: .date
)

The minimumDate and maximumDate parameters were replaced with a ClosedRange<Date>, and a label parameter was added:

DatePicker(
    selection: $profile.goalDate,
    in: startDate...endDate,
    displayedComponents: .date
) {
  Text("Goal Date")
}

You can also use this shorthand variant with a string label:

DatePicker(
    "Goal Date",
    selection: $profile.goalDate,
    in: startDate...endDate,
    displayedComponents: .date
)

TextField(_:placeholder:), SecureField(_:placeholder:)

Appeared in: “Platforms State of the Union”, “Working With UI Controls” tutorial

TextField($profile.username, placeholder: Text(“Username”))
SecureField($profile.password, placeholder: Text(“Password”))

Replaced with:

TextField("Username", text: $profile.username)
SecureField("Password", text: $profile.password)

ScrollView(showsHorizontalIndicator: false)

Appeared in: “Composing Complex Interfaces” tutorial

ScrollView(showsHorizontalIndicator: false) {
    HStack(alignment: .top, spacing: 0) {
        ForEach(self.items) { landmark in
            CategoryItem(landmark: landmark)
        }
    }
}

Replaced with: ScrollView(.horizontal, showsIndicators: false)

ScrollView(.horizontal, showsIndicators: false) {
    HStack(alignment: .top, spacing: 0) {
        ForEach(self.items) { landmark in
            CategoryItem(landmark: landmark)
        }
    }
}

It doesn’t seem to be possible now to have a scroll view that scrolls in both directions, but only shows indicators on one side (?)

List(_:action:)

Appeared in: Keynote, “Platforms State of the Union”

List(model.items, action: model.selectItem) { item in
    Image(item.image)
    Text(item.title)
}

Removed sometime in later betas - you can use selection: instead:

List(model.items, selection: $selectedItem) { item in
    Image(item.image)
    Text(item.title)
}

Text.color()

Appeared in: “Composing Complex Interfaces” tutorial, Keynote, “Platforms State of the Union”

Text(item.subtitle).color(.gray)

Replaced with: .foregroundColor()

Text(item.subtitle).foregroundColor(.gray)

Text.lineLimit(nil)

Appeared in: “Platforms State of the Union”, “SwiftUI on All Devices”

Text(trail.description)
    .lineLimit(nil)

Text used to have a default line limit of 1, so if you wanted to have a multi-line text control showing some longer text, you had to add .lineLimit(nil).

This was changed later and now no limit is the default. Instead, you may need to add .lineLimit(1) if you want to make sure that label contents don’t overflow into a second line if it’s too long.

Text(verbatim:)

Appeared in: “Building Lists and Navigation” tutorial, “SwiftUI on All Devices”

Text(verbatim: landmark.name)

It’s unclear if and when anything has changed in this API since beta 1. The current docs say that:

Text("string") used with a literal string is automatically localized
Text(model.field) used with variable is not localized
Text(verbatim: "string") should be used with a literal string that should not be localized

So verbatim: shouldn’t (or can’t) be used with variables like in the code above anymore, since in this variant the text will not be translated anyway. The parameter was removed from later versions of the tutorial code.

If you do want to localize a text that comes from a model property, use Text(LocalizedStringKey(value)).

.animation(…)

Appeared in: “Animating Views and Transitions” tutorial, “Introducing SwiftUI”, “SwiftUI on All Devices”

The .animation modifier has a number of different animation styles that you can choose from. This set of options has changed between the first beta and the final version.

In beta 1 you could do:

.animation(.basic())
.animation(.basic(duration: 5.0, curve: .linear))
.animation(.basic(duration: 5.0, curve: .easeIn))
.animation(.basic(duration: 5.0, curve: .easeInOut))
.animation(.basic(duration: 5.0, curve: .easeOut))

.animation(.default)
.animation(.empty)

.animation(.fluidSpring())
.animation(.fluidSpring(
  stiffness: 1.0, dampingFraction: 1.0, blendDuration: 1.0, timestep: 1.0, idleThreshold: 1.0
))

.animation(.spring())
.animation(.spring(mass: 1.0, stiffness: 1.0, damping: 1.0, initialVelocity: 1.0))

The .basic animations were replaced with options named after the selected curve:

.animation(.linear)
.animation(.linear(duration: 1.0))
.animation(.easeIn)
.animation(.easeIn(duration: 1.0))
.animation(.easeInOut)
.animation(.easeInOut(duration: 1.0))
.animation(.easeOut)
.animation(.easeOut(duration: 1.0))

(I’m not sure what .basic() without any parameters used to do exactly.)

What was called .spring is now .interpolatingSpring:

.animation(.interpolatingSpring(mass: 1.0, stiffness: 1.0, damping: 1.0, initialVelocity: 1.0))

And .fluidSpring is now either .spring or .interactiveSpring

.animation(.spring())
.animation(.spring(response: 1.0, dampingFraction: 1.0, blendDuration: 1.0))
.animation(.interactiveSpring())
.animation(.interactiveSpring(response: 1.0, dampingFraction: 1.0, blendDuration: 1.0))

.default is still available (I’m not sure what it does though) and .empty was removed.

.background(_:cornerRadius:)

Appeared in: “Platforms State of the Union”, “SwiftUI Essentials”

Text("🥑🍞")
    .background(Color.green, cornerRadius: 12)

Removed later - you can use separate .background and .cornerRadius modifiers to achieve the same effect:

Text("🥑🍞")
    .background(Color.green)
    .cornerRadius(12)

.identified(by:) method on collections

Appeared in: “Building Lists and Navigation” tutorial, “Platforms State of the Union”, “SwiftUI on All Devices”

ForEach(categories.keys.identified(by: \.self)) { key in
    CategoryRow(categoryName: key)
}

Replaced with: id: parameter

ForEach(categories.keys, id: \.self) { key in
    CategoryRow(categoryName: key)
}

.listStyle, .pickerStyle etc. with enum cases

Appeared in: “Introducing SwiftUI”, “SwiftUI Essentials”

.listStyle(.grouped)
.pickerStyle(.radioGroup)
.textFieldStyle(.roundedBorder)

Replaced with: creating instances of specific types

.listStyle(GroupedListStyle())
.pickerStyle(RadioGroupPickerStyle())
.textFieldStyle(RoundedBorderTextFieldStyle())

.navigationBarItem(title:)

Appeared in: “Platforms State of the Union”

NavigationView {
    List {
        ...
    }
    .navigationBarItem(title: Text("Explore"))
}

Replaced with: .navigationBarTitle

NavigationView {
    List {
        ...
    }
    .navigationBarTitle("Explore")
}

.onPaste, .onPlayPause, .onExit

Appeared in: “Integrating SwiftUI”

.onPaste(of: types) { provider in
    self.handlePaste(provider)
}
.onPlayPause {
    self.pause()
}
.onExit {
    self.close()
}

Replaced with .onPasteCommand, .onPlayPauseCommand, .onExitCommand

.onPasteCommand(of: types) { provider in
    self.handlePaste(provider)
}
.onPlayPauseCommand {
    self.pause()
}
.onExitCommand {
    self.close()
}

.tapAction

Appeared in: “Platforms State of the Union”, “Introducing SwiftUI”, “SwiftUI on All Devices”

Image(room.imageName)
    .tapAction { self.zoomed.toggle() }

MacLandmarkRow(landmark: landmark)
    .tapAction(count: 2) { self.showDetail(landmark) }

Replaced with: .onTapGesture

Image(room.imageName)
    .onTapGesture { self.zoomed.toggle() }

MacLandmarkRow(landmark: landmark)
    .onTapGesture(count: 2) { self.showDetail(landmark) }

BindableObject and didChange

Appeared in: “Handling User Input” tutorial, “Introducing SwiftUI”, “Data Flow Through SwiftUI”

class UserData: BindableObject {
    let didChange = PassthroughSubject<UserData, Never>()

    var showFavorites = false {
        didSet {
            didChange.send(self)
        }
    }
}

Replaced with: ObservableObject with objectWillChange (needs to be called before the change!). objectWillChange is automatically included, so you don’t need to declare it.

class UserData: ObservableObject {
    var showFavorites = false {
        willSet {
            objectWillChange.send(self)
        }
    }
}

In simple cases, you can use the @Published attribute instead which handles this automatically for you:

class UserData: ObservableObject {
    @Published var showFavorites = false
}

BindableObject was used together with:

@ObjectBinding

Appeared in: “Handling User Input” tutorial, “Introducing SwiftUI”, “Data Flow Through SwiftUI”

@ObjectBinding var store = RoomStore()

Replaced with: @ObservedObject

@ObservedObject var store = RoomStore()

Collection methods on Bindings

I don’t think this was mentioned in any talks or tutorials, but there were some tweets going around last June showing how you can do some cool tricks with bindings by calling methods on them, e.g.:

Toggle(landmark.name, isOn: $favorites.contains(landmarkID))

Sadly, this was removed in a later beta. The release notes include some extension code that you can add to your project to reimplement something similar.

Command

Appeared in: “SwiftUI on All Devices”

extension Command {
    static let showExplore = Command(Selector("showExplore"))
}

.onCommand(.showExplore) { self.selectedTab = .explore }

Replaced with: using Selector directly

.onCommand(Selector("showExplore")) { self.selectedTab = .explore }

Length

Appeared in: “Animating Views and Transitions” tutorial

var heightRatio: Length {
    max(Length(magnitude(of: range) / magnitude(of: overallRange)), 0.15)
}

Replaced with: CGFloat

var heightRatio: CGFloat {
    max(CGFloat(magnitude(of: range) / magnitude(of: overallRange)), 0.15)
}

#if DEBUG

Appeared in: all tutorials, “Platforms State of the Union”, “Introducing SwiftUI”

This was automatically added around the preview definition in all SwiftUI view files created in beta versions of Xcode 11:

#if DEBUG
struct CircleImage_Previews: PreviewProvider {
    static var previews: some View {
        CircleImage()
    }
}
#endif

It was removed from the templates in one of the final betas - you no longer need to add that:

struct CircleImage_Previews: PreviewProvider {
    static var previews: some View {
        CircleImage()
    }
}

Photo library changes in iOS 14

2020-07-07T14:36:05Z

I’m the kind of person who cares a lot about their digital privacy. It makes me very uncomfortable when I see ads on Facebook for something I opened on another site a moment ago, and I generally don’t like it when companies are learning more about me than they should, even if the effects of that tracking aren’t as obvious.

That’s why for example I’ve been trying to move away from Google services as much as possible (I use ProtonMail as my main email and Apple’s iWork for documents), I also started using Tresorit and iCloud1) for file sync instead of Dropbox. That’s also one of the reasons why I’ve always used some kind of ad & tracker blocker in my browsers – previously Ghostery, now I also use Brave and I’ve been experimenting with making my own ad blocker.

So it always makes me happy when Apple introduces another change to their OSes that limits the kinds of data that Mac and iOS apps can use without our permission. I especially liked:

when iOS 11 introduced the “While Using” option for location access that was non-optional for apps
the “Allow Once” option for location access in iOS 13
permissions to things like camera, microphone or screen recording on the Mac

This year Apple made another batch of changes that limit apps' access to data. The most interesting ones are the approximate location access and the limited photo library – in this post I’ll talk about the latter.

Most of us have thousands of photos on our phones, often going a few years back – after all, our iPhones are our primary cameras these days. These photos and videos capture everything we do, the places we go to, who we meet with and what we do together. They also include location info in their metadata. This is all possibly extremely sensitive data.

So far however if you wanted to upload a single photo or screenshot to e.g. Twitter or Facebook or send it to a friend through a messaging app, you had to grant them access to your whole photo library – it was all or nothing. And you could never be sure what they do with it – are they just looking at this single picture, or maybe looking through your whole 30 GB library for any interesting stuff they can find there, and uploading that to their servers? Hopefully they aren’t, but you just had to trust them on this.

Apple had previously provided a system image picker (UIImagePickerController) that lets the user choose a photo from their library and pass it to the app without giving it access to the library, as well as a way to save photos to the library without seeing what else is there (UIImageWriteToSavedPhotosAlbum()). However, for various reasons these don’t seem to be widely used in popular apps – most apps that do anything with photos currently ask for full read-write access to the whole library, just because they can.

So this year Apple is taking a bit of a carrot and stick approach: the carrot is a new improved system photo picker, while the stick is a new way for the user to only give the app access to selected photos.

PHPicker

PHPicker (not an actual name you can find in the docs, but a general name Apple uses for this new API) is a new system photo picker, a replacement for the old UIImagePickerController. The two most important differences are:

it has an integrated search, so it can help you find some specific photos that may not be recent
unlike UIImagePickerController it allows multiple selection

It also has an updated design, and while you’re scrolling the photo grid you can zoom in and out to see more or less photos at the same time:

How to use the picker

The API consists of a few types with the PHPicker* prefix, and most of them are surprisingly simple.

The main class that handles the picker screen is PHPickerViewController. It has a delegate protocol, PHPickerViewControllerDelegate, which you need to implement. You also need a PHPickerConfiguration object to pass it to the picker controller, in which you can set a few options for the picker.

You create a picker controller like this:

var config = PHPickerConfiguration()
// ...
let picker = PHPickerViewController(configuration: config)
picker.delegate = self

There are currently two options you can set in the picker configuration:

1) selectionLimit

This is the maximum number of items that the user can pick. The default is 1, and you can set it to some specific number, or to 0 to allow unlimited selection.

config.selectionLimit = 0

2) filter

The filter can be one of .images, .livePhotos, .videos, or a subset of those created using the .any(of:) helper:

config.filter = .images
config.filter = .any(of: [.images, .livePhotos])

Once the picker is configured, you can present it in the usual way:

present(picker, animated: true)

The last thing to do is to implement PHPickerViewControllerDelegate, which includes literally a single method: picker(_: didFinishPicking results:). This method is called with a list of one or more PHPickerResult objects in the response when the user confirms their selection. With single selection it returns immediately when the user taps a photo, and with multi-selection they need to confirm it with a toolbar button when they finish selecting.

The only part here that is not simple is that the photos are returned wrapped in NSItemProvider objects (used e.g. in the drag & drop API, or in some kinds of extensions). You need to get that item provider and first call canLoadObject(ofClass:) and then loadObject(ofClass:) (though I’m not 100% sure if the first is technically required).2)

You also need to dismiss the picker view – it doesn’t hide itself automatically:

func picker(
    _ picker: PHPickerViewController, 
    didFinishPicking results: [PHPickerResult])
{
    picker.dismiss(animated: true)

    for result in results {
        let provider = result.itemProvider

        if provider.canLoadObject(ofClass: UIImage.self) {
            provider.loadObject(ofClass: UIImage.self) { image, error
                // ... save or display the image, if we got one
            }
        }
    }
}

Apple is expecting that most apps that only access the photo library to attach one or two pictures to a post will switch to this new system picker now. (The old UIImagePickerController is deprecated – that is, the class itself is not, but it’s only keeping the camera part of its functionality.)

And if they don’t like the carrot… well, then there’s still the stick.

Limited photo library

The stick is that there is now a standard way for the user to only grant an app access to a selected subset of photos (most likely just a few, since they need to manually tap each one). This is *not opt-in* for apps – it affects every app immediately, even those that have been built on older SDKs.

The way it works is that when the app tries to access the photo library (or explicitly asks for authorization), the user will now see a popup that looks like this:

The top option leads them to a selection dialog which is the same new picker you’ve seen above.

When the user confirms the selection, the app gets access to a kind of “virtual” photo library that only contains those few photos they’ve selected. To the app it looks almost like a normal photo library, it just has 5 photos in it instead of 2000 – that’s how it can work in existing apps. The app can’t access the remaining photos in any way, or even have any idea how many there are in total.

It can however tell whether it got access to the full library, or some limited subset. You can use the PHPhotoLibrary.authorizationStatus method for this (which has an updated API – it now requires an accessLevel parameter, which is .addOnly or .readWrite):

switch PHPhotoLibrary.authorizationStatus(for: .readWrite) {
case .notDetermined:
    // ask for access
case .restricted, .denied:
    // sorry
case .authorized:
    // we have full access

// new option: 
case .limited:
    // we only got access to a part of the library
}

To ask for access, you also need to pass the accessLevel parameter (remember to include a NSPhotoLibraryUsageDescription key in your Info.plist):

PHPhotoLibrary.requestAuthorization(for: .readWrite) { status in
    // …
}

For backwards compatibility, the old (deprecated) versions without the parameter return .authorized even when you get limited access.

Updating the selection

You’re probably asking now: how can the user update the selection? If we’re talking about an app like Twitter or Facebook Messenger, the user will only select a few photos that they want to share, but next time when they want to post a photo, they will already be authorized – so the popup won’t appear, and they will just be choosing from the same few photos they chose last time. Not good.

So there are a few ways to solve this:

1) Settings

The user can always go to the Settings app, the Privacy section and update their selection there. However, they need to first know that there is such option and where to find it (the app can’t even deep-link to this specific page), so this is more like a last resort fallback.

2) Repeated alert

By default if the user grants limited access to the photo library to an app, they will see the same popup again after the app is restarted, and through that popup they can update their selection. This is also more of a way to somehow imperfectly support apps that haven’t been updated to the latest SDK – it solves the problem, but in an awkward way and only partially, since the popup won’t appear if you just hide the app, take a few more photos and open it again to share them, and the app doesn’t restart in the meantime.

3) Showing the selection UI again

If you want handle this properly, the recommended way is to manually request to show the selection UI again. Apple explains that if you have an app that requires full access to the photo library (e.g. some app whose main purpose is to let you browse and organize the photo library), you should add some kind of button in your UI that triggers the selection screen again. This button should only appear if authorizationStatus is .limited, and hide if the user grants the app full access.

To show the selection UI, call this new method:

PHPhotoLibrary.shared().presentLimitedLibraryPicker(from: self)

The selection screen hides automatically when the user completes selection. You will not be notified of the result through any delegate method – you need to use a “change observer” to track when the set of available photos changes. Implement the protocol PHPhotoLibraryChangeObserver and call the register(_ observer:) method on the PHPhotoLibrary:

PHPhotoLibrary.shared().register(self)

func photoLibraryDidChange(_ changeInstance: PHChange) {
    // ...
}

Once you do that, it makes sense to disable that automatic alert mentioned in point 2 above – to do that, add the key PHPhotoLibraryPreventAutomaticLimitedAccessAlert to your Info.plist.

4) Using a system picker

The best option though is that you don’t ask for access to the photo library at all 😏 Remember the carrot? If you use the new system picker, you don’t need to ask for photo library authorization. The picker runs in a separate process, it handles the selection for you and sends you back only what the user selected, so they implicitly grant you access to those photos they picked. No other popups, no checking for authorization.

So if you have an app that currently uses some kind of sliding sheet showing recent photos from which the user picks one to attach it to a post, you really, really should consider just using the system picker, instead of keeping the sheet as a kind of “staging area” and adding another unnecessary step to the flow.

Saving to the library

One special case is when you only need to save to the library, but don’t need to read from it – e.g. you want to let your users save some pictures from a feed or a website. In this case, you only need to ask for an “add only” access, which users may be more likely to grant if it’s obvious that your app doesn’t have any legitimate need for a read access. This is mostly unchanged from earlier iOS versions.

To save a picture to user’s library, you can use this method:

UIImageWriteToSavedPhotosAlbum(image, self, #selector(onImageSaved), nil)

Or just pass nils if you don’t need a callback:

UIImageWriteToSavedPhotosAlbum(image, nil, nil, nil)

If you don’t have any authorization at this point yet, it will trigger a popup asking about one – but it uses a different wording and options that the one for read-write access, making it clear that this is about add-only access:

You also need to include the usage key NSPhotoLibraryAddUsageDescription in your Info.plist.

If you’d prefer to ask the user for write access explicitly, you can use the same requestAuthorization method:

PHPhotoLibrary.requestAuthorization(for: .addOnly) { status in
    …
}

It will be interesting to see in the coming months how popular apps like Twitter, Facebook, Messenger etc. react to this new situation. The ideal scenario would be that they all switch to PHPicker and avoid the trouble with limited access – this is also, I believe, better UX for the users than if they insist on using library access and presentLimitedLibraryPicker. The worst case scenario is that they do nothing, assume that most users don’t care about privacy or will be too lazy and will just grant them full access, and those who insist on protecting their private photos will be left with working but kinda awkward user experience. Or maybe they’ll figure out something that works well – we’ll see.

1) Yes, I know that iCloud Drive is not end-to-end encrypted – but I trust Apple infinitely more than I trust Google and Dropbox. Hopefully they will add full encryption at some point – they are slowly expanding the range of things that are end-to-end encrypted, e.g. last year they’ve added some synced Safari data to the list. ↩︎

2) This doesn’t seem to currenly work in the simulator in beta 1, including in Apple’s sample code from the talk about the picker. I haven’t tried on a real device. ↩︎