Preferences, feature flags, and privacy

Preference Center

The presentation APIs below are available on the current develop branches and are intended for the next Android, iOS, and Flutter releases.

Preference Centers are authored and published in the console from subscription lists. A center is a projection over those lists: it does not own a second copy of subscription state. Use the ready-made UI for a complete screen, or observe the same snapshot to build a custom experience.

Ready-made UI

Engage.preferenceCenter.display()
 
Engage.preferenceCenter.display(
    options = PreferenceCenterDisplayOptions(
        key = "marketing",
        localeLanguageTag = "fr-FR",
    ),
)

Navigator.of(context).push(
  MaterialPageRoute(
    builder: (_) => Scaffold(
      appBar: AppBar(title: const Text('Communication preferences')),
      body: const SafeArea(
        top: false,
        child: EngagePreferenceCenter(centerKey: 'marketing'),
      ),
    ),
  ),
);

Engage.preferenceCenter.display()
Engage.preferenceCenter.display("marketing")
 
let controller = Engage.preferenceCenter.makeViewController(
    "marketing",
    materialTheme: .system
)
navigationController?.pushViewController(controller, animated: true)

On Android, display opens the SDK Activity. PreferenceCenterDisplayOptions selects a center, can override the locale, and accepts a PreferenceCenterMaterialTheme when the host needs explicit Material color roles.

On iOS, display presents a ready-made UIKit controller. Use makeViewController when the host wants to push or embed that controller itself. PreferenceCenterMaterialTheme.system follows the current system appearance and can be replaced with explicit semantic colors.

The Flutter widget deliberately creates no route, Scaffold, app bar, or navigation behavior. The host owns that chrome. It inherits the surrounding Material 3 Theme and locale, and renders an explicit unavailable state when no published center matches the requested key.

Flutter can also ask the native bridge to present the Android or iOS ready-made UI:

await Engage.preferenceCenter.display(
  key: 'marketing',
  theme: EngageMaterialTheme.of(context),
);

Headless UI

Observe a center when the product needs a fully custom presentation:

Engage.preferenceCenter.center("mobile-notifications").collect { snapshot ->
    customPreferences.render(snapshot)
}

Engage.preferenceCenter.center('mobile-notifications').listen((snapshot) {
  customPreferences.render(snapshot);
});

for await snapshot in Engage.preferenceCenter.center("mobile-notifications").updates {
    customPreferences.render(snapshot)
}

The observable initially returns null when no cached definition exists, then updates after synchronization. A missing, unpublished, or inaccessible center is an unavailable state, not an empty set of choices.

Write the user’s choice through the subscription editor represented by each item:

For a custom UI, keep controls bound to the SDK snapshot and send edits through these APIs. The SDK applies the change optimistically, persists it, places the mutation in its durable outbox, and reconciles it with the server. See Audience data for complete mutation examples.

Preference Center choices are separate from OS notification authorization and Engage privacy state. A user can express a subscription preference without granting push permission, and privacy opt-out still governs whether normal synchronization is allowed.

Feature flags

Always supply a safe default. The default is returned when the flag is unavailable, inactive, incompatible, or not eligible.

Android and iOS evaluate synchronously from the local snapshot. Flutter crosses a platform channel, so getters return Future<T> even though the native lookup itself does not wait for network:

val checkoutV2 = Engage.flags.getBoolean(
    key = "checkout_v2",
    default = false,
)
 
val resultLimit = Engage.flags.getNumber(
    key = "search.result_limit",
    default = 20.0,
)

final checkoutV2 = await Engage.flags.getBoolean(
  'checkout_v2',
  defaultValue: false,
);
 
final configuration = await Engage.flags.getJson<CheckoutConfiguration>(
  'checkout_configuration',
  defaultValue: CheckoutConfiguration.defaultValue,
  encode: (value) => value.toJson(),
  decode: CheckoutConfiguration.fromJson,
);

let checkoutV2 = Engage.flags.getBoolean(
    "checkout_v2",
    default: false
)
 
let resultLimit = Engage.flags.getNumber(
    "search.result_limit",
    default: 20.0
)

The SDK owns deterministic allocation, snapshot persistence, revision activation, and exposure deduplication.

Runtime feature controls

Disable a closed SDK capability when the application or consent model requires it:

Engage.sdkFeatures.edit {
    disable(SdkFeature.ANALYTICS)
    disable(SdkFeature.IN_APP)
}

await Engage.sdkFeatures.edit((features) {
  features.enable(SdkFeature.push);
  features.disable(SdkFeature.analytics);
});

try await Engage.sdkFeatures.edit {
    $0.disable(.analytics)
    $0.disable(.inApp)
}

Feature state is durable and observable.

Privacy

Engage.privacy.optOut()
Engage.privacy.optIn()
Engage.privacy.optOutAndWipe()

await Engage.privacy.optOut();
await Engage.privacy.optIn();
await Engage.privacy.optOutAndWipe();

try await Engage.privacy.optOut()
try await Engage.privacy.optIn()
try await Engage.privacy.optOutAndWipe()

• optOut() stops normal synchronization and collection according to runtime policy while retaining recoverable local state.
• optIn() resumes permitted behavior.
• optOutAndWipe() is for an explicit erasure flow. It clears local Engage state and queues remote revocation where required.

Do not call wipe as a logout shortcut. Identity transition and privacy erasure are different operations.