# Changelog: Twilio Sync Android SDK

> \[!CAUTION]
>
> **Support for 2.0.2 ended on February 8, 2024** Please upgrade to the latest version. See: [Versioning and Support Lifecycle](/docs/sync/versioning-and-support-lifecycle).

## Latest release

The latest release of the Sync SDK for Android is v4.0.0. Separate artifacts for utilizing the SDK with [Kotlin](https://central.sonatype.com/artifact/com.twilio/sync-android-kt) and [Java](https://central.sonatype.com/artifact/com.twilio/sync-android-java) are published on Maven Central.

* [\[Documentation for Kotlin\]](https://media.twiliocdn.com/sdk/android/sync/releases/4.0.0/docs/sync-android-kt)
* [\[Documentation for Java\]](https://media.twiliocdn.com/sdk/android/sync/releases/4.0.0/docs/sync-android-java/)

## Changelog

### Sync SDK for Android v4.0.0 *(Apr 30, 2024)*

#### Kotlin

* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/4.0.0/docs/sync-android-kt)
* gradle: `implementation "com.twilio:sync-android-kt:4.0.0"`

#### Java

* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/4.0.0/docs/sync-android-java/)
* gradle: `implementation "com.twilio:sync-android-java:4.0.0"`

#### Breaking Changes

* The SDK has been completely reworked. Interfaces have changed significantly, providing a more streamlined and efficient user experience.

#### Changes

* We've added a persistent cache. Now, the SDK can start and provide previously cached data even when the device is offline. Once the device comes online, all updates from the backend will be received.

#### New Modules

Starting from v4.0.0, Sync SDK provides two modules:

* `sync-android-kt` is targeted to be used from Kotlin apps. `SyncClient` exposes `suspend` methods to perform async operations. To use `SyncClient` from your Kotlin app, add the following dependency to your project:

```groovy
dependencies {
    implementation "com.twilio:sync-android-kt:4.0.0"
}
```

See [SyncClient documentation](https://sdk.twilio.com/android/sync/releases/4.0.0/docs/sync-android-kt/-sync%20-android%20-s-d-k/com.twilio.sync.client/-sync-client/index.html) for details on how to create a `SyncClient`.

* `sync-android-java` is targeted to be used from Java apps. `SyncClientJava` exposes methods which receive listeners to perform async operations. To use `SyncClientJava` from your Java app, add the following dependency to your project:

```groovy
dependencies {
    implementation "com.twilio:sync-android-java:4.0.0"
}
```

See [SyncClientJava documentation](https://sdk.twilio.com/android/sync/releases/4.0.0/docs/sync-android-java/-sync%20-android%20-s-d-k%20for%20-java/com.twilio.sync.client.java/-sync-client-java/index.html) for details on how to create a `SyncClientJava`.

#### Compatibility

The Sync SDK now exposes dates using `kotlinx.datetime.Instant`. If you are targeting Android devices running **below API 26**, you will need to enable `coreLibraryDesugaring` to ensure compatibility. Follow the steps below:

```groovy
android { 
    compileOptions { 
        coreLibraryDesugaringEnabled true 
    } 
}

dependencies {
    "com.android.tools:desugar_jdk_libs:1.2.2"
}
```

For more information on using `kotlinx.datetime` in your projects, visit the [official documentation](https://github.com/Kotlin/kotlinx-datetime#using-in-your-projects).

#### Example Usage

Here's an example of how to use the new SDK:

```kotlin
    val syncClient = SyncClient(applicationContext) { requestToken() }

    // Create a new map
    val map = syncClient.maps.create()

    // Listen for item-added events flow
    map.events.onItemAdded
        .onEach { println("Item added: ${it.key}") }
        .launchIn(MainScope())

    // Declare custom data type
    @kotlinx.serialization.Serializable
    data class MyData(val data: Int)

    // Add 10 items to the map
    repeat(10) { index ->
        map.setItem("key$index", MyData(index))
    }

    // Read all items from the map
    for (item in map) {
        val myData = item.data<MyData>()
        println("Key: ${item.key}, Value: ${myData.data}")
    }

    // Remove the map
    map.removeMap()
```

Please note that these changes may require modifications to your existing codebase to ensure compatibility with the new version of the SDK. We recommend thoroughly testing your application after updating to Sync SDK v4.0.0.

We hope you enjoy the new features and improvements in Sync SDK v4.0.0!

### Sync SDK for Android v3.0.3 *(Oct 26, 2023)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/3.0.3/twilio-sync-android-3.0.3.aar) sha256:`5edd0a6c2abad43681b54425dadddd71ee5c6b019c62a12e821c17343fd34465`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/3.0.3/docs/sync-android/)
* gradle: `implementation "com.twilio:sync-android:3.0.3"`

#### Changes

* Fixed a memory leak when client creation fails.

### Sync SDK for Android v3.0.2 *(Aug 18, 2023)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/3.0.2/twilio-sync-android-3.0.2.aar) sha256:`fae097470c70fec1b5f967028abc74c9c12d9c89bc0ec4b51e5112bcbcee7663`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/3.0.2/docs/sync-android/)
* gradle: `implementation "com.twilio:sync-android:3.0.2"`

#### Changes \[#changes-2]

* Fixed a crash which could occur on client creation.
* Fixed issues in transport protocol handling.
* Starting with this release the Gradle Module Metadata file is published to maven central. Now binary incompatibility between SyncSDK and ConversationsSDK will be automatically reported at compile time.

### Sync SDK for Android v3.0.1 *(May 15, 2023)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/3.0.1/twilio-sync-android-3.0.1.aar) sha256:`c7a4470785cae0e3b2771d003d3b3a011e5ac2cd3aa14fbd8ccf5767269e8877`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/3.0.1/docs/sync-android/)
* gradle: `implementation "com.twilio:sync-android:3.0.1"`

#### Changes \[#changes-3]

* Fixed a crash when both Sync SDK and Conversations SDK are in the same app.

### Sync SDK for Android v3.0.0 *(Feb 8, 2023)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/3.0.0/twilio-sync-android-3.0.0.aar) sha256:`30b32eaa4248b0e15405001867359ddf1a0d848bb205140998ffdebf6bd8d2b2`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/3.0.0/docs/sync-android/)
* gradle: `implementation "com.twilio:sync-android:3.0.0"`

#### Changes \[#changes-4]

* Bumped kotlin version to 1.8.0

#### Breaking Changes

* Bumped Android minSdkVersion to 21

### Sync SDK for Android v2.0.2 *(Nov 1, 2022)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/2.0.2/twilio-sync-android-2.0.2.aar) sha256:`44e140754fd7e41f0dddc16d3fd0ad507c78b3d01ef123f8a6f0cf65b5687feb`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/2.0.2/docs/)
* gradle: `implementation "com.twilio:sync-android:2.0.2"`

#### Changes \[#changes-5]

* Bump the ktor dependency to v2.1.2

### Sync SDK for Android v2.0.1 *(Sep 29, 2022)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/2.0.1/twilio-sync-android-2.0.1.aar) sha256:`cb51f8c153741dcc8b05af5770fc17683219e57e85f659fbea19502fccd98c63`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/2.0.1/docs/)
* gradle: `implementation "com.twilio:sync-android:2.0.1"`

#### Changes \[#changes-6]

* Fixed crash on device connectivity changes
* targetSdkVersion bumped to android-33

### Sync SDK for Android v2.0.0 *(Aug 18, 2022)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/2.0.0/twilio-sync-android-2.0.0.aar) sha256:`5e4c0afc5c688e832c2afe6e342febdefd9328afb93c80c717a5ef369d0f74c8`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/2.0.0/docs/)
* gradle: `implementation "com.twilio:sync-android:2.0.0"`

#### Changes \[#changes-7]

* Reduced the SDK footprint: AAR library has decreased in size by 6,86 %
* Significantly improved stability by refactoring transport layer to eliminate race conditions by design

#### Breaking Changes \[#breaking-changes-2]

* For the `UNAUTHORIZED` error the `ErrorInfo.code` is now 5 (was 1)
* In edge cases error codes and messages changed to more informative. So if your app relies on any specific error codes and/or messages - these cases should be double checked after updating to this version.

***

### Sync SDK for Android v1.1.0 *(Mar 8, 2022)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.1.0/twilio-sync-android-1.1.0.aar) sha256:`e4cfe5f38e13a73fdda9815699546a7b7b8cedfc644f3568b3795dcd2cd21f1d`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.1.0/docs/)
* gradle: `implementation "com.twilio:sync-android:1.1.0"`

#### Changes \[#changes-8]

* Improved performance in use cases where the user subscribes to thousands of objects.

***

### Sync SDK for Android v1.0.3 *(Jul 1, 2021)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.0.3/twilio-sync-android-1.0.3.aar) sha256:`293868bd9e4f1b70898df1376728ec771a7befda8a8c7955bca59c2a12000f5c`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.0.3/docs/)
* gradle: `implementation "com.twilio:sync-android:1.0.3"`

#### Changes \[#changes-9]

* Fixed compilation errors when sync and conversations SDKs are used together in an application.

***

### Sync SDK for Android v1.0.2 *(April 27, 2021)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.0.2/twilio-sync-android-1.0.2.aar) sha256:`a8e474a9ce48daf40b1f4d444a52580848fad3e649b4d8240b6a41b1721805f3`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.0.2/docs/)
* gradle: `implementation "com.twilio:sync-android:1.0.2"`

#### Changes \[#changes-10]

* Fixed a reconnection issue after restoring application from background.

***

### Sync SDK for Android v1.0.1 *(March 17, 2021)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.0.1/twilio-sync-android-1.0.1.aar) sha256:`afb799129b7860e19e3060d3c36aad5ca5f490bc16669287d454c3ca88be752e`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.0.1/docs/)
* gradle: `implementation "com.twilio:sync-android:1.0.1"`

#### Changes \[#changes-11]

* Reduced SDK footprint

Starting from this release all artifacts are published on `mavenCentral` instead of `jcenter`.
Root `build.gradle` have to be updated by adding `mavenCentral()` repository:

```bash
allprojects {
    repositories {
        mavenCentral()
    }
}
```

***

### Sync SDK for Android v1.0.0 *(January 19, 2021)*

* [\[aar\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.0.0/twilio-sync-android-1.0.0.aar) sha256:`bc416e2aa08aafbb148de797e6d633950640edefe6bb7740b1d52e66a08704b7`
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/1.0.0/docs/)
* gradle: `implementation "com.twilio:sync-android:1.0.0"`

#### Breaking Changes \[#breaking-changes-3]

* Java 8 required. Add to your project's `build.gradle` the following compile options, necessary to use Java8 syntax features:

```bash
compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

// Also if kotlin is used in the project
kotlinOptions {
    jvmTarget = '1.8'
}
```

* List of renamed entities:
  * `List` -> `SyncList`
  * `ListIterator` -> `SyncListIterator`
  * `ListObserver` -> `SyncListObserver`
  * `ListPaginator` -> `SyncListPaginator`
  * `Map` -> `SyncMap`
  * `MapIterator` -> `SyncMapIterator`
  * `MapObserver` -> `SyncMapObserver`
  * `MapPaginator` -> `SyncMapPaginator`
  * `Document` -> `SyncDocument`
  * `DocumentObserver` -> `SyncDocumentObserver`
  * `Stream` -> `SyncStream`
  * `StreamObserver` -> `SyncStreamObserver`
  * `Mutator` -> `SyncMutator`
  * `Options` -> `SyncOptions`
  * `ConnectionStateListener` -> `SyncClientListener`
  * `SyncClient.setConnectionStateListener()` -> `SyncClient.setListener()`
  * `InfiniteDuration` -> `INFINITE_DURATION`
* `SuccessListener` is interface now. So remove constructor invocation in Kotlin code to make it compile.
* `SyncOptions` is interface now. Use `SyncOptions.create()` for creating new instance.
* `previousData` parameter added to `SyncDocumentObserver.onRemoved()` callback.
* Removed `PageSort` parameter while querying items from `SyncList` or `SyncMap`. The order of items within the page is not guaranteed. Implement necessary sorting in application code if needed.
* Returned error codes changed in number of cases.

#### Changes \[#changes-12]

* Exposed `dateUpdated` for all sync objects (SyncList, SyncMap, SyncMap.Item etc).
* Added `onTokenAboutToExpire` and `onTokenExpired` callbacks to `SyncClientListener`.
* Fixed a bug when `previousData`/`previousItemData` is null in updated/removed callbacks for client who made the modification.
* Fixed a bug when client didn't call `onError()` callback after initialisation with invalid token.
* Improved documentation.

#### Known issues

* Recovery takes more time after network loss compared to 0.8.7.
* Update to `v1.0.1` or newer, if you got runtime error: `java.lang.NoClassDefFoundError: Failed resolution of: Lcom/getkeepsafe/relinker/ReLinker`

***

### Sync SDK for Android v0.9.0 *(August 7, 2020)*

* [\[aar\]](https://bintray.com/twilio/releases/download_file?file_path=com%2Ftwilio%2Fsync-android%2F0.9.0%2Fsync-android-0.9.0.aar)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.9.0/docs/)
* gradle: `implementation "com.twilio:sync-android:0.9.0"`

#### Changes \[#changes-13]

* SDK has switched to android native SSLSocket implementation (`javax.net.ssl.SSLSocket`), resulting in a noticeable decrease in final application size compared to previous release 0.8.7.

#### Known issues \[#known-issues-2]

* Recovery takes more time after network loss compared to previous release 0.8.7.

***

### Sync SDK for Android v0.8.7 *(January 14, 2020)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.8.7)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.8.7/docs/)
* gradle: `implementation "com.twilio:sync-android:0.8.7"`

#### Changes \[#changes-14]

* Minor bugfixes and stability improvements

***

### Sync SDK for Android v0.8.6 *(October 17, 2019)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.8.6)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.8.6/docs/)
* gradle: `implementation "com.twilio:sync-android:0.8.6"`

#### Changes \[#changes-15]

* Decreased the minimum Android SDK version to 19.
* Included the Proguard rules for Twilio classes with SDK package.

***

### Sync SDK for Android v0.8.5 *(September 27, 2019)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.8.5)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.8.5/docs/)
* gradle: `implementation "com.twilio:sync-android:0.8.5"`

#### Changes \[#changes-16]

* Fixed stack dump symbolication on Сrashlytics.
* Reduced SDK footprint, resulting in a noticeable decrease in final application size compared to release 0.8.2
* Fixed an issue where a completion handler is called more than once when publishing messages to a deleted stream.
* Fixed a bug where the `StreamObserver.onRemoved()` event is received twice.

***

### Sync SDK for Android v0.8.2 *(June 26, 2019)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.8.2)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.8.2/docs/)
* gradle: `implementation "com.twilio:sync-android:0.8.2"`

#### Changes \[#changes-17]

* Improved stability on shutdown, fixed crash issue

***

### Sync SDK for Android v0.8.1 *(April 16, 2019)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.8.1)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.8.1/docs/)
* gradle: `implementation "com.twilio:sync-android:0.8.1"`

#### Changes \[#changes-18]

* Improved connection reliability under bad network conditions.
* Fixed unexpected connectivity errors with code 1401: Unable to establish connection to Twilio Sync service.
* Increased targetSdkVersion to 28 in preparation for Google SDK policy targeted in August; minSdkVersion remains 21.

***

### Sync SDK for Android v0.8.0 *(March 7, 2019)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.8.0)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.8.0/docs/)
* gradle: `implementation "com.twilio:sync-android:0.8.0"`

#### Changes \[#changes-19]

* Overhauled transport and communication layer, significantly improving network traffic overhead and client performance
* SDK size reduction - it gained over the course of the year, so we sent it to the gym. Native libraries are now repackaged and optimized for size.

***

### Sync SDK for Android v0.7.2 *(May 23, 2018)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.7.2)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.7.2/docs/)
* gradle: `compile "com.twilio:sync-android:0.7.2"`

#### Changes \[#changes-20]

* Improve privacy compliance: by default use log level SILENT to not output anything from SDK by default. Switch to higher debug level using SyncClient.setLogLevel() to receive log messages.

***

### Sync SDK for Android v0.7.1 *(March 2, 2018)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.7.1)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.7.1/docs/)
* gradle: `compile "com.twilio:sync-android:0.7.1"`

#### Changes \[#changes-21]

* Observer interfaces will no longer receive onErrorOccurred events when a failure to open Document, List, Map or Stream occurs. The SuccessListener for such operations is the best way to check for success or failure on open/creation.
* Resolved issue with connection state listener, where onConnectionStateChanged event was not called on the user thread.
* Resolved issue with SuccessListeners where events for openDocument, openMap, openList, openStream were not called on the user thread.
* Resolved issue where remote update events may not be received after the same object got opened multiple times concurrently.

***

### Sync SDK for Android v0.7.0 *(February 15, 2018)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.7.0)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.7.0/docs/)
* gradle: `compile "com.twilio:sync-android:0.7.0"`

#### Changes \[#changes-22]

*Synopsis of enhancements:*

* FlowId has been deprecated in favor of passing the resulting object to the listeners now, where previously arguments to listeners were Void.
* The distinction between remote (for remotely initiated operations) and result (for locally initiated operations) has been transitioned to EventContext's isLocal() flag. The callback interfaces are thus simplified, by combining onResultXYZ and onRemoteXYZ events under the same method.
* Documents, Lists (and their items), Maps (and their items) and Streams may now all have an optional max time to live specified. This number is expressed in seconds and is relative to when the TTL is set. After the TTL expires, the object will be destroyed on the backend in the near future. Options has been expanded to allow specifying a TTL during object creation (this property is ignored when opening preexisting objects.) The Metadata classes taken as a parameter for some methods on Document, List and Map are optional and can be specified as null.

*Migration tips:*

FlowId has been removed globally; most methods that previously accepted a flowID now also accept metadata which can be null today if you are not specifying a TTL.

Most observer methods have changed signature. The individual remote and local observer methods have been combined into a single observer method for operations. Observers which previously received only an index or key will now also receive the full value. Most observer methods now also provide an EventContext object which will indicate whether the operation was locally or remotely initiated.

*Update squashing:*

Individual local operations will continue to return the status of each operation via their SuccessListener interface but updates sent to the server may be batched for efficiency. This means remote clients may not see every state update performed individually, but will instead see updates with the object's final updated state.

If you require updates to be treated as individual operations for purposes of notifying remote clients, it is recommended you schedule subsequent updates to occur after the completion of each operation.

*Other enhancements and bugfixes:*

* Enabled returning *null* from mutator functions, gracefully abandoning data change operations.
* Added SDK version logging on startup, with "Twilio Sync SDK version \{VERSION}" text.
* Added SyncClient.setLogLevel() method to configure the SDK log level for troubleshooting purposes.
* Fixed a race condition with an early arriving collection item remote update events.
* Fixed support for multicasting events to observers attached to de-duplicated instances of objects, i.e. where the same object SID is opened multiple times.
* Provided a fix against crash on Android Oreo.
* Listeners added via SyncClient.setConnectionStateListener() will now receive callbacks in the correct thread.

***

### Sync SDK for Android v0.6.3 *(February 1, 2018)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.6.3)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.6.3/docs/)
* gradle: `compile "com.twilio:sync-android:0.6.3"`

#### Changes \[#changes-23]

* Updated internal certificate store for upcoming certificate authority changes.

***

### Sync SDK for Android v0.6.2 *(January 9, 2018)*

* [\[aar\]](https://bintray.com/twilio/releases/sync-android/0.6.2)
* [\[Documentation\]](https://media.twiliocdn.com/sdk/android/sync/releases/0.6.2/docs/)
* gradle: `compile "com.twilio:sync-android:0.6.2"`

#### Changes \[#changes-24]

* Optimized SDK speed
* Optimized SDK size
* Improved SDK stability