• Link
• Mail
• Twitter
• Facebook
• Instagram
• LinkedIn
• GitHub
• Twitch
• YouTube

Having implemented the backend and licensing mechanism, there was still an important part missing: a way to download and install updates for the app.

A “safer” download

My app trial downloads have always been just a direct file download. But because I wanted the auto-updating mechanism in my app to use that same download path, I needed to add a little layer of validation/safe-guard there.
Step 1: sign the zip file cryptographically with a private key, and upload the signature data alongside the zip file.
Step 2: write a download PHP script. Instead of just initiating a direct file download, the script starts the download, only if the zip file’s signature could be verified with the public key. If there’s a signature mismatch, an email is sent to me so I know there’s something going on.
Step 3: implement the download and signature check in the app. The app downloads the update zip file using the PHP script, with the signature of it passed along as a header. That allows the app to verify the zip file’s signature with the public key, before unzipping it. If the signature can’t be verified (because it was tampered with, or the download got corrupted somehow), the zip file is discarded and an error presented.

I got you, “gotcha”s

With the PHP download script, I encountered two “gotcha”s.
One was that, no matter what I tried, I couldn’t set the Content-Length header, which lets the downloading client know how much data to expect (so a download progress can be displayed properly). A lot of googling later ^{(I also tried ChatGPT for fun, but it was no help here)}, there’s an environment variable that needed to be set on my server:

SetEnv ap_trust_cgilike_cl 1

With that, it miraculously started working.

The second “gotcha” was resumable downloads.
For a file that is only a few megabytes, it’s not that big of a deal, but for larger downloads, it is convenient and responsible to have resumable downloads.
If a download halts because of, say, a loss of connection, the downloader is able to later pick up the download from where it left off, instead of discarding what it had already downloaded and having to start over.
It took a bit of trial and error, but thankfully, there are lots of code samples for this available, this one being a prime specimen, and I eventually got it working.

Release the Notes

I just recently revamped my release notes to be more interactive:

It gives a nice overview of new features, improvements and bug fixes, I can display a nice header or footer if I like, and I can show users new features in action on-the-fly as a video, an image, display a website for instructions, or take users to features or settings in-app right away.

But I hadn’t thought it through enough. All this had been powered by a single JSON file. For multiple releases, over the years, that file would become larger and larger. And to display information for one release, I’d have to download the entire file. So I had to go back in and change that.
Instead of a single JSON file, I now have it in a database, each release in a row, so I can obtain information for individual releases, instead of having to download all of them at once.
Interacting with this database is powered by a custom PHP API.
It lets me retrieve all version strings for an app, alongside their release dates and build numbers – crucial for self-updating.
I can then request an individual release’s information as an on-demand created JSON. I use this in the Mac App Store version to show what’s new after an update has happened, and in the non-Mac-App-Store version to display what’s new before an update.
Additionally, it can return more than one row of releases. That allows me to show multiple releases in the “Update available” screen:
Say a user is on version 2.1. Versions 2.1.1 and 2.2 have already been released, but the user never updated to them. Now version 2.2.1 is out, and the user gets notified. Not only does the update dialog show what’s new in version 2.2.1, users can also see what was new in v2.2 and v2.1.1. Yay.

For feeding information into the database, I wrote a little PHP web “app”:

I can add localized release notes for a feature, improvement or bug fix, and manipulate the JSON (on the right side) directly, too, if I need to change the order, or fix a typo. I can go back into any version, any time, in an organized manner.

Lastly, I can download a nicely-formatted .txt file for each localization I can copy-paste into the App Store’s What’s New section (or anywhere else I like):

Self-Updating App

The simple and sane thing to do would have been to go with Sparkle. It’s fantastic. It can work with zips and other compression formats, dmgs, can do diff updates and all that stuff. It’s really good, and if you need any of that, or just want an easy way to do updates, save yourself the headache and just use Sparkle.

All I needed, though, was to unpack a zip file and install that update. And with all that custom code I wrote on the backend, to perfectly integrate and take advantage of it all, I figured I’d write my own updating mechanism.

The app has to:
1) Check if a new version is available
2) Display to the user what’s new and ask whether they’d like to download the update
3) Download the update
4) Verify the zip file’s signature
5) Unzip the zip file if the signature is okay
6) Verify that the new bundle is code signed, and that the code signature’s team of the new bundle is the same as the old one’s
7) Replace the old copy with the new one
8) Relaunch

Items 1 through 4 were easily done – all the heavy lifting is already taken care of by the server.
Item 5 – unzipping – is where it began to become tricky.
Actually, it already became tricky zipping up the app in the first place.
Like I stated before, I upload a zip file and its signature. To create both, I use a Shortcuts.app shortcut – I select the app produced by Xcode, it gets zipped up, a signature file is created, and I manually upload both to my server.
Alas, the “Make Archive” shortcut is teh suckage when it comes to apps.
Try it yourself: Create a “Make Archive” shortcut that creates a zip archive from an app, then unzip that archive and double-click – it won’t work (or, even worse, it’ll work on your Mac, but on a different one, it won’t. Thanks to UTM, I was able to figure that out).
So instead, I use a Run shell script phase with the ditto CLI:

ditto -ckX --sequesterRsrc --keepParent <app-file-path> <zip-file-path>

Unzipping that and running the app worked right away both on my Mac and in the UTM virtual machine, so the first hurdle had been taken.
Unzipping, then, in the app, also had to be done using that CLI:

ditto -xk <zip-file-path> <unzip-file-path>

Because I didn’t test each step right away and implemented the flow in one go, when I first tried it, I wondered where my mistake was when the app didn’t launch. It was only after quite a bit of backtracking and research that I came to the conclusion that my way of zipping and unzipping was the culprit.

My current iteration of my self-updating mechanism isn’t complete yet.
It can update itself when the user account that first installed the app is also the one updating it. But if a different user account runs the update, it fails, because of insufficient privileges. I had one implementation where it worked once, and then nobody could update anymore – yikes. I had another implementation where, when replacing the old app with the new one, for some reason the /Contents/MacOS/ folder could not be replaced (but the files in MacOS were deleted), corrupting both the old and the new copy.
Let’s just say, I hit some weird edge cases here.

This is obviously something I’m working on still, but in the meantime, when I suspect it’s a different user account attempting the update, I present the user with the new version of my app in Finder, and show instructions on how to manually update.
It’s nowhere near a perfect user experience yet, but it was a trade-off I was willing to accept for the time being (on behalf of the user, I’m afraid), knowing the upside of having control over the entire thing and eventually figuring it out.

It’s my main drive at work – figuring stuff out.

Next Time

Next time, I’ll talk about how and if it all worked out. I hope to see you then!

• Link
• Mail
• Twitter
• Facebook
• Instagram
• LinkedIn
• GitHub
• Twitch
• YouTube

• Link
• Mail
• Twitter
• Facebook
• Instagram
• LinkedIn
• GitHub
• Twitch
• YouTube

Now that I’d decided on a game plan, I had to put my code where my mouth was.
I thought it best to begin with the one thing that could make or break my entire endeavor: integrating my backend with my new Merchant of Record, Paddle.

Paddle Billing

Paddle Billing is very obviously targeted at recurring payments (“subscriptions”) rather than one-time purchases, underlined by the fact that Paddle Classic did have direct support for creating and/or handling license keys, whereas Paddle Billing does not. I know subscriptions are all the rage these days, but I just don’t like them.
A Quick-Start guide on how to handle one-time purchases would have been nice, or at least some sort of direction on what API to look into. The documentation in general is very good and detailed, but it isn’t outright obvious how all the pieces fit and work together. It feels like each piece is described nicely on its own, but how it all fits into a whole flow of a user purchasing something is up for the developer to figure out.
I would have preferred a use-case approach. Like, for subscriptions, what does a typical, recurring payment flow look like from first billing, to recurring billing, to the eventual cancellation by the customer? What does a one-time purchase flow look like? What APIs are involved? How are refunds handled? What are the caveats, and what should I pay close attention to? That would have helped a lot here.
Being a developer myself, I understand the situation too well. When you develop an app, you know it inside and out. That’s good, but it makes you prone to omitting the very fundamentals of your product when explaining it to others, because it’s second nature and obvious to you. Like, when a 3-Michelin-star-chef explains cooking soup to you by talking about how to plate it up and make it look nice, and you’re there wondering how to tell when the water is boiling.

Anyway, I did figure it out – Paddle’s sandbox environment made it beautifully painless. And once I did, I was very positively surprised by how extensive the API is and what you can build with it. It’s based on events and webhooks, where your server endpoints get called when certain events in your checkout flow happen. For instance, when a customer completes a purchase of a product, you get a transaction.complete event, which means you can now fulfill the order – by sending a license key, for example. That transaction persists on their server, so you can use it again to implement a “re-send license” feature, when a customer loses the email you sent. Neat.
You could also use this to implement a reminder feature, where you mail potential customers with an incomplete transaction, asking them if they’d like to complete their order. (Local and international laws apply, of course. And if you go down this route, do it very sparingly. Most people nowadays hate getting nag-mail out of the blue).

---

I went about implementing my backend using…

PHP, the old (t)rusty

Apparently, PHP is dead. Every year anew, it seems. And yet, it’s always been there when I needed it.
It has a huge community of very helpful developers behind it, is very well documented, and there’s a vast library of frameworks and code to take inspiration from. Personally, I love it. It’s also well integrated into and supported by my web server, regularly maintained and updated, so it was a no-brainer for me to use it for this implementation.

But I am not a backend developer. I usually leave backend development to those who really know it. That being said, I didn’t want to hand off something so crucial to be implemented by someone else; I would have little control over the code, I would have had to give them access to at least my Paddle credentials, and to parts of my web server – I’d rather never eat Käseleberkäse again. And I love Käseleberkäse. When it comes to my work, I keep it all as much first-party as I possibly can.
Does that mean a task that would have taken a professional fifteen minutes takes me three hours?
…
Yes.
But I sleep so much better at night.

I second-guessed every line of PHP code I wrote to ensure it runs smoothly and safely.
Cross every ‘t’, dot every ‘i’, and htmlspecialcharacter every ‘<‘.
And PDO. Why had I never heard about PDO before? In the past, I always interfaced with databases directly using mysqli (carefully, of course), but now, with PDO (PHP Data Objects), it’s way better – and allegedly safer.

To sell ScreenFloat ^{and, in time, my other apps} directly from my website (in addition to the Mac App Store), I had to implement the following:
The Backend
– Get a webhook callback from Paddle when a successful purchase occurs
– – Validate the callback, create the license(s) from the information in the transaction and send them to the customer
– – Save minimum information in a database for the license activation, deactivation, resetting, and recovery mechanisms
– Get a webhook callback from Paddle for refunds, to disable licenses created from that purchase transaction

The Website
– Integrate Paddle’s overlay into my website for checkout
– – Have a checkout “preflight”, where customers enter their name, email, and the type of license they want to purchase, to set up the transaction used in the Paddle checkout overlay

The App
– Make ScreenFloat accept licenses to be registered with
– – Have a license reset and lost-license-retrieval mechanism in-app

What was important to me here was that (a) I could easily include other apps for purchase later, (b) the license creation and all associated functions were independent of Paddle, so I could use it with other platforms (for bundles, mostly) and subsequently (c), if ever need be, switch from Paddle to a different Merchant of Record without having to re-implement everything.

---

Setting up the webhook on Paddle is straight forward. Select the events you’re interested in getting, supply your server endpoint for them, and it’s done.

After I verify the call is actually coming from Paddle and contains a valid transaction payload, I create the cryptographically signed license(s) from the customer’s information in that transaction, along with app-related information. After I verify it is signed correctly, I send it off to the customer in a nicely formatted plain-text and html-text multi-part email.
Initially I played around with encrypting the entire license and decrypting it in the app for validation and unlocking, but in the end settled on just signing a more-or-less plaintext payload to keep it simple.

Like I said in the first part of this blog post series, personal licenses can be used to register two copies of my app (on accounts on the same Mac, or on different Macs), whereas commercial licenses can be used to register one copy, but used by any account on that Mac.
There’s quite a bit of overhead in the implementation here. If you want to keep track of activations, you need a way to do that (a database and an “API” to manage all the necessary info), and will have to have a way to reset individual or all activations of a license: if a customer gets a new Mac, they might want to move their registration over from the old one, for example.
When it comes to commercial licenses, I figured administrators wouldn’t want employees to be able to mess with a copy’s registration, so those require a “key” to be reset, which is individually created and sent alongside the license keys.

---

For the customer to get to that part, I first needed some sort of checkout on my website. Paddle provides a drop-in storefront, which handles it all. Sweet. I wanted to precede that with a simple form where the customer can select what type of license they want (personal; personal as a gift for someone else; commercial), and enter their name and email, to make sure a name is supplied for the license to be personalized with.

Here comes Paddle’s API into play – I create a new transaction from the supplied information and pass it on to the Paddle storefront, with all information already set. All that’s left then is for the customer to enter their payment details, and they’re done.

This “preflight” also allows me to provide special discounts for Apple employees, like I’ve already been doing for Yoink for Mac, (although in a very different way). I do plan to transition that over to Paddle and licenses as well, just to have it all in one place, handled by the same mechanic in the background.
I thought about implementing Paddle’s storefront in-app directly, too, but I decided against that – I believe users feel safer and more comfortable entering payment details when they’re in the browser of their choice.

---

All that work is useless if users can’t use a license in my app to unlock it. I already offer trial versions for most of my Mac apps as downloads from my website, with ScreenFloat being no exception, so I already had a head start in creating an out-of-app-store branch. All that was missing from it was the license validation and app-registration that removes the trial limitations.

The license a user receives by mail is a custom app-url-scheme link which, when clicked, automatically launches my app and fills out the required license key field, for the user to be confirmed for registration. Alternatively, I also include a download link for a license file. I figured some people might like a backup copy of it somewhere, and it can make it easier to share a gifted license.

Since licenses aren’t stored anywhere, that download link is basically the same as the custom app-url-scheme link that has the payload as a url query parameter, but instead of pointing to my app, it’s pointing to an endpoint on my server – a PHP script that turns that query parameter into a file download. I found that to be a neat workaround.
Naturally, that file can be double-clicked to register the app, if it’s already installed.
The app itself then verifies the payload locally and with the server and, if everything checks out, unlocks itself.

---

Next Time

There’s still the matter of self-updating the app, displaying release notes, and verifying app update downloads, so that’s what we’ll go over next time. I hope to see you then!

---

• Link
• Mail
• Twitter
• Facebook
• Instagram
• LinkedIn
• GitHub
• Twitch
• YouTube

• Link
• Mail
• Twitter
• Facebook
• Instagram
• LinkedIn
• GitHub
• Twitch
• YouTube

It has been I-don’t-even-know-how-long ^{(that is: an eternity)} since I last offered any of my apps for purchase outside of the App Stores.
GimmeSomeTune was donationware (handled by PayPal), but there was no licensing, so that doesn’t count.
For a software-bundle (I can’t remember the name, and I don’t believe it’s around anymore), I created a non-updatable version of ScreenFloat 1.x that customers received, yet also without licenses, so that doesn’t count either.
I think the only app I ever really sold properly and had a license scheme for and handled sales myself was flickery, which I sold from my website through PayPal before the Mac App Store arrived.
But once the Mac App Store hit, I transitioned all my apps to it pretty much right away.
It’s just so convenient: no license creation, no license verification (apart from receipt validation, but that has become more convenient recently), easy updating, no handling of payments, invoices, refunds, and the potential of getting featured to lots and lots of users.

---

Why do it, then?

Besides all that, it was high time I set up a way to also sell my apps outside of the Mac App Store.
Without a licensing system for my apps, I’ve been unable to participate in software-bundles and/or collections. Lots of companies and corporations cannot purchase apps from the Mac App Store due to policies. Individuals who want to purchase my apps for work are unable to do so because of those same policies. I also am unable to give individual discounts to customers when need be.
And while I am a strong proponent of the Mac App Store, I also believe in giving people a choice. Customers should have the choice of purchasing my apps on the App Store, or directly* from me. ^{*: I don’t handle any of the payment and invoicing myself, that’s done by my Merchant of Record, Paddle.}
Also, it certainly cannot hurt to have an alternate route to sell my apps.
What if the Mac App Store goes belly-up? Not likely, but still, I’d go belly-up along with it.
What if Apple doesn’t want my apps anymore? It could happen (it has been close before), and then I’d be screwed.

All that is just a long-winded way of saying: it makes sense to have some redundancy. A second way of selling my apps. One I have a bit more control over.

Now, I did slack off on this for a long time. I’ve been getting requests to participate in bundles for years (!) and still couldn’t bring myself to set it up. I don’t know why. I guess I thought my time was better spent working on my apps instead of backend stuff.
But then there were all these recent inquiries from companies, and users affected by policies of companies, who cannot purchase apps from the Mac App Store. For some reason, there’s been an uptick there, and requests have become more and more frequent.
So I hunkered down and finally started looking into all the things that needed to get done so I could sell my apps outside of the Mac App Store as well:

• Decide on a Merchant of Record
  (crucial for the “selling” part)
• Come up with and implement a license key scheme
  (crucial for legitimating purchases of my app)
• Freshen up my PHP, HTML and JavaScript “skills” and integrate my backend with the merchant’s
  (crucial for everything)
• Implement a way for the app to update itself
  (pretty much standard nowadays)
• In that vein, implement a safer way to download files than just a plain file-straight-from-server download
  (so the app can verify the update is legit)

---

Getting a Merchant of Record or Payment Processor

A “Merchant of Record” is a company that handles payments, invoicing, refunds, taxes, etc for indie software developers and other businesses. Payment processors “just” handle the payment part, but you’re pretty much responsible for everything else.
There are actually quite a few to choose from: FastSpring, PayPal, Paddle, Stripe, and Gumroad, just to name a few.

• PayPal I didn’t want to use because I remember its API from back in the day and it just gave me headaches. I’m actually amazed I pulled it off for flickery way back when. Also, and I might be wrong about this, but, I believe it still doesn’t handle taxes and stuff for you, and I just won’t do that myself anymore.
• Gumroad seemed to me like more of a hobby thing? Anyway, I couldn’t see myself selling software through them.
• FastSpring is a popular choice, loved for its extensive feature set.
• Stripe seemed out of my league. Like, it’s a fancy masquerade ball, and I’m in the dark corner wearing sweats, eventually getting asked to leave because I make people “uncomfortable”.

Put the Paddle to the Metal

So I went with Paddle. I don’t feel frowned upon here in my sweats. And in my calculations, it seemed a bit less expensive than FastSpring. Plus, I’ve heard good things about it. The API is well-documented* and their support seemed… supportive.
Why’s there an ominous asterisk next to “well-documented”? I’m glad you asked!
There’s Paddle Classic, and as of recently, there’s the new Paddle Billing, with a completely different API.
Guess what this idiot ^{(read: me)} did. Yup, I spent 3 days looking into and partially implementing Paddle Classic, only to find out it’s no longer available for new signups. Fun!
Hey, Paddle, I have a suggestion: Instead of that tiny, friendly light-blue indicator at the top of the Paddle Classic API documentation page that you can easily overlook and even dismiss, why not make it a big, red, bold-letter banner? That would have saved me tons of time.
Instead, I sat there wondering why none of my test-calls from the Paddle dashboard worked. ^{(Side note: Debugging remote PHP scripts is a freaking pain. Especially the way I do it – which might be the wrong way.)}
But that’s alright. Every story needs its ups and downs. Why not begin with a down outright? Who knows, it could be all uphill from here!

For selling through Paddle, you need their approval. They take a look at your website and make sure everything’s on the up-and-up regarding your Privacy Policy, Terms of Service, payment flow, checkout and whatnot.
The entire process was fairly straight-forward. It might have helped that I’m already selling my apps through the Mac App Store, so they could see that I’m serious about my endeavors. For my Terms of Service I looked into the websites of other indies selling software through Paddle, which I thought made sense, since they’re already approved by them.
It took about three weeks with a bit of back and forth to get the approval, but that was no time lost, since I used it to start implementing the correct API on the backend.

---

Scheming up a License Key

A vital part of an app sold outside of the Mac App Store is requiring the user to have a license key in order to keep using it past its trial limitations. If you don’t have that, anyone could just use your app without paying for it. That’s fine for freeware or donationware and the like, but for an app you want to sell, it’s counterproductive.

Obviously, you want to be the only one able to create these license keys. Back in the day, for flickery, I had a very traditional format: a 32-odd-character dash-separated string, like FLKRY-ABA1-ABA2-ABA3…
It was just a salted MD5 hash of a certain order of transformed and salted md5 hashes of the customer’s name and email. In the app, the user would enter their name, email and the license key and flickery would re-create the license key itself from the supplied info and see if it matches up with the one the user supplied. If it did, the app was registered, if not, then not.
In order to forge a key, one would have to know the salts, the transformations and the order I used to create a valid key. Someone with a lot of time on their hands could eventually figure it out and create a key generator. Or hack the flickery binary and figure it out that way.
^{The salts were actually more pepper than salt, as they were hopefully secret. As a side note, I don’t think the license generation was ever cracked. The app itself was, though.}

I’ve decided to go a different way this time around. The license now is a cryptographically signed payload (signed using a private key), consisting of the user’s data, app information and transactional data. All the app does is use the corresponding public key to verify the signature. If it’s valid, it can proceed with further activation steps. If not, something’s wrong with the license. As long as the private key actually stays private, there’s no feasible way to forge a license at this point in time.

I also wanted to make sure a license can only be active on a limited number of Macs or user accounts at a time, and have a way of blocklisting license keys infringing on my Terms of Service.
This is also where license types come into play.
There’s the “personal license” for individuals, which can be used to activate the app a limited amount of times (on any Mac or user account);
and the “commercial license”, which can be activated on a single Mac, but used with an unlimited amount of accounts on that Mac – a “seat” license.
With managing and limiting the activations comes the need to unregister individual copies of an app, or reset the entire license, so you can free up a slot to activate the app on a different Mac or user account. More work on the backend!

Consequently, in order to activate a copy of my app with a license key, an internet connection is required. But you also need an internet connection to download the app in the first place, so I don’t see a downside there. And there’s no always-online requirement. Only once in a while, the app will demand a connection to make sure the license and its activation are still good.

What was important to me about all this though is that none of the user’s information, not even the license key, is stored on my server. Yes, Paddle stores user data, because they have to. But I didn’t see the need to have user data be present on my server as well. It holds only the information it absolutely requires to activate, deactivate, reset, re-issue and refund licenses.

Most of this is handled on the backend, which took most of my time to implement and test. Even though I have been using PHP (with MySQL for database integration) on and off over the years, I’m by no means “fluent”, so I repeatedly had to consult different guides to figure out the best practices, and how to code safely, for everyone involved. JavaScript I’d never really used before (but had to for the Checkout pages), and HTML with CSS, well… my checkout pages are as pretty as they’re going to get, to put it bluntly.
But I learned a lot. I like doing server/website stuff for some reason. Maybe because it’s not my area of expertise, and I get to understand the workings of the internet a little bit better and learn so much. It just has a certain allure I can’t explain.

---

Next Time

In the next part, I’ll go over the integration with Paddle, and my backend implementation. I hope you’ll join me!

---

• Link
• Mail
• Twitter
• Facebook
• Instagram
• LinkedIn
• GitHub
• Twitch
• YouTube