Can I Get Your Address?

Mac OS X’s centralized Address Book empowers developers to offer users features that go above and beyond what would be possible in the absence of such a resource. For example, an envelope-printing utility on Mac OS X doesn’t need to demand that you painstakingly type in the name and address of your friend before mailing a letter, you can search for them and automatically select from a list of matching addresses. It’s magic, it just works, and it makes a Mac a Mac.

Many other examples of Mac software just working are also based in accessing the Address Book, but instead of needing access to the whole thing, it’s just the “Me” card that is of interest. This is very useful for example if a map app wants to offer you easy directions home. A very common use case for accessing the “Me” card is when an application has good reason to pre-populate personal fields in an inquiry form of some kind: for example, a feedback or crash reporter dialog. In this case, putting the user’s email address in the field for them saves a step and prevents a possible typo.

Starting in Mountain Lion 10.8, Apple has dramatically increased security protections around the contents of users’ Address Book data. On the face of it, this is a good thing, as it protects against applications that either surreptitiously or stupidly access and upload the contents of address books to web servers without permission. The flip side is that fairly innocuous requests for the “Me” card are now met with a foreboding dialog:

Yikes! What is Red Sweater Crash Reporter and why does it want my contacts!? Sounds fishy. In fact, all it wants is the “Me” card, but there’s no way for it to let the user know this. Or is there?

Thanks to Cabel Sasser’s tweet today, I learned that there is in fact a way to express intent, albeit with a very crude mechanism. You can’t specify intent on a call-by-call basis, but you can publish in your application’s Info.plist a single string that will be conveyed to the user as an explanation for your need of Address Book data. The key is NSContactsUsageDescription, and it’s very lightly documented in Apple’s Info Property List Key Reference:

NSContactsUsageDescription (String – OS X). This key contains the localizable description of the reason why an app is requesting access to the user’s contacts information in the Address Book database.

It would be far preferable if there were an API mechanism through which an app could request specific content from the Address Book, along with a dynamically stated explanation. But this is better than nothing. Tweaking my crash reporter’s Info.plist, I end up with this:

Incidentally, if you’re a developer trying to add this to your own app, you’ll find it frustrating that the nature of this dialog provides you only one chance to get the terminology right. As soon as you click “OK” or “Don’t Allow”, that’s the last time you’ll ever see this dialog. Unless you happen to know about this magic little command line incantation (thanks to Jim Correia for reminding me):

% tccutil reset AddressBook

That clears out all permissions for your Address Book access, causing the panel to appear again the next time any app, including yours, tries to access contacts.