Creating your First iOS App (User-to-User chat)

This guide walks you through how to build a new iOS Mobile app that will enable in-app user-to-user chat between platforms.

Create a new App

  1. Open Magnet Studio.

  2. Click the Create App button in the navigation bar.

  3. Enter a name for your app. Click Save to create your new app.

    Home-new

  4. Download MagnetMax.plist (from the Settings screen) and include in it in your new Xcode project.

  5. Add the Magnet Message library to your Xcode project with CocoaPods. See the CocoaPods Get Started guide for more information.

    1
    2
    3
    4
    5
    6
    7
    8
    source 'https://github.com/CocoaPods/Specs.git'
    source 'https://github.com/magnetsystems/Specs.git'
    platform :ios, '8.0'
    use_frameworks!
    pod 'MagnetMax', '~> 2.7'
    }
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  6. Initialize the Magnet Message SDK.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    // In your AppDelegate
    @import MagnetMax;
    @implementation AppDelegate
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Configure MagnetMax
    NSString *configurationFile = [[NSBundle mainBundle] pathForResource:@"MagnetMax" ofType:@"plist"];
    id <MMConfiguration> configuration = [[MMPropertyListConfiguration alloc] initWithContentsOfFile:configurationFile];
    [MagnetMax configure:configuration];
    // Your code ...
    return YES;
    }
    @end
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  7. Register yourself as a Magnet Message User.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    MMUser *user = [[MMUser alloc] init];
    user.firstName = @"Jane";
    user.lastName = @"Doe";
    user.email = @"jane.doe@company.com";
    user.userName = @"jane.doe";//user.email;
    user.password = @"password";
    [user register:^(MMUser *user) {
    NSLog(@"user = %@", user);
    } failure:^(NSError *error) {
    NSLog(@"error = %@", error.localizedDescription);
    }];
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  8. Log in with the user created in the previous step, and initialize Magnet Message.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    NSString *username = @"jane.doe";
    NSString *password = @"password";
    NSURLCredential *credential = [NSURLCredential credentialWithUser:username password:password persistence:NSURLCredentialPersistenceNone];
    [MMUser login:credential success:^{
    NSLog(@"currentUser = %@", [MMUser currentUser]);
    } failure:^(NSError *error) {
    NSLog(@"Login error = %@", error.localizedDescription);
    }];
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  9. Get the current user after logging in.

    1
    MMUser *currentUser = [MMUser currentUser];
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  10. Get Users. For example, to find users with known user names, use the code example below.

    1
    2
    3
    4
    5
    [MMUser usersWithUserNames:@[@"jane.doe",@"john.doe"] success:^(NSArray *users) {
    // do something
    } failure:^(NSError *error) {
    }];
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  11. Create a chat channel with recipients. NOTE: In most cases the chat channel should be prviate. Only channel owners can invite people into the chat.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    // MMUser *johnDoe = ...;
    // MMUser *janeSmith = ...;
    NSSet <MMUser *> *recipients = [NSSet setWithArray:@[johnDoe, janeSmith]];
    __block MMXChannel *myChatChannel;
    [MMXChannel createWithName:name summary:summary isPublic:NO publishPermissions:MMXPublishPermissionsSubscribers subscribers:recipients success:^(MMXChannel * _Nonnull channel) {
    myChatChannel = channel;
    } failure:^(NSError * _Nonnull error) {
    }];
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  12. Send the message.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    NSDictionary *content = @{@"foo": @"bar"};
    // Build the message
    MMXMessage *message = [MMXMessage messageToChannel:myChatChannel messageContent:content];
    [myChatChannel publishMessage:message success:^{
    // do something
    } failure:^(NSError * _Nonnull error) {
    // do something
    }];
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  13. Register for a notification to receive the message and chat invitation. </a>

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    - (void)viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];
    // Indicate that you are ready to receive messages now!
    [MMX start];
    [[NSNotificationCenter defaultCenter] addObserver:self
    selector:@selector(didReceiveMessage:)
    name:MMXDidReceiveMessageNotification object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self
    selector:@selector(didReceiveChannelInvite:)
    name:MMXDidReceiveChannelInviteNotification object:nil];
    }
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  14. Once MMX has started, you can continue to implement your notification code as shown below:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    - (void)didReceiveMessage:(NSNotification *)notification {
    MMXMessage *message = notification.userInfo[MMXMessageKey];
    // Do something with the message
    }
    - (void)didReceiveChannelInvite:(NSNotification *)notification {
    MMXInvite *invite = notification.userInfo[MMXInviteKey];
    // Do something with the invite
    }
    - (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:(BOOL)animated];
    [[NSNotificationCenter defaultCenter] removeObserver:self];
    }
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  15. Invite more users into the chat using the same invitation process used in the Private Discussion Group.

  16. Get the chat history.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    int limit = 10;
    int offset = 0;
    NSDate *now = [NSDate date];
    NSDate *anHourAgo = [now dateByAddingTimeInterval:-(60 * 60)];
    BOOL ascending = NO;
    [myChatChannel messagesBetweenStartDate:anHourAgo endDate:now limit:limit offset:offset ascending:ascending success:^(int totalCount, NSArray<MMXMessage *> * _Nonnull messages) {
    } failure:^(NSError * _Nonnull error) {
    }];
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  17. Get all chat recipients.

    1
    2
    3
    4
    5
    6
    MMXChannel *myChatChannel = ...;
    [myChatChannel subscribersWithLimit:100 offset:0 success:^(int totalCount, NSArray<MMUser *> * _Nonnull subscribers) {
    } failure:^(NSError * _Nonnull error) {
    }];
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  18. Set up disconnection handling. A user can be redirected to the login screen on disconnect with the code below.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    - (void)viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(didDisconnect:) name:MMUserDidReceiveAuthenticationChallengeNotification object:nil];
    }
    - (void)didDisconnect:(NSNotification *)notification {
    // Indicate that you are not ready to receive messages now!
    [MMX stop];
    // Redirect to the login screen
    //When the user logs back in you will need to reinitialize MMX
    }
    - (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:(BOOL)animated];
    [[NSNotificationCenter defaultCenter] removeObserver:self];
    }
    XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Advanced: Wakeup Users

We provide the capability to add a mechanism that notifies the app there is a pending incoming message to registerd users who are not currently online. This capability leverages the platform's push technology—in the case of iOS: APNS.

NOTE: Configuring APNS for your application is a prerequisite. Please see our detailed documentation on how to setup APNS for your application.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// In your AppDelegate
@import MagnetMax;
@implementation AppDelegate
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
//In the case of a silent notification use the following code to see if it is a wakeup notification
if ([MMXRemoteNotification isWakeupRemoteNotification:userInfo]) {
//Send local notification to the user or connect via MMXClient
completionHandler(UIBackgroundFetchResultNewData);
} else if ([MMXRemoteNotification isMMXRemoteNotification:userInfo]) {
NSLog(@"userInfo = %@",userInfo);
//Check if the message is designed to wake up the client
[MMXRemoteNotification acknowledgeRemoteNotification:userInfo completion:^(BOOL success) {
completionHandler(UIBackgroundFetchResultNewData);
}];
} else {
completionHandler(UIBackgroundFetchResultNoData);
}
}
@end
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Next Steps

See how to send and receive Rich Messages in your app.