Analytics Opt-Out Preference

In Pinch Analytics r69, we've added an optional feature that allows individual users to opt out of statistics collection. It's based on Cocoa's User Defaults system which is familiar to almost all iPhone developers, and it works like this:

• If kEnablePinchMediaStatsCollection is YES, or not set at all, stats are enabled.
• If kEnablePinchMediaStatsCollection is NO, stats are disabled.

Simple!

Again — this feature is completely optional! There is no change to the Beacon API; you don't have to change a single line of Beacon-related code when you upgrade to libPMAnalytics-r69. As always, we strongly recommend that you upgrade to the latest version of Pinch Analytics before you submit your app to the App Store, whether you plan to use new features or not. We always sneak in some minor enhancements and tweaks that don't deserve a mention in the changelog.

There are two ways of implementing preferences on the iPhone. One method is to include a Settings.bundle that defines a list of preferences to be displayed in the Settings app on the device. The other, which seems to be more common, is to keep a preferences view inside the application. Either method will work for our opt-out system, and here's how to make it work:

The Settings.bundle Method

Apple's documentation for the Settings.bundle is useful, but this guide will get you up and running quickly.

Add a Settings.bundle, if necessary

1. In Xcode, choose File -> New File...
2. Under iPhone OS on the left, choose Resource, and then click the Settings Bundle icon
3. Save it with its default name, "Settings.bundle" (we've heard that other names don't work)
4. The file will be created somewhere in your project. Put it wherever you like. (the Resources group seems like a sensible choice)
5. Expand its drop-down, and open Root.plist

Add the opt-out toggle

Technically, all that's actually required to support opt-out is one PreferenceSpecifier:

<dict>
	<key>Type</key>
	<string>PSToggleSwitchSpecifier</string>
	<key>Title</key>
	<string>Send Statistics</string>
	<key>Key</key>
	<string>kEnablePinchMediaStatsCollection</string>
	<key>DefaultValue</key>
	<true/>
</dict>

This is the XML representation of a toggle switch with the label "Anonymous Stats" that defaults to On and uses our key kEnablePinchMediaStatsCollection. Settings.bundle property list files (like Root.plist) are represented in XML by default, so you can open this as text (in XCode, right- or control-click Root.plist and choose Open As -> Source Code File) and edit manually. You'll see an <array> of <dict>s like the snippet above; just paste this wherever you'd like it to appear.

That's not very clear.

While that one toggle is all you need to support opt-out in your app, it's confusing — users will wonder what "Send Statistics" means. The next example shows how to add a header and a brief explanation. We strongly encourage developers to tailor this language to their apps. For instance, if you enable Beacon's CoreLocation reporting, it's worth mentioning that you're interested in knowing where your users are so you can make decisions about which languages to support.

The following snippet will look like this in the Settings app:

<dict>
    <key>Type</key>
    <string>PSGroupSpecifier</string>
    <key>Title</key>
    <string>Anonymous Usage Statistics</string>
</dict>
<dict>
    <key>Type</key>
    <string>PSToggleSwitchSpecifier</string>
    <key>Title</key>
    <string>Send Statistics</string>
    <key>Key</key>
    <string>kEnablePinchMediaStatsCollection</string>
    <key>DefaultValue</key>
    <true/>
</dict>
<dict>
    <key>Type</key>
    <string>PSGroupSpecifier</string>
    <key>Title</key>
    <string>
        This anonymous information is used by this application&apos;s developers
        to help understand their applications and make them better.
    </string>
</dict>

Here's what this looks like in XCode's PList editor, with the crucial toggle switch highlighted:

See Apple's documentation for the Settings.bundle for more information about what you can do with the Settings app on the iPhone.

The "Custom Preferences View" Method

If you use your own view to control preferences from inside your app, all you need to know is that we respect the boolean user default with the key "kEnablePinchMediaStatsCollection." Before using it, you should set the default value of the key to be enabled, either by setting it in the user's default preferences plist (if you use one) or adding the following code:

- (void)viewDidLoad {
    NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
    
    // set the default state to be enabled. registerDefaults: will not overwrite a preference
    // that has been set by the user, so it is safe to do this each time the app starts.
    [defaults registerDefaults:[NSDictionary dictionaryWithObjectsAndKeys:
        [NSNumber numberWithBool:YES], kEnablePinchMediaStatsCollection, nil
    ]];
    
    // set the UISwitch to the proper position
    statsSwitch.on = [defaults boolForKey:kEnablePinchMediaStatsCollection];
}

Internal Implementation Specifics

Opt-out is a simple concept, but we want to be transparent about how we've implemented it.

In brief: Every call you make to Beacon checks whether stats are disabled; if so, the method returns immediately. If stats are disabled when you call endBeacon, we delete all Pinch Media files and (of course) don't send anything to our servers.

Here are some use cases to help you understand the behavior:

• If the user disables analytics while the app is running (and analytics were previously enabled), all Beacon calls (sub-beacons, FBConnect sessions, etc) will return immediately. When endBeacon is called, the Beacon SQLite database is deleted (which removes all cached data that has not yet been sent to our servers) and nothing is transmitted.
• On the other hand, if analytics are enabled when the app starts, but the user disables analytics and continues to use the app, and then re-enables it before quitting, data will still be transmitted. No analytics data (ie sub-beacons, location updates, etc.) will be recorded while analytics is disabled, however.
• If analytics have previously been disabled, but are enabled while the app is running, data will be collected for all subsequent runs (in other words, we don't start recording session data whenever the analytics opt-out is disabled since that would produce incomplete and inaccurate data).