Alchemer Mobile iOS SDK Interaction Customization

Alchemer Mobile (ApptentiveKit) on iOS has four levels of customization available for the interactions it presents:

1. Theme setting
2. UIAppearance overrides
3. UIKit extensions
4. Overriding InteractionPresenter

Themes

For apps where cross-platform consistency is less of a concern, or where a developer wants to apply their own visual customization, the theme property on the Apptentive instance can be set to .none (this should be completed before calling the register(with:completion:) method):

Apptentive.shared.theme = .none

By default, ApptentiveKit adopts a cross-platform theme for Surveys and Message Center that includes dark blue navigation bars with white text, and hides most of the default UITableView decorations. The colors of other interface elements mostly use system defaults, and system fonts are used throughout. This correspondes to a the theme property being set to .apptentive.

Internally, these themes use a combination of the next two customization options: UIAppearance and the Apptentive UIKit extensions (found in UIKit+Apptentive.swift).

UIApperance

Some aspects of the Alchemer Mobile (ApptentiveKit) interactions can be customized using familiar UIAppearance properties. The properties that the Alchemer Mobile (ApptentiveKit) theme customizes via UIAppearance overrides include segmented controls, navigation bars, toolbars, bar button items, and table views.

The customizable Alchemer Mobile (ApptentiveKit) interactions are all contained in a subclass of UINavigationController called ApptentiveNavigationController, which can be used to scope appearance changes to only apply to Alchemer Mobile (ApptentiveKit) customizable interactions:

UITableView.appearance(whenContainedInInstancesOf: [ApptentiveNavigationController.self]).backgroundColor = myBackgroundColor

ApptentiveNavigationController also has a static property to determine the status bar style:

Alchemer Mobile-Specific Appearance Settings

For customizing dialog-style interactions (Prompts and the Love Dialog), the SDK uses UIAppearance properties.

DialogView Appearance Settings

The dialog appearance can be customized by accessing the appearance proxy for the DialogView class. To target properties in either Love Dialog or Prompts (formerly Notes) interactions, use the EnjoymentDialogViewController and/or TextModalViewController as appearance containers, respectively.

To match the standard UIAlertController in its alert style, the DialogView uses a UIVisualEffectView for its background. This means that the backgroundColor property will appear as an underlay behind the visual effect view. To avoid this, you can turn off the effect as follows:

UIVisualEffectView.appearance(whenContainedInInstancesOf: [DialogView.self]).effect = .none

DialogButton Appearance Settings

The DialogButton class draws the buttons in the dialog. By default, the buttons cover the entire corner (for Love Dialog) or row (for Prompts) of the dialog

If you are adding a border or corner radius to dialog buttons, we recommend hiding the separators and setting the inset and spacing on the DialogView to create some visual space between multiple buttons and between the buttons and the edges of the dialog.

You can separately style the “yes” and “no” buttons in the Love Dialog (by using the YesButton and NoButton classes) and the dismiss and other buttons in Prompts (by using the DismissButton and InteractionButton classes).

UIKit Extensions

Alchemer Mobile (ApptentiveKit) extends a number of UIKit classes with Alchemer Mobile-specific static properties that can be used to change the appearance of nearly every interface element. For example, to change the color of a text input (UITextField or UITextView) border, you would add the following code to your app:

UIColor.apptentiveTextInputBorder = .darkGray

Illustrations of UIKit Extension Properties

The images below illustrate what each property affects in Message Center and Surveys. Colors, Fonts and Images are indicated by the small icon next to the property name.

List of UIKit Extension Properties

The following is a list of UIKit classes for which Alchemer Mobile (ApptentiveKit) has style properties, what each property is used for, and its value using both the .none and .apptentive theme.

While the theme property must be set before calling register(with:completion), you can change the values below at any time. However if you change them while an interaction is visible on screen, it may behave unpredictably.

UITableView.Style

UIModalPresentationStyle

UIBarButtonItem

UIButton

UIImage

Property	Description	Default	Apptentive Theme
apptentiveMessageAttachmentButton	The image for the button used to attach an image or file to a message	paperclip.circle.fill SF Symbol	Same
apptentiveMessageSendButton	The image for the button used to send a message	paperplane.circle.fill SF Symbol	Same
apptentiveSentMessageBubble	The background image for a sent message	Resizable, using 9 point top and left insets, and 18 point bottom and right insets, rendered as template	Same
apptentiveReceivedMessageBubble	The background image for a received message	Resizable, using 9 point top and right insets, and 18 point bottom and left insets, rendered as template	Same
apptentiveAttachmentPlaceholder	The placeholder image for a yet-to-be-downloaded attachment	Resizable, using 14 point top and right insets, and 4 point bottom and left insets	Same
apptentiveAttachmentRemoveButton	The image for a button used to remove an attachment from the draft message	minus.circle.fill SF Symbol	Same
apptentiveHeaderLogo	An image that can replace the navigation bar’s title view in Surveys. Recommended size is 200 × 44 points.	None	None
apptentiveRadioButton	The accessory image for an unselected answer to a single-select survey question	circle SF Symbol	Same
apptentiveCheckbox	The accessory image for an unselected answer to a multi-select survey question	square SF Symbol	Same
apptentiveRadioButtonSelected	The accessory image for the selected answer to a single-select survey question	smallcircle.fill.circle.fill SF Symbol	Same
apptentiveCheckboxSelected	The accessory image for a selected answer to a multi-select survey question	checkmark.square.fill SF Symbol	Same

UIColor

UIFont

Overriding InteractionPresenter

As a final customization option (short of forking ApptentiveKit itself), your app can subclass ApptentiveKit’s InteractionPresenter class and set theinteractionPresenter property on the Alchemer Mobile (ApptentiveKit) instance to an instance of your subclass.

Apptentive.shared.interactionPresenter = MyInteractionPresenter()

This can be useful, for example, to customize the Love Dialog or Prompts interactions, since the UIAlertController class used by Alchemer Mobile (ApptentiveKit) is not customizable.

Your InteractionPresenter subclass can override one or more of the following methods, which will be passed a view model with the properties and methods necessary to implement the interaction:

• presentEnjoymentDialog(with:) (for Love Dialog interactions)
• presentMessageCenter(with:)
• presentSurvey(with:)
• presentTextModal(with:) (for Prompts interactions)

Your override method should create a suitable view controller (using the view model to configure it) and present it, for example by calling the presentViewController(_:completion:) method.

If you use a different method of displaying your interaction view controller, be sure to override dismissPresentedViewController(animated:) to handle the programmatic dismissal of your view controller.

Because of their complexity, for Message Center and Survey interactions we strongly recommend starting with a copy of the code in the “Default UI” group (“List UI” for Surveys) under each interaction’s group in the Alchemer Mobile (ApptentiveKit) Xcode project.

While we will make a strong effort to maintain API compatibility with current view models, you should expect the view model API to potentially have breaking changes when Alchemer Mobile (ApptentiveKit) minor version number changes.