86 lines
3.1 KiB
Plaintext
86 lines
3.1 KiB
Plaintext
---
|
||
id: events
|
||
sidebar_position: 25
|
||
title: Events
|
||
---
|
||
|
||
Understand Low Level Messaging Events
|
||
|
||
Events allow the client to stay up to date with changes to the chat. Examples are a new message, a user's image that updated, a reaction, or a member joining the channel. There are a 4 different type of events. These first 2 types of events you receive if you're connected to Stream, no further action is needed to receive these events:
|
||
|
||
Client events: You always receive these events.
|
||
Examples are `connection.recovered`, `health.check` and `connection.changed`
|
||
Notification events: Notification events notify you when something changed on a channel you are a member of even if you're not explicitly watching that channel.
|
||
One example is someone starting a new channel to message you while you are currently in the app.
|
||
|
||
User presence events: `queryUsers`, `queryChannels` and `channel.watch()` allow you to specify `presence=True`,
|
||
if you specify this option you'll opt in to receiving updates about the users on these channels.
|
||
You'll receive events when they go online/offline or their data is updated
|
||
Channel events: if you call `queryChannels` with `watch=true`, or you call `channel.watch()` you'll opt-in to receiving events for the given channels.
|
||
Examples are new messages, people joining the chat etc.
|
||
|
||
### Listening To Events
|
||
|
||
As soon as you call watch on a Channel or queryChannels you’ll start to listen to these events. You can hook into specific events:
|
||
|
||
```dart
|
||
channel.on("message.deleted").listen((Event event) {
|
||
print("message ${event.message.id} was deleted");
|
||
});
|
||
```
|
||
|
||
You can also listen to all events at once:
|
||
|
||
```dart
|
||
channel.on().listen((Event event) {
|
||
print("received a new event of type ${event.type}");
|
||
});
|
||
```
|
||
|
||
### Connection Events
|
||
|
||
The official SDKs make sure that a connection to Stream is kept alive at all times and that chat state
|
||
is recovered when the user's internet connection comes back online.
|
||
Your application can subscribe to changes to the connection using client events.
|
||
|
||
```dart
|
||
client.on('connection.changed', (e) => {
|
||
if (e.online) {
|
||
print('the connection is up!');
|
||
} else {
|
||
print('the connection is down!');
|
||
}
|
||
});
|
||
```
|
||
|
||
### Stop Listening for Events
|
||
|
||
It is a good practice to unregister event handlers once they are not in use anymore. Doing so will save you from performance degradations coming from memory leaks or even from errors and exceptions (i.e. null pointer exceptions)
|
||
|
||
```dart
|
||
final subscription = channel.on().listen((Event event) {
|
||
print("received a new event of type ${event.type}");
|
||
});
|
||
|
||
subscription.cancel();
|
||
```
|
||
|
||
### Custom Events
|
||
|
||
Custom events allow you to build more complex interactions within a channel or with a user.
|
||
|
||
#### To a channel
|
||
|
||
Users connected to a channel, either as a watcher or member, can send custom events and have them delivered to all users watching the channel.
|
||
|
||
```dart
|
||
// sends an event for the current user to all connect clients on the channel
|
||
await channel.sendEvent(
|
||
Event(
|
||
type: 'friendship_request',
|
||
extraData: {
|
||
'text': 'Hey there, long time no see!',
|
||
},
|
||
),
|
||
);
|
||
``` |