117 lines
3.6 KiB
Plaintext
117 lines
3.6 KiB
Plaintext
---
|
||
id: watching_channels
|
||
sidebar_position: 8
|
||
title: Watching Channels
|
||
---
|
||
|
||
More About Watching A Channel
|
||
|
||
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'));
|
||
```
|