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)disableLibraryAttachment
Declared In
Dimelo.h
+ isLibraryAttachmentEnabled
Get state of individual attachment category or all of them
+ (bool)isLibraryAttachmentEnabled
Declared In
Dimelo.h
Setting up an API client
+ sharedInstance
Returns a shared API client initialized with config from DimeloConfig.plist
+ (instancetype)sharedInstance
Discussion
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>)delegate
Parameters
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>)delegate
Parameters
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>)delegate
Parameters
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>)delegate
Parameters
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 *)apiSecret
Discussion
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> delegate
See Also
Declared In
Dimelo.h
apiKey
Per-application public API key that identifies all requests to Dimelo.
@property (nonatomic, copy) NSString *apiKey
Discussion
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 *hostname
Declared In
Dimelo.h
installationIdentifier
Per-installation identifier generated when the component is instantiated for the first time within the app.
@property (nonatomic, readonly) NSString *installationIdentifier
Declared In
Dimelo.h
userIdentifier
Per-user unique identifier used to link messages sent from different devices to a single person.
@property (nonatomic, copy) NSString *userIdentifier
Discussion
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 *authenticationInfo
Discussion
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 *userName
Declared In
Dimelo.h
jwt
Complete serialized JWT token.
@property (nonatomic, copy) NSString *jwt
Discussion
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 *jwtDictionary
Discussion
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 *messageContextInfo
Discussion
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)displayChatView
Discussion
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 *)chatViewController
Return 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 *deviceToken
Discussion
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 developmentAPNS
Discussion
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 *)dictionary
Parameters
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 unreadCount
Discussion
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 updateAppBadgeNumber
Discussion
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)noteUnreadCountDidChange
Discussion
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 ))completion
Discussion
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 *tintColor
Declared In
Dimelo.h
navigationBarTintColor
Bar tint color for navigation bar (sets barTintColor
property).
@property (nonatomic) UIColor *navigationBarTintColor
Declared In
Dimelo.h
navigationBarColor
Background color for navigation bar (sets backgroundColor
property).
@property (nonatomic) UIColor *navigationBarColor
Declared In
Dimelo.h
title
Title for the chat.
@property (nonatomic, copy) NSString *title
Discussion
Used only if titleView
is nil.
Declared In
Dimelo.h
titleView
Title view for the chat.
@property (nonatomic) UIView *titleView
Discussion
If not nil, overrides title
value.
Declared In
Dimelo.h
backgroundView
Background view of the chat.
@property (nonatomic, readonly) UIView *backgroundView
Discussion
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 *messageFont
Declared In
Dimelo.h
systemMessageFont
Font for system messages.
@property (nonatomic) UIFont *systemMessageFont
Declared In
Dimelo.h
userMessageTextColor
Foreground color for user’s message text.
@property (nonatomic) UIColor *userMessageTextColor
Declared In
Dimelo.h
agentMessageTextColor
Foreground color for agent’s message text.
@property (nonatomic) UIColor *agentMessageTextColor
Declared In
Dimelo.h
systemMessageTextColor
Foreground color for system notification message text.
@property (nonatomic) UIColor *systemMessageTextColor
Declared In
Dimelo.h
userMessageBackgroundColor
Background color for user message bubbles.
@property (nonatomic) UIColor *userMessageBackgroundColor
Discussion
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 *agentMessageBackgroundColor
Discussion
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 *systemMessageBackgroundColor
Discussion
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 *dateTextColor
Declared In
Dimelo.h
dateFormatter
Date formatter instance used to format the date label.
@property (nonatomic) NSDateFormatter *dateFormatter
Declared In
Dimelo.h
errorIconColor
Color for the error icon.
@property (nonatomic) UIColor *errorIconColor
Declared In
Dimelo.h
agentNameFont
Font for agent’s name.
@property (nonatomic) UIFont *agentNameFont
Declared In
Dimelo.h
agentNameColor
Text color for agent’s name.
@property (nonatomic) UIColor *agentNameColor
Declared In
Dimelo.h
loadMoreMessagesButtonTextColor
Text color for the button “load more messages”.
@property (nonatomic) UIColor *loadMoreMessagesButtonTextColor
Discussion
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 *disabledSendButtonColor
Discussion
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 *messageFieldFont
Discussion
If this property is nil (default), default font is used
Declared In
Dimelo.h
defaultFont
Default font
@property (nonatomic) UIFont *defaultFont
Discussion
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 agentNameInsets
Discussion
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 *userMessageBubbleImage
See Also
Declared In
Dimelo.h
agentMessageBubbleImage
Resizable (9-part) image to decorate agent text bubble.
@property (nonatomic) UIImage *agentMessageBubbleImage
See Also
Declared In
Dimelo.h
systemMessageBubbleImage
Resizable (9-part) image to decorate system text bubble.
@property (nonatomic) UIImage *systemMessageBubbleImage
See Also
Declared In
Dimelo.h
userMessageBubbleInsets
Insets for text in user’s message bubble.
@property (nonatomic) UIEdgeInsets userMessageBubbleInsets
See Also
Declared In
Dimelo.h
agentMessageBubbleInsets
Insets for text in agent’s message bubble.
@property (nonatomic) UIEdgeInsets agentMessageBubbleInsets
See Also
Declared In
Dimelo.h
systemMessageBubbleInsets
Insets for text in system message bubble.
@property (nonatomic) UIEdgeInsets systemMessageBubbleInsets
See 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 *userAttachmentBubbleImage
Discussion
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 *agentAttachmentBubbleImage
Discussion
By default, the same as agentMessageBubbleImage
.
Declared In
Dimelo.h
userAttachmentBubbleInsets
Insets for user’s attachment preview bubble.
@property (nonatomic) UIEdgeInsets userAttachmentBubbleInsets
See Also
Declared In
Dimelo.h
agentAttachmentBubbleInsets
Insets for agent’s attachment preview bubble.
@property (nonatomic) UIEdgeInsets agentAttachmentBubbleInsets
See Also
Declared In
Dimelo.h
inputBarTintColor
Bar tint color of the input bar.
@property (nonatomic) UIColor *inputBarTintColor
Declared In
Dimelo.h
inputBarBackgroundColor
Background color of the input bar.
@property (nonatomic) UIColor *inputBarBackgroundColor
Declared In
Dimelo.h
attachmentIcon
Icon to be displayed on “attach” button in the input bar.
@property (nonatomic) UIImage *attachmentIcon
Declared In
Dimelo.h
keyboardAppearance
Keyboard appearance for a system keyboard.
@property (nonatomic) UIKeyboardAppearance keyboardAppearance
Discussion
Default is UIKeyboardAppearanceDefault
.
Declared In
Dimelo.h