.. Teamchat documentation master file, created by sphinx-quickstart on Wed Sep 23 16:53:44 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Teamchat SDK’s documentation! ======================================== .. toctree:: :maxdepth: 2 ================== Introduction ================== Teamchat SDK is a framework for iOS, that helps any third party application to easily integrate with Teamchat messaging service. The SDK provides UI elements to display the groups for a user, and also the chat timeline for any selected group. It also supports few UI configurations such as setting different icons, colors, etc. The following sections describe various features of the SDK, such as authentication, getting groups, displaying groups, and chat timeline of a group. ================== Interface ================== --------------- Initialization --------------- SDK exposes an object called Teamchat. This object provides an object oriented interface to the SDK. You can initialize by supplying an Application ID provided by Teamchat. This method should be called in *application:didFinishLaunchingWithOptions:* method of AppDelegate. The following code demonstrates how to initiate Teamchat:: +(void)initializeWithAppID:(NSString*)appID withCompletionHanlder:(^(BOOL, NSError*))handler ============= ============================== ============================================== Parameter Type Description ============= ============================== ============================================== appID String This is an alpha numeric string provided by the Teamchat Server handler ^(BOOL success,NSError* error) Initialization is successful, the ‘success’ will be TRUE. NSError will convey if any problem was encountered during initialization. ============= ============================== ============================================== **Example**:: static const NSString * const APP_ID = @“XXZ” [Teamchat initializeWithAppID:APP_ID withCompletionHanlder: ^(BOOL success, NSError* error) { if( success == TRUE ) { //Success } else { //Failure while initializing the Teamchat object. } } -------------------------------- Setting up remote notifications -------------------------------- Device token should be set, to enable push notifications. Use the following API to setup remote notifications and this API should be called in *application:didRegisterForRemoteNotificationsWithDeviceToken:* method of AppDelegate. The following code demonstrates how to setup remote notifications:: + (void)setRemoteNotificationsDeviceToken:(NSString*)deviceToken ============= ========= =========================================== Parameter Type Description ============= ========= =========================================== deviceToken String A token that identifies the device to APNs. ============= ========= =========================================== **Example**:: [Teamchat setRemoteNotificationsDeviceToken:]; The push notification certificate name can be set using the following API:: + (void)setPNEnvironmentID:(NSString*)pnEnvironmentID; =============== ========= =================================== Parameter Type Description =============== ========= =================================== pnEnvironmentID String Push notification certificate name. =============== ========= =================================== **Example**:: [Teamchat setPNEnvironmentID:]; ------ Login ------ You can login to Teamchat in 2 ways. **************************************************************** By setting Authentication code, Email ID, UserID and host URL **************************************************************** +++++++++++++++++++++++++++ Setting Authentication code +++++++++++++++++++++++++++ Before any other API on Teamchat can be called, you need to pass it the authentication code that you have got from a Teamchat authentication service. You can set the authentication code:: +(void)setAuthenticationCode:(NSString*)authCode ============= ========= ==================================================== Parameter Type Description ============= ========= ==================================================== authCode String The authentication code provided by Teamchat service ============= ========= ==================================================== **Example**:: static const NSString* const authCode = @”AUTH_CODE” [Teamchat setAuthenticationCode: authCode] +++++++++++++++++++ Setting User Email +++++++++++++++++++ Before any other API on Teamchat can be called, you need to pass it the user email that you have got from a Teamchat authentication service. You can set the email:: +(void)setUserEmailID:(NSString*)emailID ============= ========= ================ Parameter Type Description ============= ========= ================ emailID String Email ID ============= ========= ================ **Example**:: [Teamchat setUserEmailID: emailID] ++++++++++++++++ Setting User ID ++++++++++++++++ Before any other API on Teamchat can be called, you need to pass it the user ID that you have got from a Teamchat authentication service. You can set the user id:: +(void)setUserID:(NSString*)userID ============= ========= ================ Parameter Type** Description ============= ========= ================ userID String The user ID ============= ========= ================ **Example**:: static const NSString * const userID = @”UserID” [Teamchat setUserID: userID] ++++++++++++++++ Setting Host URL ++++++++++++++++ You can set the host URL using the following API:: + (void)setHostURL:(NSString *)hostURL; **Example**:: [Teamchat setHostURL:@“”] **************** Teamchat login. **************** Use the following API to get login view controller. :: +(UIViewController*)teamchatLoginViewController:(^(BOOL, NSError*,NSString*))handler ============= ========================== =============================================== Parameter Type Description ============= ========================== =============================================== handler ^(BOOL success, NSError* If login is successful, ‘success’ will be true. error, NSString* errMsg) NSError will convey any error if occurred during login. ============= ========================== =============================================== **If you set an email using ‘[Teamchat setUserEmailID: emailID]’, then the login page will have pre-filled email field without editing support.** **Example**:: UIViewController* controller = [Teamchat teamchatLoginViewController: ^(BOOL success, NSError* error, NSString *errMsg) { if( success == TRUE ) { //Success } else { //Failure while logging into Teamchat. } } Use this controller to present wherever it is appropriate in your application. .. image:: images/Login.png ---------------------- Initializing Teamchat ---------------------- After all the above mentioned, required parameters are set, or after successful login, this method should be called before any group creation or ViewController creation APIs on Teamchat can be called. :: +(void)initWithCompletionHandler:(^(BOOL, NSError*,NSString*))handler ============= ========================== ============================================== Parameter Type Description ============= ========================== ============================================== handler ^(BOOL success, NSError* Initialization is successfull, ‘success’ will error, NSString* errMsg) be true. NSError will convey any any problem was encountered during initialization. ============= ========================== ============================================== **Example**:: [Teamchat iniWithCompletionHanlder: ^(BOOL success, NSError* error, NSString *errMsg) { if( success == TRUE ) { //Success } else { //Failure while initializing Teamchat. } }]; While this asynchronous API is in progress, your app might want to show some progress indicator to indicate Teamchat is being initialized. -------------------------- Setting UI configurations -------------------------- You can set navigation bar title, navigation bar tint color, and the chat browser icon in chat window as well as the icon to indicate rich media in the chat window. If you do not call any of these APIs, then the default values will be used. :: +(void)setNavigationTitle:(NSString*)title; +(void)setNavigationTitleColor:(UIColor*)color; +(void)setMediaIcon:(UIImage*)iconImage; +(void)setChatletIcon:(UIImage*)iconImage; +(void)setTableViewSeparatorColor:(UIColor*)seperatorColor; **Example**:: [Teamchat setNavigationTitle:@"My title"]; [Teamchat setNavigationTitleColor:[UIColor greenColor]]; [Teamchat setMediaIcon:[UIImage imageNamed:@"mediaIcon"]]; [Teamchat setChatletIcon:[UIImage imageNamed:@"chatletIcon"]]; [Teamchat setTableViewSeparatorColor:[UIColor blueColor]]; You can customise navigation bar’s left bar button items using the following API:: + (void)setNavigationItemLeftBarButtonItems:(NSArray *)leftBarButtonItems; ================== ======= ================================================ Parameter Type Description ================== ======= ================================================ leftBarButtonItems NSArray An array of bar button items that should be set as left bar button items of navigation item. ================== ======= ================================================ **Example**:: UIBarButtonItem *leftBarButtonItem = [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemAdd target:self action:@selector(addButtonHandler:)]; [Teamchat setNavigationItemLeftBarButtonItems:@[leftBarButtonItem]]; --------------------- Getting groups/rooms --------------------- You can get list of groups using the rooms API. :: +(NSArray*)teamchatGroups:(NSError **)error ============= ========= ==================== Parameter Type Description ============= ========= ==================== error NSError** An error object, passed by reference. ============= ========= ==================== **Example**:: NSError *error = [NSError new]; NSArray *groups =[Teamchat teamchatGroups:&error]; If no error, groups will be an array containing TeamchatGroup objects. The **TeamchatGroup** object is a light weight object and has the following simple properties: ======== ======================================== groupID The identifier of the group as NSString name Name of the room ======== ======================================== --------------------------------------- Creating the chat group using group ID --------------------------------------- You can get a specific group using this API. :: +(TeamchatGroup *)teamchatGroupWithID:(NSString*)groupID error:(NSError**) error ============= ========== ========================== Parameter Type Description ============= ========== ========================== groupID String Group ID error NSError** An error object, passed by reference. ============= ========== ========================== **Example**:: NSError *error = [NSError new]; TeamchatGroup *group = [Teamchat teamchatGroupWithID: error:&error]; If no error, a valid group will be returned. ----------------------------- Showing the chat groups list ----------------------------- Use the following API to get a view controller:: +(UIViewController*)teamchatGroupsViewController; **Example**:: UIViewController* controller = [Teamchat teamchatGroupsViewController]; Use this controller to present wherever it is appropriate in your application. .. image:: images/ChatRooms.png ----------------------------------- Showing the chat window for a room ----------------------------------- Use this API, to load the chat window for a given Teamchat group object. :: +(UIViewController*)createTeamchatWindowViewControllerWithGroup:(TeamchatGroup*) group **Example**:: UIViewController* controller = [TeamChat createTeamchatWindowViewControllerWithGroup:]; Use this controller to present wherever it is appropriate in your application. .. image:: images/ChatWindow.png -------------------- Getting User profile -------------------- Use the following API to get the user profile view controller:: + (UIViewController *)userProfileViewController; **Example**:: UIViewController* controller = [Teamchat userProfileViewController]; Use this controller to present wherever it is appropriate in your application. .. image:: images/UserProfile.png --------------------- Getting Settings View --------------------- Use the following API to get the Teamchat settings view:: + (UIViewController *)settingsViewController; **Example**:: UIViewController* controller = [Teamchat settingsViewController]; Use this controller to present wherever it is appropriate in your application. .. image:: images/Settings.png ------------------------------------- Getting Public groups View controller ------------------------------------- Use the following API to get the Public groups view:: + (UIViewController *)publicGroupsViewController:(^(TeamchatGroup *selectedGroup))handler; ========== ================================ ====================== Parameter Type Description ========== ================================ ====================== handler ^(TeamchatGroup * selectedGroup) The public group that was selected ========== ================================ ====================== Use this controller to present wherever it is appropriate in your application. .. image:: images/PublicGroups.png --------------------------------------- Getting user logged out view controller --------------------------------------- User session is invalidated when the user is deleted from organisation. SessionState will be set to **TCSessionStateInvalidatedOnUserDelete** and you can get notified when the user is deleted from organisation by observing to **TCActiveSessionIsInvalidatedNotification** as follows:: [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleInvalidSession:) name:TCActiveSessionIsInvalidatedNotification object:nil]; Add this method in the class that should observe for session invalid notification. When the session is invalidated, you can show logged out view controller. Use the following API to get logged out view:: + (UIViewController *)userLoggedOutViewController:(void (^)(void))userLoggedOutCompletionHandler; ========== ================================ ======================================== Parameter Type Description ========== ================================ ======================================== handler (void (^)(void)) The block to execute after user logs in to Teamchat again. This block has no return value and takes no parameters. ========== ================================ ======================================== **Example**:: UIViewController* controller = [Teamchat userLoggedOutViewController:^{ // User has logged in to Teamchat }]; Present this controller when active session is invalidated. .. image:: images/LoggedOut.png ----------------------------------- Resetting active Teamchat session ----------------------------------- Use this API to reset Teamchat session before creating a new session:: - (void)resetTeamchatSession **Example**:: [Teamchat resetTeamchatSession]; ----------------------- Checking session state ----------------------- Teamchat session states are defined by **TCSessionState** enum and the state could be any one of the enum values which are as follows 1. TCSessionStateInactive - Teamchat session is inactive 2. TCSessionStateLoggedIn - User has logged in to Teamchat 3. TCSessionStateActive - Session is active after initial set up 4. TCSessionStateInvalidatedOnUserDelete - Session is invalidated when user is deleted from organisation Use this API to check Teamchat session state:: + (NSUInteger)sessionState; **Example**:: TCSessionState sessionState = [Teamchat sessionState]; ----------------------------------- Setting options to display contacts ----------------------------------- The different types of contacts that are supported by Teamchat are: 1. TCShowShowLocalAddressBookContacts - Lists the contacts from phone’s address book. 2. TCShowShowServerAdressBookContacts - List the contacts from Teamchat server in users organisation. 3. TCShowShowCustomAdressBookContacts - List the custom contacts from app contact provider as per TCCustomAddressBookContactProvider. The **TCCustomAddressBookContact** object is a light weight object and has the following simple properties: =========== ======================= profileName Contact display name email Contact email phone Contact phone number =========== ======================= **TCCustomAddressBookContactProvider** is a protocol which provides a method that should return an array of **TCCustomAddressBookContact** objects. The protocol method is as follows:: - (NSArray*)customAddressBookContacts This method should be implemented in the class that conforms to TCCustomAddressBookContactProvider protocol and customAddressBookContactProvider can be set using the following API:: +(void)setCustomAddressBookContactProvider:(id)customAddressBookContactProvider; ================================= ================ =================== Parameter Type Description ================================= ================ =================== customAddressBookContactProvider id The class that ContactProvider protocol ================================= ================ =================== **Example**:: [Teamchat setCustomAddressBookContactProvider:]; You can choose the type of contacts that should be listed in contacts list using the following API:: + (void)setShowContactOptions:(NSUInteger)showContactOptions =================== =========== ============================================ Parameter Type Description =================== =========== ============================================ showContactOptions NSUInteger You can pass an option or a combination of options, combined using ‘|’ operator. =================== =========== ============================================ **Example**:: [Teamchat setShowContactOptions:TCShowShowLocalAddressBookContacts | TCShowShowServerAdressBookContacts | TCShowShowCustomAdressBookContacts]; ----------------------------------- Inviting your contacts to Teamchat ----------------------------------- You can invite contacts to Teamchat by creating an array of TeamchatInviteContact objects and passing it to the following API:: + (void)inviteContactsToTeamchat:(NSArray *)inviteContactsArray compeltionHandler:(^(BOOL, NSError*,NSString*))handler ==================== =============== ========================================== Parameter Type Description ==================== =============== ========================================== inviteContactsArray NSArray An array of TeamchatInviteContact objects handler ^(BOOL success, If invite is successful, the ‘success’ NSError* error) will be TRUE. NSError will convey if any problem was encountered during invite. ==================== =============== ========================================== **Example**: Create **TeamchatInviteContact** objects as follows:: TeamchatInviteContact *invitee1 = [TeamchatInviteContact new]; invitee1.name = @"John"; invitee1.emailID = @"john.bell@gmail.com"; TeamchatInviteContact *invitee2 = [TeamchatInviteContact new]; invitee2.name = @"Kate"; invitee2.emailID = @"kate.appleseed@gmail.com"; Create an array of TeamchatInviteContact objects. :: NSArray *inviteContactsArray = @[invitee1, invitee2]; Note: **+(void)initWithCompletionHandler:(^(BOOL, NSError*,NSString*))handler** method should be called before calling Invite API. :: [Teamchat initWithCompletionHandler:^(BOOL success, NSError* error, NSString *errMsg) { if (success) { [Teamchat inviteContactsToTeamchat:inviteContactsArray compeltionHandler:^(BOOL success, NSError* error, NSString *errMsg) { if (success) { // Invite was successful } }]; } }]; While this asynchronous API is in progress, your app might want to show some progress indicator to indicate Teamchat Invite is in progress. ------------------ Getting user info ------------------ You can use **TeamchatUser** class to query about user info like profileName, userEmail, organisation and userID, profileImageURL. 1. Use the following API to get user’s profile name:: +(NSString *)profileName; This method returns user’s profile name as String. **Example**:: NSString *userName = [TeamchatUser profileName]; 2. Use the following API to get user’s email:: +(NSString*)userEmail; This method returns the user’s emailID as String. **Example**:: NSString *email = [TeamchatUser userEmail]; 3. Use the following API to get user’s organisation:: + (NSString *)organization; This method returns the user’s organisation as String. **Example**:: NSString *organization = [TeamchatUser organization]; 4. Use the following API to get user’s ID:: + (NSString *)userID; This method returns the user’s ID as String. **Example**:: NSString *userID = [TeamchatUser userID]; 5. Use the following API to get user’s profile image URL:: + (NSString *)profileImageURL; This method returns the user’s profile image URL as String. **Example**:: NSString *imageURL = [TeamchatUser profileImageURL]; ------------------------- Tracking Teamchat events ------------------------- You can track Teamchat events using **TeamchatEventTracker** class and **TeamchatEventTrackerDelegate** protocol. TeamchatEventTrackerDelegate is a protocol which provides a method that provides information about the event name and its properties. The protocol method is as follows:: - (void)eventTracked:(NSString *)eventName withProperties:(NSDictionary *)properties; ========== ============ ============================================ Parameter Type Description ========== ============ ============================================ eventName NSString Name of a particular event which can be tracked. properties NSDictionary A dictionary whose keys are the properties associated with the event and values as the value of the the property. ========== ============ ============================================ This method should be implemented in the class that conforms to **TeamchatEventTrackerDelegate** protocol and **eventTrackerDelegate** can be set using the following API:: -(void)setEventTrackerDelegate:(id)eventTrackerDelegate; ==================== ================ ============================ Parameter Type Description ==================== ================ ============================ eventTrackerDelegate id TeamchatEventTrackerDelegate protocol. ==================== ================ ============================ **Example**:: [TeamchatEventTrackerDelegate sharedEventTrackerInstance] setEventTrackerDelegate:]; ------------------------------------ Getting the count of unread messages ------------------------------------ Use the following API to get the count of unread messages that were received:: + (NSInteger)numberOfUnreadMessages; **Example**:: NSInteger unreadMsgCount = [Teamchat numberOfUnreadMessages]; ------------- Enabling Logs ------------- Use the following API to show the Teamchat logs every time:: + (void)setLoggingEnabled:(BOOL)loggingEnabled; **Example**:: [Teamchat setLoggingEnabled:YES]; ===================================== Integrating the SDK with your iOS app ===================================== 1. Add **TeamchatSDK.framework** to your project. 2. Add **TeamchatSDK.framework** to ‘Embedded Binaries’ field under ‘General’ tab of your project target. 3. Add **TeamchatSDK.framework/TeamChat.momd** folder to your project using the “Create folder references” option as shown below. .. image:: images/SetUp.png Now project navigator will look like: .. image:: images/ProjectNavigator.png Now you need to initialize the Teamchat object with appID in the AppDelegate method *application:didFinishLaunchingWithOptions:*. :: - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [Teamchat initializeWithAppID: withCompletionHanlder:^(BOOL success, NSError *error) { if (!success) { [[[UIAlertView alloc] initWithTitle:@"Failed" message:[error localizedDescription] delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil, nil] show]; } }]; return YES; } Enable remote notifications by setting deviceID in the AppDelegate method *application:didRegisterForRemoteNotificationsWithDeviceToken:* :: - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { [Teamchat setRemoteNotificationsDeviceToken:deviceTokenString]; } You can login to Teamchat in two ways: 1. Set Authentication code, emailID and userID. :: [Teamchat setAuthenticationCode:@""]; [Teamchat setUserEmailID:@""]; [Teamchat setUserID:@""]; 2. Use Teamchat login view controller. :: UIViewController *loginViewController = [Teamchat teamchatLoginViewController:^(BOOL success, NSError *error, NSString *errMsg) { if (success) { // Successful login } else { // Login error } }]; if (loginViewController) { [self presentViewController:loginViewController animated:YES completion:nil]; } If you want to configure UI of the Teamchat screens, you can set them as follows:: [Teamchat setNavigationTitle:@"Chats"]; [Teamchat setNavigationTitleColor:[UIColor greenColor]]; [Teamchat setTableViewSeparatorColor:[UIColor redColor]]; To get the chat groups list controller, you can use the following API:: [Teamchat initWithCompletionHandler:^(BOOL success, NSError *error, NSString *errMsg) { if (success) { UIViewController *teamchatGroupsViewController = [Teamchat TeamchatGroupsViewController]; if (teamchatGroupsViewController) { [self presentViewController:teamchatGroupsViewController animated:YES completion:nil]; } else { // Error } } else { // Error } }]; Note: **+(void)initWithCompletionHandler:(^(BOOL, NSError*,NSString*))handler** method should be called before calling groups list API. To get the chat window controller, you can use the following API:: [Teamchat initWithCompletionHandler:^(BOOL success, NSError *error, NSString *errMsg) { if (success) { NSError *error = [NSError new]; TeamchatGroup *group = [Teamchat teamchatGroupWithID:@"" error:&error]; UIViewController *groupViewController = [Teamchat createTeamchatWindowViewControllerWithGroup:group]; if (groupViewController) { [self presentViewController:groupViewController animated:YES completion:nil]; } else { // Error } } else { // Error } }]; Note: **+(void)initWithCompletionHandler:(^(BOOL, NSError*,NSString*))handler** method should be called before calling chat window controller API. To get user profile view controller, you can use the following API:: [Teamchat initWithCompletionHandler:^(BOOL success, NSError *error, NSString *errMsg) { if (success) { UIViewController *userProfileViewController = [Teamchat userProfileViewController]; if (userProfileViewController) { [self presentViewController:userProfileViewController animated:YES completion:nil]; } else { // Error } } else { // Error } }]; Note: **+(void)initWithCompletionHandler:(^(BOOL, NSError*,NSString*))handler** method should be called before calling chat window controller API. To get the public groups view controller, you can use the following API:: [Teamchat initWithCompletionHandler:^(BOOL success, NSError *error, NSString *errMsg) { if (success) { UIViewController *publicGroupsViewController = [Teamchat publicGroupsViewController:^(TeamchatGroup *selectedGroup) { if (selectedGroup) { // Push the selected group's chat window. UIViewController *chatWindowViewController = [Teamchat createTeamchatWindowViewControllerWithGroup:selectedGroup]; if (chatWindowViewController) { [self.navigationController pushViewController:chatWindowViewController animated:YES]; } else { // Error } } }]; if (publicGroupsViewController) { [self presentViewController:publicGroupsViewController animated:YES completion:nil]; } } else { // Error } }]; Note: **+(void)initWithCompletionHandler:(^(BOOL, NSError*,NSString*))handler** method should be called before calling public group API. To get Teamchat settings view controller, you can use the following API:: [Teamchat initWithCompletionHandler:^(BOOL success, NSError *error, NSString *errMsg) { if (success) { UIViewController *settingsViewController = [Teamchat settingsViewController]; if (settingsViewController) { [self presentViewController:settingsViewController animated:YES completion:nil]; } else { // Error } } else { // Error } }]; Note: **+(void)initWithCompletionHandler:(^(BOOL, NSError*,NSString*))handler** method should be called before calling public group API.