Getting Started with Preference Center

Preference Center allows users to opt in and out of subscription lists configured via the Airship Dashboard. For more information, see the Preference Center user guide.

Important

Airship Preference Centers are widgets that can be embedded in a page in an app or website. Please verify with your legal team that your full Preference Center page, including any web page for email Preference Centers, is compliant with local privacy regulations.

Displaying a Preference Center

A Preference Center can be displayed in its own window with the provided Airship UI with a single method call. By wiring this method call to a button in your app, you can quickly produce a user-initiated Preference Center with no additional effort.

Displaying a Preference Center

PreferenceCenter.shared().open("my-first-pref-center")

PreferenceCenter.shared().open("my-first-pref-center");

Airship.preferenceCenter.display("my-first-pref-center")

[UAirship.preferenceCenter display:@"my-first-pref-center"];

await Airship.preferenceCenter.display("my-first-pref-center");

Airship.preferenceCenter.display("my-first-pref-center");

Airship.preferenceCenter.display("my-first-pref-center");

await Airship.preferenceCenter.display("my-first-pref-center")

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

Airship.preferenceCenter.display("my-first-pref-center")

// Not supported

Styling the Preference Center

Most developers will want to customize the look and feel to match their app’s existing style and layout. iOS and Android both support customizing through a styling config:

Custom Preference Centers

If the provided preference center is insufficient for your app, you can build your own UI. Currently, preference center is limited to modifying subscription lists. You will need to fetch and edit lists when the user interacts with the preferences. See the subscription list audience section for more info on to interact with subscription lists.

Example preference center implementations are available in our open source repos:

Fetching Preference Center config

When creating a custom preference center, you will need to fetch the config from the Airship SDK. The config might not be available right away on first app start. Screens should use exponential back off if automatically retrying, or provide a UI to the user to retry.

Fetching config

val configPendingResult = PreferenceCenter.shared().getConfig(preferenceCenterId)

PendingResult<PreferenceCenterConfig> configPendingResult = PreferenceCenter.shared().getConfig(preferenceCenterId);

Airship.preferenceCenter.config(preferenceCenterID: preferenceCenterId) { config in
    // Use the preference center config
}

[UAirship.preferenceCenter jsonConfigWithPreferenceCenterID:@"my-first-pref-center"
                                          completionHandler:^(NSData *data, NSError * error) {
    // Use the preference center config
}];

const config = await Airship.preferenceCenter.getConfig(preferenceCenterId);
});

PreferenceCenterConfig preferenceCenterConfig = await Airship.preferenceCenter.getConfig(preferenceCenterId)

Airship.preferenceCenter.getConfig(preferenceCenterId, function(result) {
    //Use the preference center config
});

const config = await Airship.preferenceCenter.getConfig(preferenceCenterId)

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship.NETStandard library. Use native binding methods instead.

Airship.preferenceCenter.getConfig(preferenceCenterConfig function(result) {
    //Use the preference center config
})

// Not supported

Overriding the open behavior

To override the default preference center handling, you need to set a delegate/listener to handle displaying the preference center and to prevent the Airship SDK from displaying the OOTB UI.

Override Preference Center Display

Set the PreferenceCenterOpenListener during the onAirshipReady callback.

PreferenceCenter.shared().openListener =  object : PreferenceCenter.OnOpenListener {
    override fun onOpenPreferenceCenter(preferenceCenterId: String): Boolean {
      // Navigate to custom preference center UI

      // true to prevent default behavior
      // false for default Airship handling
      return true
    }
}

Set the PreferenceCenterOpenListener during the onAirshipReady callback.

PreferenceCenter.shared().setOpenListener(preferenceCenterId -> {
    // Navigate to custom preference center UI

    // true to prevent default behavior
    // false for default Airship handling
    return true;
});

Set the callback after takeOff.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // Call takeOff
    Airship.takeOff(config, launchOptions: launchOptions)

    // Set the Preference Center display callback
    Airship.preferenceCenter.onDisplay = { preferenceCenterID in
        // Navigate to custom preference center UI

        // true to prevent default behavior
        // false for default Airship handling
        return true
    }

    return true
}

Set the callback after takeOff.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Call takeOff
    [UAirship takeOff:config launchOptions:launchOptions];

    // Set the Preference Center display callback
    UAirship.preferenceCenter.onDisplay = ^BOOL(NSString *preferenceCenterID) {
        // Navigate to custom preference center UI

        // YES to prevent default behavior
        // NO for default Airship handling
        return YES;
    };

    return YES;
}

First disable the OOTB UI for the Preference Center ID.

Airship.preferenceCenter.setAutoLaunchDefaultPreferenceCenter(preferenceCenterId, false);

When disabled, the plugin will generate DisplayPreferenceCenter events instead of showing any OOTB UI when the configured preference center is requested to be displayed.

Next, add a listener to handle the display events:

  Airship.addListener(EventType.DisplayPreferenceCenter, (event) => {
    const preferenceCenterId = event.preferenceCenterId;
    // deep link to preferenceCenterId
  });

First disable the OOTB UI for the Preference Center ID.

  Airship.preferenceCenter.setAutoLaunchDefaultPreferenceCenter(preferenceCenterId, false);

When disabled, the plugin will generate display events instead of showing any OOTB UI when the configured preference center is requested to be displayed.

Next, add a listener to handle the display events:

Airship.preferenceCenter.onDisplay
    .listen((event) => debugPrint('Open preference center $event'));

Airship.preferenceCenter.setAutoLaunchDefaultPreferenceCenter(preferenceCenterId, false);
Airship.preferenceCenter.onDisplay((e) => {
  // Navigate to custom preference center UI
  console.log("Open preference center: " + e.preferenceCenterId)
})

await Airship.preferenceCenter.setAutoLaunchDefaultPreferenceCenter(preferenceCenterId, false)
await Airship.preferenceCenter.onDisplay(event => {
    // Navigate to custom preference center UI
    console.log("Open preference center: " + event.preferenceCenterId)
})

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

Airship.preferenceCenter.setUseCustomPreferenceCenter(preferenceCenterId, true)
Airship.addEventListener(Airship.eventOpenPreferenceCenter, function (e) {
    // Navigate to custom preference center UI
    console.log("Open preference center: " + e.preferenceCenterId)
});

// Not supported

Feedback

Was this page helpful?