Twilio Programmable Chat 1.0 brings additional controls on data synchronization to enhance performance as well as many other enhancements. This guide will help you migrate your existing Chat applications to the new strategies supported by release 1.0.
Client and Channel callbacks have been expanded to indicate what parts of the object have been updated, allowing you to tailor UI updates to the information that has changed.
Users are no longer implicitly subscribed to to improve performance on large instances. You can subscribe up to a maximum number of users at once after which your least recently used User will be unsubscribed. Using either subscribed Users or User Descriptors appropriately is key to the performance of your application:
- Subscribed Users will immediately reflect changes made on other clients, such as Friendly Name and Attributes and will also have the most up-to-date reachability and online status information. Subscribed Users are best for live display of messages or recently contacted Users by the client.
- User Descriptors are a snapshot in time of that user’s status in the system. These snapshot objects are ideal for temporary lists of users within your user interface or for visualizing large numbers of users on a Channel where constant data synchronization is not key.
The notifications registration process has been streamlined, reflecting success of subscribing to push notifications in a callback rather than the separate delegate methods previously exposed.
Client initialization has been simplified to reflect most users typical usage of the system. All user channels (channels for which the current user is joined to or an owner of) will be subscribed to from client startup but only the members roster will be synchronized initially. This keeps client startup fast while still reflecting the latest activity immediately to the client. This removes the requirement to manually call
synchronize on channel objects to begin utilizing them.
Creation of the Chat client is now asynchronous and the client object is returned to you as part of a listener callback. This change reflects the possibility that client creation may fail due to issues with the provided access token.
ChatClient.Properties object provided during client creation has two fewer properties:
synchronizationStrategy has been deprecated. All user channels are implicitly synchronized in Chat 1.0 so that events for Channels the user is joined to will be delivered from client initialization.
To ensure the impact on clients for this change are manageable, Chat will no longer implicitly load a pre-determined list of messages (previously deprecated
initialMessageCount property has been removed) nor will it synchronize the User objects for Channel's Members. These objects incur frequent updates and can incur additional burden for clients unnecessarily. If you are relying on
initialMessageCount in your implementation, we recommend you consider fetching messages on demand as the user displays the UI for the channel. If having some messages initially is key to your use case, you may iterate through the
ChatClient.getChannels().getSubscribedChannels() once the client is fully synchronized to seed the local cache with a history of messages.
updateToken() has transitioned to use a listener which will provide an indication of success for the token update operation.
Default log level of the Chat SDK has been reduced to Log.WARN. If you need to debug or ask Twilio for support, please build your application setting maximum log level manually using
(un)registerGCMToken is now accompanied by
(un)registerFCMToken which is preferred version of Google push notifications system. You can use only one or another, but not both at the same time - due to conflicting dependencies.
Notification callbacks are renamed, but their function is the same.
In order to not force FCM libraries dependency in the SDK, NotificationPayload class does not support FCM payloads out of the box but there’s an example how it can be used with FCM here.
UserInfo has been deprecated and replaced with two distinct objects,
UserDescriptor. Similar to
ChannelDescriptor objects, a
UserDescriptor represents a snapshot of data in time that should be utilized directly after obtaining it but not retained since it will not be updated with new data over time.
User objects add a new concept to Programmable Chat, subscriptions. A Programmable Chat primitive is subscribed if it will receive updates from the server.
Channel objects at this time are always subscribed, and
ChannelDescriptor objects are not. Similarly,
UserDescriptor objects are not subscribed but a
User object may or may not be subscribed. When a
User is initially subscribed to on the client, you will receive the
When you first obtain a
User object, it will be subscribed but there is a maximum number of
User objects which may be subscribed at a time in the Programmable Chat client. Once this limit is exceeded, the least recently subscribed
User object in memory will be unsubscribed. Several things happen when this occurs:
- The new
onUserUnsubscribedcallback method will be called to let you know the object is no longer receiving updates
isSubscribedaccessor will start to return
falseif you still have a reference to the
notifiableboolean values on an unsubscribed TCHUser will return
false. This reflects a lack of information of the user’s current status.
The number of Users you can concurrently subscribe to in a given instance of the Chat client is large enough that many implementation of Chat will not be affected by User objects being unsubscribed. This is something you should provide for in your code though, and ensure you are using
User objects when consistently updated representation of users is important and
UserDescriptors when displaying a temporary UI such as a membership list.
UserDescriptor object has all of the accessors of the deprecated
UserInfo object but none of the setters. It also has an asynchronous method
subscribe that will return a subscribed
User object has the full functionality of the old
UserInfo object along with a
isSubscribed property which should be checked to see if a
User object is still subscribed. There is an
unsubscribe method on this object which will remove the
User object from the subscription pool explicitly if you no longer need updates for it.
Users class exists, accessible from the client instance with the
getUsers() method. This class is one way to access
UserDescriptor objects. Methods this class provides include:
getChannelUserDescriptorsis a convenience method to retrieve
UserDescriptorobjects for an entire Channel's membership with a single asynchronous call. You always have the option to obtain
UserDescriptorobjects individually for a channel's Member but for a large number of Members this method is faster. The return will be a list of ephemeral UserDescriptor objects
UserDescriptorinstance for the specified identity
getAndSubscribeUserretrieves and subscribes the
Userobject for the specified identity. If the user object is already subscribed, this will be an instance of that object otherwise a new subscription will be created
getSubscribedUserssynchronously returns a list of currently subscribed
getMyUsersynchronously returns a
Userobject corresponding to yourself.
There is a new synchronous method,
getSubscribedChannels which will give you the list of currently synchronized channels. The
getPublicChannels method has been renamed to
getPublicChannelsList for clarity on its returned objects and a new method,
getUserChannelsList has been added.
getMembersByIdentityreturns a list of
Memberobjects with given identity across all available channels.
synchronize has been removed since Channel objects are now always synchronized once loaded.
onChannelUpdated callback has update reason now, specifying what exactly has changed.
getMembersList accessor on the
Members object for a channel will return synchronously a list of members in the Channel. Add, invite and remove functions now have variations using Member object or String identity. It is recommended to add and invite by identity, using
inviteByIdentity and remove either by identity or via member object using
getUserInfo is replaced with a new
getIdentity method which will provide the string identity for the Member. There are also two convenience methods on this class,
getAndSubscribeUser to obtain a
UserDescriptor and subscribed
User object respectively.
One new getter added,
getStatus to return a broad error category (0 being client-side error, non-zero related to network responses). Conveniece
toString method helps in printing/logging the error info.
getErrorCode is renamed to just
getErrorText renamed to