Preference Center

Implement a preference center on your website.

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.

A preference center consists of these interfaces:

PreferenceCenterManager — Provides an interface for fetching preference center definitions.
PreferenceCenter — A data structure that defines a preference center in a format that is convenient for rendering in your toolkit of choice.
Channel — Can be opted in or out of subscription lists.
Contact — Can be opted in or out of scoped subscription lists.
SubscriptionListManager — An interface for managing a channel’s subscription list membership.
ScopedSubscriptionListManager — An interface for managing a contact’s scoped subscription list membership.

When implementing a preference center, you will fetch the preference center’s definition, render it in your chosen toolkit, and listen for the end user’s interactions with the various subscription list items to manage the channel’s or contact’s opting in or out of a list.

Preference centers are referred to by id, and you may have multiple preference centers within your app.

The await channel.subscriptions.list() returns an array of subscription list ids type: string[].
The await contact.subscriptions.list() returns a ScopedSubscriptionListIdentifier of type {[key: string]: Scope[]}, where the key is the subscription list id, e.g., {listId1: ['app', 'web'], listId2: ['email']}.

Web SDK Preference Center Examples

Note

How you implement a preference center will depend heavily on your UI toolkit of choice. The following examples purposefully ignore those details.

Example for a Channel preference center implementation

const sdk = await UA

const id = "my_preference_center" // refers to the ID you created in the Airship Dashboard
// retrieve the preference center by id
const preferenceCenterDefinition = await sdk.components.preferenceCenters.get(id)

// render your preference center component; here we assume some class
// `PreferenceUi` which takes a definition and returns an event
// emitter which emits membership changes based on end-user interactions, but
// this will be up to your implementation.
const preferenceUi = new PreferenceUi(preferenceCenterDefinition)

preferenceUi.addEventListener("list_change", async (e) => {
  const {
    operation, // assume string "subscribe" or "unsubscribe"
    listId, // the id of the list
  } = e.detail

  // now that you have received an event, use the Airship SDK to alter the
  // channels list membership
  const editor = await sdk.channel.subscriptions.edit()

  // subscribe or unsubscribe, depending on the operation
  if (operation === "subscribe") {
    editor.subscribe(listId)
  } else if (operation === "unsubscribe") {
    editor.unsubscribe(listId)
  }

  // apply the changes
  await editor.apply()
})

Example for a Contact preference center implementation

const sdk = await UA

const id = "my_cross_channel_preference_center" // refers to the ID you created in the Airship Dashboard
// retrieve the preference center by id
const preferenceCenterDefinition = await sdk.components.preferenceCenters.get(id)

// render your preference center component; here we assume some class
// `PreferenceUi` which takes a definition and returns an event
// emitter which emits membership changes based on end-user interactions, but
// this will be up to your implementation.
const preferenceUi = new PreferenceUi(preferenceCenterDefinition)

preferenceUi.addEventListener("list_change", async (e) => {
  const {
    operation, // assume string "subscribe" or "unsubscribe"
    listId, // the id of the list
    scope, // the scope to which you are subscribing or unsubscribing (e.g. "web")
  } = e.detail

  // If this is not a scoped (i.e. contact-level) operation, 
  // it cannot be handled by the contact subscription manager
  if (!scope) return

  // now that you have received an event, use the Airship SDK to alter the
  // contact list membership
  const contact = await sdk.contact
  const editor = await contact.subscriptions.edit()

  // subscribe or unsubscribe, depending on the operation
  if (operation === "subscribe") {
    editor.subscribe(listId, scope)
  } else if (operation === "unsubscribe") {
    editor.unsubscribe(listId, scope)
  }

  // apply the changes
  await editor.apply()
})

Feedback

Was this page helpful?