Upgrading from Pre-XDK Versions

The following upgrade instructions should help for developers upgrading from SDKs and UI Libraries Layer has shipped prior to the Layer XDK.

Update the podfile

  • make sure you have the latest version of CocoaPods installed in your development environment.
  • change the Atlas pod to LayerXDK/UI (the LayerXDK/UI pod will make sure to pull the right version of the Layer Messaging framework): from
    pod 'Atlas'
    pod 'LayerXDK/UI'

Key differences between Atlas and the XDK UI components

Atlas used the standard MVC (model-view-controller) design pattern for its UI components, whereas the XDK UI components use the MVP (model-view-presenter) design pattern.

If your app is based on Atlas-Messenger example project

We recommend looking at the iOS-XDK-Messenger repo on github, it’s analogous to Atlas-Messenger. The structure of the new XDK-Messenger stayed the same. There’s:

  • LYRMAppDelegate replaces ATLMAppDelegate (the app delegate)
  • LYRMLayerController replaces ATLMLayerController (implements LYRClientDelegate and handles its notifications)
  • LYRMAuthenticationProvider replaces ATLMAuthenticationProvider (in charge of the authentication process)
  • LYRMApplicationViewController replaces ATLMApplicationViewController (a top-level UI state machine)
  • LYRMRegistrationViewController replaces ATLMRegistrationViewController (the default login/registration form)
  • LYRMConversationListViewController replaces ATLMConversationListViewController (the view controller in charge of list of conversations)
  • LYRMStartConversationViewController replaces ATLMStartConversationViewController (the view controller with a blank conversation and participant picker)
  • LYRMConversationViewController replaces ATLMConversationViewController (the view controller showing the conversation content)
  • LYRMConversationDetailViewController replaces ATLMConversationDetailViewController (the view controller showing info about the conversation)
  • LYRMSettingsViewController replaces ATLMSettingsViewController (the view controller showing info about the session)

Most view controllers’ initializers have been replaced with a different argument, that takes in an LYRUIConfiguration instance, instead of ATLMLayerController.

The ATLMConversationListViewController implementation changes

Atlas Messenger codebase would use the ATLMConversationListViewController which would inherit an Atlas based view controller called ATLConversationListViewController that’d be in charge of controlling and displaying a list of conversations. With the XDK codebase, it’s suggested that a standard UIViewController is used as the super class of the conversation list view controller, and the view is just replaced or added to the view hierarchy:

- (void)loadView {
    self.view = [[LYRUIConversationListView alloc] initWithConfiguration:self.layerUIConfiguration];

The Atlas Messenger version used to handle the following ATLConversationListViewControllerDelegate callbacks:

  • conversationListViewController:didDeleteConversation:deletionMode:, which would just log a message that a conversation was successfully deleted, but is now handled by the view itself;
  • conversationListViewController:didFailDeletingConversation:deletionMode:error:, which would also just log a message with an error stating the deletion failure, but is now handled by the view itself;
  • conversationListViewController:didSearchForText:completion:, which would allow the user to search trough messages based on participant’s name, but with the XDK UI, the search feature has been removed due to inability to search text through messages;
  • conversationListViewController:avatarItemForConversation:, which would return any identity from the set of participants of a conversation, but is now handled by the view itself;
  • conversationListViewController:titleForConversation:, which would return a shortened list of names of the participants, but is now handled by the view itself;
  • conversationListViewController:didSelectConversation:, which would push the ATLMConversationViewController onto the navigation stack is now replaced by the LYRConversationListView's itemSelected block method:
    // A helper function that casts the self.view to (LYRUIConversationListView *).
    - (LYRUIConversationListView *)conversationListView {
        if ([self.view isKindOfClass:[LYRUIConversationListView class]]) {
            return (LYRUIConversationListView *)self.view;
        return nil;
    // Setup the conversation selection handler.
    - (void)viewDidLoad {
        [super viewDidLoad];    
        __weak __typeof(self) weakSelf = self;
        self.conversationListView.itemSelected = ^(LYRConversation *conversation) {
            [weakSelf presentControllerWithConversation:conversation];

The ATLMConversationViewController implementation changes

As with the conversation list view controller and with other view controllers, there’s no class inheritance from the XDK UI components, using a standard UIViewController is suggested and then simply set or add the LYRUIConversationView to the view hierarchy:

- (void)loadView {
    self.view = [[LYRUIConversationView alloc] initWithConfiguration:self.layerUIConfiguration];

The Atlas Messenger’s ATLMConversationViewController used to handle two scenarios, showing an existing conversation or starting a new blank conversation. For the later scenario, the ATLMConversationViewController had to present a mutable address bar (ATLAddressBarViewController) which allowed users to add participants (either through the auto-complete entry or via participants picker). In contrast, the XDK UI messenger’s LYRMConversationViewController presents a LYRMStartConversationViewController whenever it’s been initialized with conversation argument being nil.

Also note that the initializer has changed in the LYRMConversationViewController, it takes an LYRConversation and the LYRUIConfiguration instance, instead of ATLMLayerController. If the conversation argument is omitted the controller will present the LYRMStartConversationViewController, which takes care of creating a new conversation with a new set of participants.

The ATLMConversationViewController used to handle a lot of delegates which are not present anymore in the XDK UI codebase:

The ATLConversationViewControllerDelegate callbacks:
  • conversationViewController:didSendMessage: which is now handled by the LYRUIMessageSender owned by the LYRUIConversationView;
  • conversationViewController:didFailSendingMessage:error: which used to present an alert view, and is now handled in LYRUIMessageSender class (which also presents an alert view);
  • conversationViewController:didSelectMessage: which would handle the tap action and present the appropriate view controller for the corresponding mime-type, now handled by the message action handler (see protocol LYRUIActionHandling);
The ATLConversationViewControllerDataSource callbacks:
  • conversationViewController:participantForIdentity: which used to transform an LYRIdentity to an object conforming to id<ATLParticipant>;
  • conversationViewController:attributedStringForDisplayOfDate: which was in a role of a date formatter for the timestamp string, and now replaced by the LYRUIMessageListTimeFormatter;
  • conversationViewController:attributedStringForDisplayOfRecipientStatus: which was used to compose the delivery status string of the last message, and now replaced by the LYRUIMessageRecipientStatusFormatter;

Note: The XDK UI Messenger doesn’t include an address bar, when creating new conversations the view controller will automatically present a participant picker. But here are some of the delegates the Atlas Messenger used to handle the callbacks from ATLAddressBarViewController which are irrelevant for the XDK UI:

The ATLAddressBarControllerDelegate callbacks:
  • addressBarViewController:didTapAddContactsButton: which was invoked when the plus button was tapped in the address bar, presenting a single-select participant picker view controller;
  • addressBarViewController:searchForParticipantsMatchingText:completion: which was used by the address bar when adding participants via the auto-complete entry;
  • addressBarViewControllerDidSelectWhileDisabled: which was invoked when tapped while disabled causing a conversation details view controller to be presented;
The ATLParticipantTableViewControllerDelegate callbacks:
  • participantTableViewController:didSelectParticipant: which would handle the participant picker selection by adding it into the address bar;
  • participantTableViewController:didSearchWithString:completion: which would filter the results set in the participant picker;
The ATLMConversationDetailViewControllerDelegate callbacks:
  • conversationDetailViewControllerDidSelectShareLocation: which used to send the user’s current location as a message;
  • conversationDetailViewController:didChangeConversation which would change the ATLMConversationViewController's conversation (in case a participant was added or removed and an existing conversation with the same set of participants already existed);
Core API Reference Changelog