DOCSP-37885: Flutter: Update progress notification documentation (mon…

…godb#3251) ## Pull Request Info Jira ticket: https://jira.mongodb.org/browse/DOCSP-37885 - [Manage a Sync Session - Flutter SDK](https://preview-mongodbcbullinger.gatsbyjs.io/realm/docsp-37885-dart-progress-notifications/sdk/flutter/sync/manage-sync-session/#monitor-sync-upload-and-download-progress): Replace `transferredBytes` and `transferrableBytes` with `progressEstimate`. Update code example. ### Reminder Checklist Before merging your PR, make sure to check a few things. - [x] Did you tag pages appropriately? - genre - meta.keywords - meta.description - [x] Describe your PR's changes in the Release Notes section - [x] Create a Jira ticket for related docs-app-services work, if any ### Release Notes - **Flutter** SDK - Sync Device Data/Manage Sync Session: Update the progress notification documentation in the "Monitor Sync Upload and Download Progress" section for compatibility with Flexible Sync. ### Review Guidelines [REVIEWING.md](https://github.com/mongodb/docs-realm/blob/master/REVIEWING.md)
cbullinger · May 8, 2024 · 0a3b18b · 0a3b18b
1 parent b5987c8
commit 0a3b18b
Show file tree

Hide file tree

Showing 4 changed files with 114 additions and 102 deletions.
diff --git a/examples/dart/test/manage_sync_session_test.dart b/examples/dart/test/manage_sync_session_test.dart
@@ -55,8 +55,8 @@ main() {
       dynamic streamListener;
       streamListener = syncProgress.listen((syncProgressEvent) {
         if (called == false) {
-          expect(syncProgressEvent.transferableBytes > 0, isTrue);
-          expect(syncProgressEvent.transferredBytes > 0, isTrue);
+          expect(syncProgressEvent.progressEstimate > 0.0, isTrue);
+          expect(syncProgressEvent.progressEstimate > 0.0, isTrue);
           called = true;
           streamListener.cancel();
         }
@@ -98,6 +98,7 @@ main() {
       // :snippet-end:
       expect(realm.syncSession.state, SessionState.active);
     });
+
     test("Monitor sync progress", () async {
       var isCalled = false;
       realm.write(() {
@@ -113,19 +114,23 @@ main() {
 
       late StreamSubscription streamListener;
       streamListener = stream.listen((syncProgressEvent) {
-        if (syncProgressEvent.transferableBytes ==
-            syncProgressEvent.transferredBytes) {
-          isCalled = true; // :remove:
-          // Upload complete
-          print('Upload complete');
-          // Stop listening to the Stream
-          streamListener.cancel();
+        final progressEstimate = syncProgressEvent.progressEstimate;
+
+        if (progressEstimate < 1.0) {
+          print('Upload progress: ${progressEstimate * 100}%');
         }
+      }, onDone: () {
+        print("Upload complete");
+        isCalled = true; // :remove:
+      }, onError: (error) {
+        print("An error occurred: $error");
+        streamListener.cancel();
       });
       // :snippet-end:
       await Future.delayed(Duration(seconds: 1));
       expect(isCalled, isTrue);
     });
+
     test("Monitor network connection", () async {
       var isConnected = false;
       // :snippet-start: get-network-connection

diff --git a/source/examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart b/source/examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart
@@ -3,11 +3,14 @@ final stream = realm.syncSession.getProgressStream(
 
 late StreamSubscription streamListener;
 streamListener = stream.listen((syncProgressEvent) {
-  if (syncProgressEvent.transferableBytes ==
-      syncProgressEvent.transferredBytes) {
-    // Upload complete
-    print('Upload complete');
-    // Stop listening to the Stream
-    streamListener.cancel();
+  final progressEstimate = syncProgressEvent.progressEstimate;
+
+  if (progressEstimate < 1.0) {
+    print('Upload progress: ${progressEstimate * 100}%');
   }
+}, onDone: () {
+  print("Upload complete");
+}, onError: (error) {
+  print("An error occurred: $error");
+  streamListener.cancel();
 });
diff --git a/source/sdk/flutter/sync/manage-sync-session.txt b/source/sdk/flutter/sync/manage-sync-session.txt
@@ -9,22 +9,21 @@ Manage a Sync Session - Flutter SDK
   :values: tutorial
 
 .. meta::
-   :description: Pause and resume sync sessions and monitor sync upload progress
-     with the Atlas Device SDK for Flutter.
+   :description: Access the syncSession to check network connection, pause and resume sync sessions, and monitor Sync progress with the Atlas Device SDK for Flutter.
 
 .. contents:: On this page
    :local:
    :backlinks: none
    :depth: 2
    :class: singlecol
 
-When you use Atlas Device Sync, the Realm Flutter SDK syncs data with Atlas
+When you use Atlas Device Sync, the Flutter SDK syncs data with Atlas
 in the background using a sync session. The sync session starts whenever
 you open a synced realm.
 
 The sync session manages the following:
 
-- Uploading and downloading changes to the realm
+- Uploading and downloading changes to the synced database
 - Pausing and resuming sync
 - Monitoring sync progress
 - Monitoring network connectivity
@@ -54,7 +53,7 @@ to download to your synced realm, call :flutter-sdk:`Session.waitForDownload()
 .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.wait-upload-download.dart
    :language: dart
 
-You can add an optional :flutter-sdk:`CancellationToken 
+You can add an optional :flutter-sdk:`CancellationToken
 <realm/CancellationToken-class.html>` to ``waitForUpload()`` and
 ``waitForDownload()``.
 
@@ -87,36 +86,41 @@ When to Pause a Sync Session
 
 .. _flutter-monitor-sync-progress:
 
-Monitor Sync Upload Progress
-----------------------------
+Monitor Sync Upload and Download Progress
+-----------------------------------------
 
-To monitor Sync upload progress progress, call :flutter-sdk:`SyncSession.getProgressStream()
+.. versionchanged:: 2.0.0
+   ``transferredBytes`` and ``transferrableBytes`` deprecated in favor of ``progressEstimate``
+
+To monitor Sync progress, call :flutter-sdk:`SyncSession.getProgressStream()
 <realm/Session/getProgressStream.html>`. This method returns a Stream of
-:flutter-sdk:`SyncProgress <realm/SyncProgress-class.html>` objects.
-``SyncProgress`` provides the total number of transferrable bytes and the remaining
-bytes to be transferred.
+:flutter-sdk:`SyncProgress <realm/SyncProgress-class.html>` objects that provide
+a ``progressEstimate`` for the current upload or download.
+
+The provided ``progressEstimate`` is a double whose value
+ranges from ``0.0`` to ``1.0``. At ``1.0``, the progress stream is complete.
 
 ``SyncSession.getProgressStream()`` takes two arguments:
 
 - A :flutter-sdk:`ProgressDirection <realm/ProgressDirection.html>`
-  enum that must be set to ``upload``.
-  This specifies that the progress stream tracks uploads.
+  enum that can be set to ``upload`` or ``download``. Specifies whether the
+  progress stream monitors upload or download progress.
 
 - A :flutter-sdk:`ProgressMode <realm/ProgressMode.html>` enum
-  that can be set to ``reportIndefinitely`` or ``forCurrentlyOutstandingWork``.
-  ``reportIndefinitely`` sets notifications to continue until the callback is unregistered.
-  ``forCurrentlyOutstandingWork`` sets notifications to continue until only
-  the currently-transferable bytes are synced.
+  that can be set to one of the following:
+
+  - ``reportIndefinitely``: Sets notifications to continue until the callback is
+    unregistered.
+  - ``forCurrentlyOutstandingWork``: Sets notifications to continue until the
+    ``progressEstimate`` reaches ``1.0``.
 
 .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart
    :language: dart
 
-.. warning:: Do Not Track Downloads
+.. tip::
 
-   The ``ProgressDirection`` enum also has a ``download`` option to track down downloads.
-   The ``download`` case provides planned future support for download progress notifications. 
-   However, these notifications do not currently provide an accurate indicator of download progress.
-   Do not rely on ``ProgressDirection.download`` for download progress notifications.
+   Use the ``progressEstimate`` to display a progress indicator or estimated
+   data transfer percentage.
 
 .. _flutter-monitor-network-connection:
 
@@ -146,7 +150,7 @@ Manually Reconnect All Sync Sessions
 The Flutter SDK automatically detects when a device regains connectivity after
 being offline and attempts to reconnect using an incremental backoff strategy.
 
-You can choose to manually trigger a reconnect attempt with the 
+You can choose to manually trigger a reconnect attempt with the
 :flutter-sdk:`App.reconnect() <realm/App/reconnect.html>` instead of waiting for
 the duration of the incremental backoff. This is useful if you have a more
 accurate understanding of the network conditions and don't want to rely on
@@ -155,12 +159,12 @@ automatic reconnect detection.
 .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.session-reconnect.dart
    :language: dart
 
-When you call this method, the SDK forces all sync sessions to attempt to 
+When you call this method, the SDK forces all sync sessions to attempt to
 reconnect immediately and resets any timers used for incremental backoff.
 
 .. important:: Cannot Reconnect Within Socket Read Timeout Duration
-   
+
    The Flutter SDK has an internal default socket read timeout of 2 minutes,
-   where the SDK will time out if a read operation does not receive any data 
-   within a 2-minute window. If you call ``App.Sync.reconnect()`` 
+   where the SDK will time out if a read operation does not receive any data
+   within a 2-minute window. If you call ``App.Sync.reconnect()``
    within that window, the Flutter SDK does *not* attempt to reconnect.