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,42 @@ sidebar_position: 6
 title: Creating Channels
 ---

+Both channel <b>channel.query</b> and  <b>channel.watch</b> methods ensure that a channel exists and create one otherwise.
+If all you need is to ensure that a channel exists, you can use <b>channel.create</b>.
+Typically you use <b>channel.watch</b> client side and <b>channel.create</b> for a server side integration.
+Channels are unique either by the specified channel id or by the list of members.
+
+### Creating a Channel Using a Channel ID
+
+This is typically the best approach if you already have some sort of object in your database that the channel is associated with.
+As an example if you're building a live-streaming service like Twitch you have a channel for every streamer in your database.
+
+```dart
+final channel = client.channel(
+  "messaging",
+  id: "travel",
+  extraData: {
+    "name": "Founder Chat",
+    "image": "http://bit.ly/2O35mws",
+    "members": ["thierry", "tommaso"],
+  },
+);
+```
+
+Note: Note that for client side integrations you'll typically prefer to use channel.watch() instead of channel.create.
+Channel.watch both creates the channel and watches it at the same time.
+
+### Creating a Channel for a List of Members
+
+Channels can be used to create conversations between users.
+In most cases, you want conversations to be unique and make sure that a group of users have only one channel.
+
+You can achieve this by leaving the channel ID empty and provide channel type and members.
+When you do so, the API will ensure that only one channel for the members you specified exists (the order of the members does not matter).
+
+Note: You cannot add/remove members for channels created this way.
+
+```dart
+client.channel("messaging", extraData: {"members": ["thierry", "tommaso"]});
+```
+
@@ -4,3 +4,36 @@ sidebar_position: 7
 title: Querying Channels
 ---

+If you’re building a similar application to Facebook Messenger or Intercom, you’ll want to show a list of Channels.
+The Chat API supports MongoDB style queries to make this easy to implement.
+
+You can query channels based on built-in fields as well as any custom field you add to channels.
+Multiple filters can be combined using AND, OR logical operators, each filter can use its comparison (equality, inequality, greater than, greater or equal, etc.). You can find the complete list of supported operators in the query syntax section of the docs.
+
+As an example, let's say that you want to query the last conversations I participated in sorted by `last_message_at`.
+
+Here’s an example of how you can query the list of channels:
+
+```dart
+final filter = Filter.in_('members', ['thierry']);
+
+final sort = [SortOption("last_message_at", direction: SortOption.DESC)];
+
+final channels = await client.queryChannels(
+  filter: filter,
+  sort: sort,
+  options: {
+    "watch": true,
+    "state": true,
+  },
+);
+
+channels.forEach((Channel c) {
+  print("${c.extraData['name']} ${c.cid}");
+});
+```
+
+The query channels endpoint will only return channels that the user can read,
+you should make sure that the query uses a filter that includes such logic.
+For example: messaging channels are readable only to their members,
+such requirement can be included in the query filter (see below).
@@ -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'));
+```