Dimelo Class Reference
| Inherits from | NSObject |
|---|---|
| Declared in | Dimelo.h |
Overview
Dimelo is a central object to access Dimelo API.
You instantiate Dimelo with an API key, configure the delegate, information about the current user and use it to display a chat view controller.
There are two modes in which API instance can be configured: a secure and less secure one.
Recommended mode: with server-signed authentication token.
``` // Instantiate dimelo with public api key and an optional hostname. Dimelo* dimelo = [[Dimelo sharedInstance] initWithApiKey:@“public api key” hostname:@“api.example.com” delegate:self];
// Assign optional properties to include in authenticated JWT token.
dimelo.userIdentifier = @“optional user account ID”;
dimelo.authenticationInfo = @{
// Retrieve a dictionary to be signed by your server within a JWT token: NSDictionary* dict = dimelo.jwtDictionary;
// Send dict to your server and receive a signed JWT token in response. // Token must be signed with a secret key corresponding to public API key that you use in your app.
// Assign a token to dimelo.jwt so it can be used in all communications. dimelo.jwt = jwtFromServer; ```
Now Dimelo will be able to make requests to Dimelo servers, send and receive chat messages etc.
Unsafe mode which does not require signing a JWT token by your server:
``` // Instantiate dimelo with secret api key and an optional hostname. Dimelo* dimelo = [[Dimelo sharedInstance] initWithApiSecret:@“secret api key” hostname:@“api.example.com” delegate:self];
// Assign optional properties to include in authenticated JWT token.
dimelo.userIdentifier = @“optional user account ID”;
dimelo.authenticationInfo = @{
// Dimelo will compute and sign a valid JWT token automatically each time you change one of the properties above. // All communications will include the signed JWT token as if they were signed by your server. ```
WARNING: Note that anyone who extracts your secret API key will be able to impersonate any user if they know their userIdentifier. User’s data is relatively safe if userIdentifier is not well-known or cannot be easily guessed.
Other Methods
+ disableLibraryAttachment
disable state of individual attachment category or all of them
+ (void)disableLibraryAttachmentDeclared In
Dimelo.h
+ isLibraryAttachmentEnabled
Get state of individual attachment category or all of them
+ (bool)isLibraryAttachmentEnabledDeclared In
Dimelo.h
Setting up an API client
+ sharedInstance
Returns a shared API client initialized with config from DimeloConfig.plist
+ (instancetype)sharedInstanceDiscussion
For correct operation you will have to provide a valid signed JWT token via jwt property.
To do so, fill in userIdentifier, authenticationInfo and send the resulting jwtDictionary to your server.
This is a recommended way to access Dimelo API.
Declared In
Dimelo.h
– initWithApiKey:delegate:
Initializes a new API client with a public API key and a delegate.
- (id)initWithApiKey:(NSString *)apiKey delegate:(id<DimeloDelegate>)delegateParameters
apiKey |
public hex-encoded API key, typically specific to your app. |
|---|---|
delegate |
an instance conforming to |
Discussion
Delegate must not be nil as it is needed to correctly show the chat in various usage scenarios.
For correct operation you will have to provide a valid signed JWT token via jwt property.
To do so, fill in userIdentifier, authenticationInfo and send the resulting jwtDictionary to your server.
This is a recommended way to access Dimelo API.
Declared In
Dimelo.h
– initWithApiKey:hostname:delegate:
- (id)initWithApiKey:(NSString *)apiKey hostname:(NSString *)hostname delegate:(id<DimeloDelegate>)delegateParameters
apiKey |
public hex-encoded API key, typically specific to your app. |
|---|---|
hostname |
a Dimelo API hostname specific to your app. |
delegate |
an instance conforming to |
Discussion
Delegate must not be nil as it is needed to correctly show the chat in various usage scenarios.
For correct operation you will have to provide a valid signed JWT token via jwt property.
To do so, fill in userIdentifier, authenticationInfo and send the resulting jwtDictionary to your server.
This is a recommended way to access Dimelo API.
Declared In
Dimelo.h
– initWithApiSecret:delegate:
Initializes a new API client with a secret API key and a delegate.
- (id)initWithApiSecret:(NSString *)apiSecret delegate:(id<DimeloDelegate>)delegateParameters
apiSecret |
a hex-encoded API secret key, typically specific to your app. |
|---|---|
delegate |
an instance conforming to |
Discussion
Delegate must not be nil as it is needed to correctly show the chat in various usage scenarios.
This mode is less secure than initWithApiKey:delegate: because shared secret is stored inside the app.
Declared In
Dimelo.h
– initWithApiSecret:hostname:delegate:
- (id)initWithApiSecret:(NSString *)apiSecret hostname:(NSString *)hostname delegate:(id<DimeloDelegate>)delegateParameters
apiSecret |
a hex-encoded API secret key, typically specific to your app. |
|---|---|
hostname |
a Dimelo API hostname specific to your app. |
delegate |
an instance conforming to |
Discussion
Delegate must not be nil as it is needed to correctly show the chat in various usage scenarios.
This mode is less secure than initWithApiKey:hostname:delegate: because shared secret is stored inside the app.
Declared In
Dimelo.h
– setApiSecret:
Per-application API secret key, typically specific to your app.
- (void)setApiSecret:(NSString *)apiSecretDiscussion
API secret is always represented in hex format, e.g. @"ab12d1a2a9349797b807589e7e1635cb760d69de3a8241070b1682a1bdbd6d70".
Declared In
Dimelo.h
delegate
Delegate object to present a chat view controller and react to various optional notifications.
@property (nonatomic, weak) id<DimeloDelegate> delegateSee Also
Declared In
Dimelo.h
apiKey
Per-application public API key that identifies all requests to Dimelo.
@property (nonatomic, copy) NSString *apiKeyDiscussion
API Key is always represented in hex format, e.g. @"ab12d1a2a9349797b807589e7e1635cb760d69de3a8241070b1682a1bdbd6d70".
Declared In
Dimelo.h
hostname
Per-application hostname used to connect to Dimelo backend.
@property (nonatomic, copy) NSString *hostnameDeclared In
Dimelo.h
installationIdentifier
Per-installation identifier generated when the component is instantiated for the first time within the app.
@property (nonatomic, readonly) NSString *installationIdentifierDeclared In
Dimelo.h
userIdentifier
Per-user unique identifier used to link messages sent from different devices to a single person.
@property (nonatomic, copy) NSString *userIdentifierDiscussion
User identifier could be an arbitrary string that makes sense in your application: an email, an account number or a UUID.
You can initialize and use Dimelo before user is logged-in, but after he has logged in,
set the userIdentifier to let Dimelo know the real identity of the user.
If userIdentifier is nil, user will be uniquely identified on the server by the installationIdentifier.
Declared In
Dimelo.h
authenticationInfo
Additional fields to be added to the JWT dictionary under “extra” key.
@property (nonatomic, copy) NSDictionary *authenticationInfoDiscussion
You must make sure only PropertyList-compatible items a present inside this dictionary.
Declared In
Dimelo.h
userName
Optional name of the person to be sent to Dimelo.
@property (nonatomic, copy) NSString *userNameDeclared In
Dimelo.h
jwt
Complete serialized JWT token.
@property (nonatomic, copy) NSString *jwtDiscussion
If you use instantiation with public API key and your server signs JWT token, set this property with a JWT provided by your server.
If you instantiate Dimelo with a secret API key, this property is computed automatically.
Declared In
Dimelo.h
jwtDictionary
JWT dictionary to be signed. Computed out of apiKey, installationIdentifier, userIdentifier, authenticationInfo.
@property (nonatomic, readonly) NSDictionary *jwtDictionaryDiscussion
Send this dictionary to your app’s server to sign with a shared secret corresponding to API key.
If you instantiate Dimelo with API secret, this dictionary will be used to compute jwt property automatically.
Declared In
Dimelo.h
messageContextInfo
Arbitrary contextual info attached to a message.
@property (nonatomic, copy) NSDictionary *messageContextInfoDiscussion
Attached only to the first message after a new value was specified.
Example: user selects a category of a problem (“Technical” or “Sales”) and then contacts the support. First message indicates what type of the problem user is talking about.
Declared In
Dimelo.h
Displaying Chat View
– displayChatView
Asks delegate to display the chat view.
- (void)displayChatViewDiscussion
This method is called internally, but it is also available for you to display the chat from a single convenient place.
Declared In
Dimelo.h
– chatViewController
Creates a new instance of a chat view controller.
- (UIViewController *)chatViewControllerReturn Value
A UIViewController containing a chat view.
Discussion
Use standard -presentViewController:animated:completion: and —dismissViewController messages to show/hide it.
You can present it modally or in UITabViewController.
Use transitioningDelegate for custom presentation.
Declared In
Dimelo.h
Remote Notifications
deviceToken
Device token for remote notifications. Optional.
@property (nonatomic, copy) NSData *deviceTokenDiscussion
Override -application:didRegisterForRemoteNotificationsWithDeviceToken: and
set this property to a provided deviceToken.
Declared In
Dimelo.h
developmentAPNS
Flag to tell Dimelo server to send push notifications using development channel.
@property (nonatomic) BOOL developmentAPNSDiscussion
Set this to YES in order to receive notifications on development builds.
By default, Dimelo server will send notifications to production environment and
development builds will not receive such notifications.
Default is NO.
Declared In
Dimelo.h
– consumeReceivedRemoteNotification:
Attempts to process the remote notification.
- (BOOL)consumeReceivedRemoteNotification:(NSDictionary *)dictionaryParameters
dictionary |
a |
|---|
Return Value
YES if notification is consumed by Dimelo and should not be processed by your app.
NO if notification does not belong to Dimelo and should be processed by your app.
Discussion
Returns YES if this notification belongs to this Dimelo instance and user. Otherwise returns NO.
If the app was activated due to this notification, delegate is asked to display the chat.
If the app was active already, it displays the notification on top of the screen. When user taps it, delegate is asked to display the chat.
If it returns YES do not pass the notification data to the rest of your app.
Recommended usage:
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
if ([self.dimelo consumeReceivedRemoteNotification:userInfo]) {
return;
}
// You app's handling of this notification...
}
Declared In
Dimelo.h
Accessing Unread Count
unreadCount
Number of unread messages or other events to which user hasn’t reacted yet.
@property (nonatomic, readonly) NSInteger unreadCountDiscussion
You can display this as a badge on a button that opens the chat.
Default value is 0.
Declared In
Dimelo.h
updateAppBadgeNumber
Whether the app’s icon badge is automatically updated with unreadCount value.
@property (nonatomic) BOOL updateAppBadgeNumberDiscussion
If YES, updates app’s icon badge automatically to reflect unreadCount.
Set it to NO to fully control app’s badge number.
The badge is updated also by push notifications. To avoid Dimelo notifications changing your app’s badge number, disable automatic badge update on the Dimelo administration website.
Default is YES.
Declared In
Dimelo.h
– noteUnreadCountDidChange
Sends notifications to NSNotificationCenter and notifies the delegate about unreadCount change. Does not affect the value itself.
- (void)noteUnreadCountDidChangeDiscussion
This method is called automatically when unreadCount is changed due to new data received from the server.
It may be useful to call it manually when you want to refresh counters after the views are presented without
them having explicit references to Dimelo instance (NSNotification object will store reference to Dimelo instance).
Declared In
Dimelo.h
– fetchUnreadCountWithCompletionHandler:
Fetch unreadCount.
- (void)fetchUnreadCountWithCompletionHandler:(void ( ^ ) ( NSInteger unreadCount , NSError *error ))completionDiscussion
In case of error completion will be called with NSNotFound value and the corresponding error. Completion is called on main thread.
NSErrors of domain DimeloHTTPErrorDomain will mirror the HTTP code from Dimelo backend’s response in their own code property. You may want to handle special HTTP code responses like 429 Too many requests for example.
Declared In
Dimelo.h
Application language
Basic Customization
tintColor
Tint color for aux controls: Close button, Send button, cursor etc.
@property (nonatomic) UIColor *tintColorDeclared In
Dimelo.h
navigationBarTintColor
Bar tint color for navigation bar (sets barTintColor property).
@property (nonatomic) UIColor *navigationBarTintColorDeclared In
Dimelo.h
navigationBarColor
Background color for navigation bar (sets backgroundColor property).
@property (nonatomic) UIColor *navigationBarColorDeclared In
Dimelo.h
title
Title for the chat.
@property (nonatomic, copy) NSString *titleDiscussion
Used only if titleView is nil.
Declared In
Dimelo.h
titleView
Title view for the chat.
@property (nonatomic) UIView *titleViewDiscussion
If not nil, overrides title value.
Declared In
Dimelo.h
backgroundView
Background view of the chat.
@property (nonatomic, readonly) UIView *backgroundViewDiscussion
You may customize its backgroundColor or place arbitrary views inside it.
Declared In
Dimelo.h
messageFont
Font for user and agent messages.
@property (nonatomic) UIFont *messageFontDeclared In
Dimelo.h
systemMessageFont
Font for system messages.
@property (nonatomic) UIFont *systemMessageFontDeclared In
Dimelo.h
userMessageTextColor
Foreground color for user’s message text.
@property (nonatomic) UIColor *userMessageTextColorDeclared In
Dimelo.h
agentMessageTextColor
Foreground color for agent’s message text.
@property (nonatomic) UIColor *agentMessageTextColorDeclared In
Dimelo.h
systemMessageTextColor
Foreground color for system notification message text.
@property (nonatomic) UIColor *systemMessageTextColorDeclared In
Dimelo.h
userMessageBackgroundColor
Background color for user message bubbles.
@property (nonatomic) UIColor *userMessageBackgroundColorDiscussion
This color is applied when userMessageBubbleImage has template rendering mode (see UIImageRenderingMode).
Default image is configured this way.
Declared In
Dimelo.h
agentMessageBackgroundColor
Background color for agent message bubbles.
@property (nonatomic) UIColor *agentMessageBackgroundColorDiscussion
This color is applied when agentMessageBubbleImage has template rendering mode (see UIImageRenderingMode).
Default image is configured this way.
Declared In
Dimelo.h
systemMessageBackgroundColor
Background color for system message bubbles.
@property (nonatomic) UIColor *systemMessageBackgroundColorDiscussion
This color is applied when systemMessageBubbleImage has template rendering mode (see UIImageRenderingMode).
Default image is configured this way.
Declared In
Dimelo.h
dateTextColor
Text color for the date label.
@property (nonatomic) UIColor *dateTextColorDeclared In
Dimelo.h
dateFormatter
Date formatter instance used to format the date label.
@property (nonatomic) NSDateFormatter *dateFormatterDeclared In
Dimelo.h
errorIconColor
Color for the error icon.
@property (nonatomic) UIColor *errorIconColorDeclared In
Dimelo.h
agentNameFont
Font for agent’s name.
@property (nonatomic) UIFont *agentNameFontDeclared In
Dimelo.h
agentNameColor
Text color for agent’s name.
@property (nonatomic) UIColor *agentNameColorDeclared In
Dimelo.h
loadMoreMessagesButtonTextColor
Text color for the button “load more messages”.
@property (nonatomic) UIColor *loadMoreMessagesButtonTextColorDiscussion
If this property is nil (default), this button is colored using tintColor.
Declared In
Dimelo.h
disabledSendButtonColor
Color for the button “send” in the disabled state.
@property (nonatomic) UIColor *disabledSendButtonColorDiscussion
If this property is nil (default), this button is colored into [UIColor grayColor].
Declared In
Dimelo.h
messageFieldFont
Font for the message field input
@property (nonatomic) UIFont *messageFieldFontDiscussion
If this property is nil (default), default font is used
Declared In
Dimelo.h
defaultFont
Default font
@property (nonatomic) UIFont *defaultFontDiscussion
If this property is nil (default), default system font is used
Declared In
Dimelo.h
Advanced Customization
agentNameInsets
Insets for agent name label placed under the message bubble.
@property (nonatomic) UIEdgeInsets agentNameInsetsDiscussion
These insets should be in sync with agentMessageBubbleImage.
Declared In
Dimelo.h
userMessageBubbleImage
Resizable (9-part) image to decorate user text bubble.
@property (nonatomic) UIImage *userMessageBubbleImageSee Also
Declared In
Dimelo.h
agentMessageBubbleImage
Resizable (9-part) image to decorate agent text bubble.
@property (nonatomic) UIImage *agentMessageBubbleImageSee Also
Declared In
Dimelo.h
systemMessageBubbleImage
Resizable (9-part) image to decorate system text bubble.
@property (nonatomic) UIImage *systemMessageBubbleImageSee Also
Declared In
Dimelo.h
userMessageBubbleInsets
Insets for text in user’s message bubble.
@property (nonatomic) UIEdgeInsets userMessageBubbleInsetsSee Also
Declared In
Dimelo.h
agentMessageBubbleInsets
Insets for text in agent’s message bubble.
@property (nonatomic) UIEdgeInsets agentMessageBubbleInsetsSee Also
Declared In
Dimelo.h
systemMessageBubbleInsets
Insets for text in system message bubble.
@property (nonatomic) UIEdgeInsets systemMessageBubbleInsetsSee Also
Declared In
Dimelo.h
userAttachmentBubbleImage
Resizable (9-part) image to mask user’s attachment (alpha channel is used as a mask).
@property (nonatomic) UIImage *userAttachmentBubbleImageDiscussion
By default, the same as userMessageBubbleImage.
See Also
Declared In
Dimelo.h
agentAttachmentBubbleImage
Resizable (9-part) image to mask agent’s attachment (alpha channel is used as a mask).
@property (nonatomic) UIImage *agentAttachmentBubbleImageDiscussion
By default, the same as agentMessageBubbleImage.
Declared In
Dimelo.h
userAttachmentBubbleInsets
Insets for user’s attachment preview bubble.
@property (nonatomic) UIEdgeInsets userAttachmentBubbleInsetsSee Also
Declared In
Dimelo.h
agentAttachmentBubbleInsets
Insets for agent’s attachment preview bubble.
@property (nonatomic) UIEdgeInsets agentAttachmentBubbleInsetsSee Also
Declared In
Dimelo.h
inputBarTintColor
Bar tint color of the input bar.
@property (nonatomic) UIColor *inputBarTintColorDeclared In
Dimelo.h
inputBarBackgroundColor
Background color of the input bar.
@property (nonatomic) UIColor *inputBarBackgroundColorDeclared In
Dimelo.h
attachmentIcon
Icon to be displayed on “attach” button in the input bar.
@property (nonatomic) UIImage *attachmentIconDeclared In
Dimelo.h
keyboardAppearance
Keyboard appearance for a system keyboard.
@property (nonatomic) UIKeyboardAppearance keyboardAppearanceDiscussion
Default is UIKeyboardAppearanceDefault.
Declared In
Dimelo.h