SDK Migration Guide - Android 1.0

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 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 the 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.

The 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 is 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 ChatClient.setLogLevel(Log.VERBOSE).

(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, User and 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 onUserSubscribed callback.

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 onUserUnsubscribed callback method will be called to let you know the object is no longer receiving updates
• The isSubscribed accessor will start to return false if you still have a reference to the User object
• The online and notifiable boolean 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 implementations 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.

The new 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.

The new 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.

A new Users class exists, accessible from the client instance with the getUsers() method. This class is one way to access User and UserDescriptor objects. Methods this class provides include:

• getChannelUserDescriptors is a convenience method to retrieve UserDescriptor objects for an entire Channel's membership with a single asynchronous call. You always have the option to obtain UserDescriptor objects 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
• getUserDescriptor provides a UserDescriptor instance for the specified identity
• getAndSubscribeUser retrieves and subscribes the User object 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
• getSubscribedUsers synchronously returns a list of currently subscribed User objects
• getMyUser synchronously returns a User object 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.

• getMembersByIdentity returns a list of Member objects 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.

The 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 addByIdentity and inviteByIdentity and remove either by identity or via member object using remove /removeByIdentity .

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, getUserDescriptor and 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 getCode and getErrorText renamed to getMessage .