Articles index

iOS 15.2 broke Safari extension preferences storage

December 14 2021 by Jeff Johnson
Support this blog: StopTheMadness, Tweaks for Twitter, StopTheScript, Link Unshortener, PayPal.Me

Apple made a breaking change to Safari extension preferences storage in iOS 15.2 and iPadOS 15.2, which were released to the public yesterday. I believe but haven't confirmed that this breaking change was also made in Safari 15.2 for macOS, which was included in yesterday's Monterey update. I assume that Safari 15.2 is forthcoming for macOS Big Sur and Catalina too, though for some reason it hasn't yet been released (despite the 0day security vulnerabilities already announced in the release notes).

For StopTheMadness Mobile Customers:

Before I discuss the technical details of the preferences storage breakage, I want to make an announcement for my customers: unfortunately, StopTheMadness Mobile is affected. My other extensions — StopTheMadness on macOS, Tweaks for Twitter on iOS and macOS, and StopTheScript on iOS — are unaffected, for reasons I'll explain in the technical details. In general, StopTheMadness Mobile works fine on iOS 15.2, and if you've never made any changes to your preferences, which I call "website options" in StopTheMadness, then you're also unaffected. However, if you've changed your preferences, customized your website options in any way, then your preferences may have reverted to the default values after the iOS 15.2 update.

Within a few hours of discovering the problem yesterday, I submitted a StopTheMadness Mobile update that can restore your missing preferences. At the time of publication of this blog post, the update is still waiting for review by Apple. There's a big caveat: the StopTheMadness update will restore your old website options only if you haven't changed them again after the iOS 15.2 update. Technically, I could restore your old preferences in any case, but then I would have to erase any newly set preferences. I don't think that two wrongs, two consecutive losses of data, make a right. I might have done that if I could have gotten the update immediately into customer hands yesterday, but I can't predict when it will be released or when customers will install it. Moreover, I was in a rush to release a fix, so I didn't have time to sit back and design the "perfect" solution for this pressing problem.

If your customized StopTheMadness Mobile website options disappeared after the 15.2, you have two choices. (1) You can manually set them again, then everything should be fine thereafter, and you won't lose your preferences again. Or (2) you can wait for the StopTheMadness Mobile 2.6 update, and avoid changing your website options. In the meantime, you can continue to use StopTheMadness, as long as you're ok with the default values (which should be mostly ok, by design). If you have any questions, please contact support.

Technical Details:

I've pieced together the details from a few different sources. The breaking change involves the extension sync storage API. This is a cross-platform API shared by Chrome extensions, Firefox extensions, and Safari web extensions. Two types of storage are defined by the API for the purpose of saving browser extension data, such as user preferences, on your device: sync and local. Chrome and Firefox each have a built-in sync mechanism, so an extension can use sync storage to ensure that the user's preferences are synced among all of the user's devices running Chrome or Firefox. Local storage, on the other hand, is not synced. Safari also has a built-in sync mechanism, namely, iCloud, but no Safari extension data is (yet?) synced by iCloud. Nonetheless, Safari adopts the same extension API of local and sync storage. This allows extension developers to use the same code with Chrome, Firefox, and Safari, and indeed StopTheMadness shares some code between its Chrome, Firefox, and Safari versions, which is why StopTheMadness Mobile uses extension sync storage.

Aside: StopTheMadness for desktop Safari, the first version I wrote, still uses an older, Mac-specific "app extension" API that saves data in an entirely different way, which is why it's unaffected by the sync storage change. Tweaks for Twitter uses local storage rather than sync storage, because its preferences are minimal, so I never felt the need for sync even with Chrome. And my extension StopTheScript has no preferences: it relies on Safari's own built-in permissions system to determine whether it runs on particular sites. Thus, StopTheMadness Mobile is the only one of my extensions that's affected by he breaking change. However, Safari extensions from other developers may also be affected by the breaking change, if they use sync storage. This is more likely for cross-platform extensions.

What happened with extension sync storage, I believe, is that Safari 15.0 had a bug, and then Safari 15.2 "fixed" the bug. I said above that two wrongs don't make a right, but apparently Apple thinks they do! In my Google searches I came across an Apple Developer Forum post titled Bug: Local and Sync storage merged since safari 15.

Since Safari 15, the extensions local and sync storage seems to be merged into one. This means operations in local storage apply to sync storage and the reverse. This caused the users of of my extensions with more than half a million of downloads to loose all their user settings. To keep compatibility across browsers, the sync and local storage should be separated.

The catch to this is that Mobile Safari didn't have web extensions at all until iOS 15.0, released a few months ago, whereas Mac Safari introduced web extensions in version 14.0, released in 2020. So if you're the developer of a macOS Safari extension that uses sync storage, you may have noticed a problem when Safari 15.0 was released a few months ago, but if you're the developer of an iOS Safari extension that uses sync storage, and only sync storage, you may have never noticed a problem until now!

Googling also uncovered identical release notes for macOS 12.1 beta 2 and iOS 15.2 beta 2 back in November. (For some reason, Apple deletes the beta release notes from its website when the beta period is over.)

In Safari 15 and 15.1, sync storage for Safari Web Extensions is no longer being written into the local storage area. Developers using sync storage can check for storage in the local storage area if they can’t find their data in the sync storage area and do a one-time migration.

This description is very confusing, and I think… wrong? Almost the opposite of the truth. What it should have said, as far as I understand, is something like "In Safari 15 and 15.1, sync storage for Safari Web Extensions is being written into the local storage area, but no longer in macOS 12.1 beta 2 and iOS 15.2 beta 2." The iOS 15.2 beta release notes are especially confusing, because Safari doesn't have explicit version numbers on iOS (no "About" windows!), and as I already noted, Safari web extensions did not exist on iOS until version 15.0.

Safari Technology Preview has some less confusing release notes.

Fixed an issue where browser.storage.sync entries were saved into the browser.storage.local storage area. If unable to locate sync storage entries, check in the local storage area and do a one-time migration to the sync storage area

Safari Technology Preview is only for macOS, though, not for iOS. And these release notes didn't mention when the issue was introduced, unlike the (confusing) beta release notes.

The behavior I observe on iOS 15.2 is that when my extension checks sync storage, it finds nothing, but if it checks local storage, it finds the old preferences that were previously saved to sync storage. So restoring the old preferences is a relatively "simple" matter of falling back to local storage if there's nothing in sync storage. (This is actually very complicated in StopTheMadness because the storage is accessed in many places: the content script loaded into every frame on every page in every tab, the non-persistent background script, and the preferences window. I keep sanity here by only writing to the storage in one place, the preferences window.) If something is found in sync storage, on the other hand, then the fallback is not used. Technically, the old preferences are still there in local storage, even if new preferences are set in sync storage on iOS 15.2, so it would still be possible to restore the old preferences in the future. I'll have to give some thought to whether that's feasible or advisable. The more time passes, the less appealing that possibility would become for users. And every iOS App Store update I release must first pass through Apple review, which can take days. But I hope that StopTheMadness Mobile 2.6 will be reviewed and approved today.

Support this blog: StopTheMadness, Tweaks for Twitter, StopTheScript, Link Unshortener, PayPal.Me

Articles index