Handbill beta tester guide

Thanks for agreeing to test handbill. The real test comes from trying to use it for fun.

This setup should take about 20 minutes, most of it waiting for email.

FYI, there is a first draft of a user manual here. It was written by Claude, which appears to be much worse at writing instructions for humans than it is at writing code. I haven’t even looked at it carefully, feel free to take a look at some point, or just ignore it.

1. Install through TestFlight

1. Install the TestFlight app from the App Store if you do not have it. (TestFlight is Apple’s platform for doing this stuff).

2. Open the invitation email from TestFlight on your iPhone and tap View in TestFlight, then Accept, then Install. If you were invited by a public link instead, open the link on the phone.

3. Handbill appears on your home screen like any app. Updates arrive through TestFlight too: it tells you when a new build is up, and you tap Update there.

4. TestFlight's own "Send Beta Feedback" works, but the better route is inside Handbill: Settings → Send feedback to developer for your words, and Settings → Send log to developer when something went wrong. Both go from your own account and both let you attach screenshots. The log contains no message text and no addresses.

Handbill is beta software. Expect something to look odd, and tell us when it does.

2. Pick and set up your email account
(the most annoying part probably)

Handbill needs a mail account it can read and send from, using an app password, and it holds full access to that mailbox. A few things about the email account:

  • For testing, use a spare account, not your main one. This is new software, and I can’t guarantee that it won’t delete something it shouldn’t or screw something up with your main account. If you ignore this, that’s on you.

  • If you have a spare gmail account you don’t use much and isn’t important to you, that would be ideal. Spare iCloud, Yahoo or AOL should work too… Yahoo and AOL work only on accounts old enough to be allowed an app password. Outlook, Hotmail, Proton and Tuta cannot be used at all, and the app says why if you pick them. If you run your own email server, you’re a giant nerd and you should be able to figure out how to log in to SMTP/IMAP.

  • You should be able to create a spare gmail account and use that, unless you have already created too many for gmail to stomach.

If you need/want to create a new gmail account - skip this step if you already have a spare account you can use. Otherwise it takes about five minutes and needs a phone that can receive a text.

1. In a browser, on the phone or a computer, go to accounts.google.com/signup. It works whether or not you are signed in to another Google account. Choose "For my personal use".

2. Give a first name. Any name will do: the name your friends see comes from Handbill, not from here. Google also asks for a birthday and gender.

3. Choose your Gmail address. Google suggests a couple; tap "Create your own Gmail address" to type one instead. Your friends will see this address on every post and welcome from you, so something like yourname.handbill@gmail.com beats a random string.

4. Make a password and write it down. This is the Google password for signing in to the account. It is not the one you give Handbill; that is the app password, which comes next.

5. Phone number. Google usually asks for one and sends a code by text. Give it: you need a number for 2-Step Verification in a moment anyway. If Google refuses the number as already used too many times, that is Google's cap on accounts per phone number, and the only fix is another number.

6. Recovery email. Optional, and worth giving: your main address is how you get back in if you forget the new password.

7. Review the details, read and agree to the terms, and you land in the new, empty inbox. Stay signed in; the app password is next.

Do not add the account to the iPhone's Mail app. Handbill connects to it on its own, and nothing else needs to.

Getting a Gmail app password (two minutes):

1. Sign in to the account at myaccount.google.com and open Security.

2. Turn on 2-Step Verification if it is off. App passwords do not exist without it.

3. Search the page for App passwords (or go to myaccount.google.com/apppasswords). Create a new entry and name it "Handbill", then tap Create.

4. Copy the sixteen letters. The spaces do not matter. Google never shows it again; if you lose it, make another.

This will be the password you give Handbill, never your normal Google password. And no, there wasn’t really a good way to automate this I could find. Let me know if you have any actionable ideas on this.

If you want to use iCloud, yahoo, AOL, or “Other Account” (IMAP/SMTP), the app should give you analogous instructions for finding an app password when you try adding them.

3. First run

1. Connect to your email account.
- Open Handbill.
- Choose Gmail (or your provider).
- Enter the email address you will be using with Handbill
- Paste or type the app password you found in section 2 (above)
- Tap Connect.

The app will make two folders in a mailbox for your email account: “handbill-content” and “handbill-meta”. The app should now show an empty feed.

If Connect fails, check the provider before the password. The provider you choose decides which mail server Handbill talks to, so a Yahoo or iCloud address entered under Gmail is refused by Google no matter how correct the password is, and the error will blame the password. Once the provider matches the address, the next suspect is the password itself: it must be an app password made for Handbill, never your normal sign-in password.

2. Fill in the following about yourself (these can all be changed later using the Me and Filters tabs):
- your name
- the welcome sentence sent to each new friend (there is a default; make it yours)
- the topics you post about
- the topics you want to see from others

3. Choose a passphrase. The app asks for this and creates your encryption (PGP) keys. The passphrase protects your keys where they are stored (in a box at your email server). Write the passphrase down and store somewhere safe. Nobody can recover it for you. (If you installed an earlier build and skipped the key, the app asks at every launch until you make one.)

4. Add friends

Remember, Handbill can communicate in two modes… with friends who already have Handbill installed on their end (“App Friends”), or using regular email with people who don’t have it installed (“Email Friends”).

Everything goes through the Friends tab, and both kinds of friend are added the same way: tap Add new email, enter the email address and a name for them, tap Add. That sends them one email, in your welcome sentence, asking whether they want your posts, with Yes and No thanks buttons. Nothing is posted to anyone until they tap Yes, and the Friends tab shows "waiting" beside them until then.


Add an “Email Friend”

Add one or two people who are happy to get real email from you and know it is a test. Tell them in person to expect a welcome and to tap Yes in it. What they get from then on:

- Your posts, as readable email with your photos in it, each carrying Like and Comment buttons.

- Their replies should show up in your feed as comments - ask them to try responding or “liking” something from you.

- Ask them if they turned on conversation summaries, and if that is working or annoying or anything. They should only appear attached at the bottom of new content from you.

- Ask them afterwards what they got and whether it made sense in general. That is the most useful thing a tester can report.

Add an “App Friend” (Bruce, for now)

- Add my (Bruce’s) handbill address on the Friends tab exactly as above. It will be the same email address from which you have been receiving emailed Handbill messages from me.

- Once I respond, you should see a card in your feed asking if you want to receive my posts in return. Click “Yes, send them”.

- On your “Friends” tab, you should be able to click on me and set filters for my messages.

- Post something with a photo and a topic.

- I will post something new as well and we can experiment to see if the comments/conversations work properly. This stuff has only been tested by simulators so far.

- It should start using encryption at this point. Please check to make sure that messages from me show a green edge down the left of the card and a padlock icon at the top right.

What to tell us

Anything, but especially:

- what your email-only friend received, and whether they understood it;

- a post or a comment that did not arrive, or arrived twice;

- anything on screen that you had to think about.

If you see a bug or something weird, please take screenshots demonstrating the problem if you can. They can be attached to bug reports and make things much easier.

Use [Settings → Send log to developer] if something failed or if you found a bug. Please attach screenshot(s) if possible.

Use [Settings → Send feedback to developer] for sending other notes.

The version line on the Settings tab, for example 0.1.0 (325, …), tells us exactly which build you are on. That will be included when you send us log files.