feat: Added new docs

2021-06-15 21:40:14 +05:30
parent 8ec130bc84
commit e91b17df6a
3 changed files with 180 additions and 0 deletions
@@ -4,3 +4,111 @@ sidebar_position: 8
 title: Watching Channels
 ---

+The call to channel.watch does a few different things in one API call:
+
+* It creates the channel if it doesn't exist yet (if this user has the right permissions to create a channel)
+* It queries the channel state and returns members, watchers and messages
+* It watches the channel state and tells the server that you want to receive events when anything in this channel changes
+* To start watching a channel
+
+The examples below show how to watch a channel. Note that you need to be connected as a user before you can watch a channel.
+
+```dart
+final state = await channel.watch();
+```
+
+### Watchers vs Members
+
+The concepts of watchers vs members can require a bit of clarification:
+
+* <b>Members</b>: a permanent association between a user and a channel. If the user is online and not watching the channel they will receive a notification event, if they are offline they will receive a push notification.
+* <b>Watchers</b>: the list of watchers is temporary. It's anyone who is currently watching the channel.
+
+Being able to send messages, and otherwise engage with a channel as a non-member requires certain permissions.
+For example, we have pre-configured permissions on our livestream channel type to allow non-members to interact,
+but in the messaging channel type, only members of the channel can interact.
+
+### Watching Multiple Channels
+
+The default queryChannels API returns channels and starts watching them.
+There is no need to also use channel.watch on the channels returned from queryChannels
+
+```dart
+// first let’s create a filter to make messaging channels that include a specific user
+final filter = Filter.in_('members', [user_id]);
+
+// we can also define a sort order of most recent messages first
+final sort = [SortOption("last_message_at", direction: SortOption.DESC)];
+
+// finally, we can query for those channels, automatically watching them for the
+// currently connected user
+final channels = await client.queryChannels(
+  filter: filter,
+  sort: sort,
+  options: {
+    "watch": true,
+    "state": true,
+  },
+);
+```
+
+### Stop Watching a Channel
+
+To stop receiving channel events:
+
+```dart
+// we can also stop watching a channel
+final stopWatching = await channel.stopWatching();
+```
+
+### Watcher Count
+
+To get the watcher count of a channel:
+
+```dart
+// create a new channel of type “livestream” with name “watch-this-channel”
+final channel = client.channel("livestream", id: "watch-this-channel");
+
+// retrieve our channels
+channel.query();
+
+// each channel object has a state collection with a watcher_count property
+ return channel.state.watcherCount;
+```
+
+### Paginating Channel Watchers with channel.query
+
+```dart
+// create a new channel of type “livestream” with name “watch-this-channel”
+final channel = client.channel("livestream", id: "watch-this-channel");
+
+// now query the newly created channel for watchers, retrieving the first 5
+final result = await channel.query(
+    watchersPagination: PaginationParams(
+      limit: 5,
+      offset: 0,
+    ),
+  );
+
+ return result.watchers;
+```
+
+### Listening to Changes in Watchers
+
+A user already watching the channel can listen to users starting and stopping watching the channel with the realtime events:
+
+```dart
+final channel = client.channel("livestream", id: "watch-this-channel");
+
+await channel.watch();
+
+// handle watch started event
+channel
+      .on("user.watching.start")
+      .listen((event) => print('${event.user.id} started watching'));
+
+// handle watch stopped event
+channel
+      .on("user.watching.stop")
+      .listen((event) => print('${event.user.id} stopped watching'));
+```