Hyphenate Docs

Start Chatting with Hyphenate!

Welcome to the Hyphenate docs portal. Here you'll find comprehensive guides and technical documentation to help you integrate Hyphenate In-App Chat.

Get Started

Basic Operations

Initialize the SDK

  1. Import the SDK header file.
#import <Hyphenate/Hyphenate.h>

OR

Lite version without voice & video calling feature

#import <HyphenateLite/HyphenateLite.h>
  1. Implementation in AppDelegate.m

AppDelegate.m

#import <Hyphenate/EMSDKFull.h>

/** Hyphenate configuration constants **/
static NSString *const kHyphenateAppKey = @"hyphenate#hyphenatedemo";                    // API Key
static NSString *const kHyphenatePushServiceDevelopment = @"DevelopmentCertificate";     // push service certificate name for development
static NSString *const kHyphenatePushServiceProduction = @"ProductionCertificate";       // push service certificate name for production 

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
{
    EMOptions *options = [EMOptions optionsWithAppkey:kHyphenateAppKey];
    options.apnsCertName = kHyphenatePushServiceProduction;    
    [[EMClient sharedClient] initializeSDKWithOptions:options];
}

- (void)applicationDidEnterBackground:(UIApplication *)application
{
    [[EMClient sharedClient] applicationDidEnterBackground:application];
}

- (void)applicationWillEnterForeground:(UIApplication *)application 
{
    [[EMClient sharedClient] applicationWillEnterForeground:application];
}    

- (void)registerNotifications
{
    [self unregisterNotifications];
    [[EMClient sharedClient] addDelegate:self];                  // connection
    [[EMClient sharedClient].chatManager addDelegate:self];      // messaging handling  
    [[EMClient sharedClient].contactManager addDelegate:self];   // contact management  
    [[EMClient sharedClient].groupManager addDelegate:self];     // (optional) group management  
    [[EMClient sharedClient].roomManager addDelegate:self];      // (optional) chat room management  
}

- (void)unregisterNotifications
{
    [[EMClient sharedClient] removeDelegate:self];
    [[EMClient sharedClient].chatManager removeDelegate:self];
    [[EMClient sharedClient].contactManager removeDelegate:self];
    [[EMClient sharedClient].groupManager removeDelegate:self];
    [[EMClient sharedClient].roomManager removeDelegate:self];
}

Notes

EMOptions

Here're few init option examples listed in EMOption.h for specific actions,

Enforce HTTPS

If HTTPS is not enforced, then you might encounter an error like App Transport Security has blocked a cleartext HTTP (http://) resource load since it is insecure. Temporary exceptions can be configured via your app's Info.plist file..

@property (nonatomic, assign) BOOL usingHttpsOnly;

Login automatically

@property (nonatomic, assign) BOOL isAutoLogin;

Keep the group message if a user leaves the group?

@property (nonatomic, assign) BOOL isDeleteMessagesWhenExitGroup;

Keep the chat room message if a user leaves the chat room?

@property (nonatomic, assign) BOOL isDeleteMessagesWhenExitChatRoom;

example

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    EMOptions *options = [EMOptions optionsWithAppkey:@"hyphenatedemo#hyphenatedemo"];
    [options setUsingHttpsOnly:YES];
    [options setIsDeleteMessagesWhenExitGroup: NO];
    [[EMClient sharedClient] initializeSDKWithOptions:options];
}

Register a New Account

We recommend you register a new Hyphenate account via REST API, but you can also do it from the client SDK.

EMError *error = [[EMClient sharedClient] registerWithUsername:@"apple" password:@"000000"];
if (error==nil) {
    // registered successfully
}

Login

EMError *error = [[EMClient sharedClient] loginWithUsername:@"username" password:@"password"];
if (!error) {
    // login successfully!
}

Auto login

Auto login is to log the user into the Hyphenate server automatically without triggering the login method again after a successful login. The attribute of auto login is set to YES by default in the SDK. You can adjust the auto login by changing the setting's successful login.

EMError *error = [[EMClient sharedClient] loginWithUsername:@"username" password:@"password"];
if (!error) {
   // Setting for auto login
   [[EMClient sharedClient].options setIsAutoLogin:YES];   // or NO, to disable auto login
}

isAutoLogin getter

BOOL isAutoLogin = [EMClient sharedClient].options.isAutoLogin;

Auto login will be canceled under the following situations:

  • The logout method is called and executed from the previous session
  • The user credential or password is changed that causes an auto-login failure
  • The user account is deleted from the server
  • The user logs into another device and the system forces the user to logout on the current device, since it currently only supports login on a single mobile device.

Login Error delegate

- (void) autoLoginDidCompleteWithError:(EMError *)error

example

@interface someClass() <EMClientDelegate>

- (void)someInitMethod {
    [[EMClient sharedClient] addDelegate:self delegateQueue:nil];
}

- (void) autoLoginDidCompleteWithError:(EMError *)error {
    // handle auto login error
}

Logout

There are two types of logout scenarios,

Active logout

Active logout is when you call the logout method explicitly.

[[EMClient sharedClient] logout:YES];

Passive logout

Passive logout is triggered if a user is forced to logout by the developer via REST API or console, or exceeded the login session limitation, etc.

User logged into another device and caused a logout on the current device

- (void)userAccountDidLoginFromOtherDevice;

User account is deleted from the server

- (void)userAccountDidRemoveFromServer;

Connection Status Changed

The SDK will attempt to reconnect automatically if the device connection dropped due to a network issue.

- (void) connectionStateDidChange:(EMConnectionState)aConnectionState;
typedef enum {
    EMConnectionConnected = 0,  
    EMConnectionDisconnected, 
} EMConnectionState;

Next step: Messages

Basic Operations


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.