Customize the iOS Preference Center

One of Urban Airship’s most powerful tools is the ability to segment your audience with tags. Providing users with a set of notification preferences is a great way of creating these segments. Urban Airship provides an additional framework that allows you to easily create and style a Preference Center.

Download and installation instructions can be found here. Preference Center supports iOS 8 and above.

Basics

Preference Center is designed to take an array of preference tags and display them with a switch to toggle each preference on or off.

UATagPreference is used to create a tag preference. Each preference consists of an internal tag and the corresponding display name:

let worldNewsPref = UATagPreference(tag: "worldNewsPref", displayName: "World News")


The above example will set a standard device tag. You also have the option of using Tag Groups:

let weatherPref = UATagPreference(tag: "weatherPref", displayName: "Weather", tagGroup: "userPreferences")

Remember to use a tag group that has already been created or else Preference Center will not display.


To present the Preference Center modally:

UATagPreferences.start(preferences: [worldNewsPref, weatherPref], title: "News Preferences")

This will display the Preference Center with "News Preferences" as a title, along with default font and color styles.

A Deeper Look

Styling the Preference Center

If you don’t want to use the default Preference Center stylings, you can include your own:

let myStyle = UATagPreferencesStyle()

myStyle.preferenceLabelFont = UIFont(name: "Avenir Next", size: 17)
myStyle.preferenceLabelColor = UIColor(red:0.87, green:0.64, blue:0.23, alpha:1.00)
myStyle.closeButtonColor = UIColor(red:0.44, green:0.40, blue:0.85, alpha:1.00)


If you would like to use a plist file to load your custom style:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>preferenceLabelFont</key>
        <dict>
            <key>fontName</key>
            <string>Helvetica Neue</string>
            <key>fontSize</key>
            <string>17</string>
        </dict>

        <key>preferenceLabelColor</key>
        <string>#4F758F</string>

        <key>closeButtonColor</key>
        <string>#4F758F</string>

    </dict>
</plist>


Set your plist file with:

let myStyle = UATagPreferencesStyle(contentsOfFile: "MyStylePreferences")


A default UATagPreferenceCenterStyle.plist file is included and can be overwritten with custom styles.

Style Properties


  1. closeButtonFont and closeButtonColor
  2. backgroundColor
  3. titleFont and titleColor
  4. preferenceLabelFont and preferenceLabelColor
  5. cellSwitchOnColor
  6. cellSwitchOffTintColor
  7. cellBackgroundColor
  8. cellSeparatorColor
  9. listColor

Displaying the Preference Center

The Preference Center can easily be displayed modally with UATagPreferences.start, however, you may want to integrate this deeper into your app. You can do this by initializing UATagPreferencesViewController directly or by subclassing it.

UATagPreferencesViewController provides three properties:

  • preferences: [UATagPreference]
  • style: UATagPreferencesStyle
  • preferencesTitle: String

UATagPreferencesViewController requires an array of UATagPreference objects in order to display any data. Populate this property with your tag preferences before the view is shown, along with optional style and title properties.

A title should be used to identify the Preference Center. If an empty string is found when displaying the Preference Center modally, it will default to display "Notification Preferences" as the title.

Allowing the Preference Center to be Updated Remotely

The Preference Center can also be saved and updated outside of the app. It’s important to consider whether or not to allow any newer preferences to override your default values. Each call to open the Preference Center has an optional preferSavedPreferences parameter which defaults to true but will ignore saved preferences if set to false:

UATagPreferences.start(preferences: [financePref,
                                     sportsPref,
                                     worldNewsPref,
                                     weatherPref],
                       title: "News Preferences",
                       preferSavedPreferences: false)

when using a UATagPreferences instance:

prefCenter.start(preferSavedPreferences: false)

Handling the Preference Center Through Push Notifications

If you would like send push notifications to update or open the Preference Center, turn this on after calling takeOff in your AppDelegate:

UAirship.takeOff(config)

// create a preference action after takeOff
UATagPreferences.registerAction()


You can also set a default UATagPreferencesStyle to use:

let myStyle = UATagPreferencesStyle()

myStyle.preferenceLabelFont = UIFont(name: "Avenir Next", size: 17)
myStyle.preferenceLabelColor = UIColor(red:0.87, green:0.64, blue:0.23, alpha:1.00)
myStyle.closeButtonColor = UIColor(red:0.44, green:0.40, blue:0.85, alpha:1.00)

UATagPreferences.registerAction(style: myStyle)

Triggering a One-Off Preference Center From a Push Notification

To trigger the Preference Center from a push notification, include the action key "ua_tag_preference_open_action" along with a JSON payload. The same parameters apply as they did when setting up each UATagPreference:

{
	"preferences": [
		{
    		"tag": "sportsPref",
    		"displayName": "Sport",
		    "tagGroup": "userPreferences"
		},
		{
		    "tag": "financePref",
		    "displayName": "Finance",
		    "tagGroup": "userPreferences"
		},
		{
		    "tag": "worldNewsPref",
		    "displayName": "World News",
		    "tagGroup": "userPreferences"
		},
		{
		    "tag": "weatherPref",
		    "displayName": "Weather",
		    "tagGroup": "userPreferences"
		}
	],
	"title": "News Preferences"
}


Full API cURL Example:

curl -X POST "https://go.urbanairship.com/api/push" \
   -H "Content-Type: application/json" \
   -H "Accept: application/vnd.urbanairship+json; version=3;" \
   -H "Authorization: Basic <AUTHORIZATION>" \
   -d '{
    "audience":  "all",
    "device_types" : ["ios"],
    "notification" : {
        "ios": {
          "alert": "Pick your favorite news preferences!"
        },
        "actions": {
			"app_defined": {
				"ua_tag_preference_open_action": {
					"preferences": [
						{
				    		"tag": "sportsPref",
				    		"displayName": "Sport",
						    "tagGroup": "userPreferences"
						},
						{
						    "tag": "financePref",
						    "displayName": "Finance",
						    "tagGroup": "userPreferences"
						},
						{
						    "tag": "worldNewsPref",
						    "displayName": "World News",
						    "tagGroup": "userPreferences"
						},
						{
						    "tag": "weatherPref",
						    "displayName": "Weather",
						    "tagGroup": "userPreferences"
						}
					],
					"title": "News Preferences"
				}
			}
		}
    }
}'

Updating the Preference Center From a Push Notification

You can update all or part of the Preference Center with the same key/value pairs as mentioned above. The only difference is the action key used: ua_tag_preference_save_action. It is recommended that you update through content-available silent pushes to avoid alerting the users unnecessarily.

Tutorials