Участники
Обзор
Когда игрок вступает в гильдию, групповой чат или лобби, он становится участником канала. Игровой процесс может быть построен таким образом, что игроку потребуется самостоятельно инициировать или отменить запрос на вступление в канал. Участника канала можно исключить, замьютить и так далее.
Взаимодействие участника с каналом - это, например, механизм подачи заявки на вступление в клан
Ниже представлен полный список методов, реализованных для управления участниками канала:
gp.channels.join
- запрос на вступлениеgp.channels.cancelJoin
- отмена запроса на вступлениеgp.channels.leave
- выход участника из каналаgp.channels.kick
- исключение участника из каналаgp.channels.mute
- мьют игрока в каналеgp.channels.unmute
- отменить мьют игрока
Вступление в канал
Чтобы вступить в канал, следует создать запрос на вступление. В этом случае может быть два сценария развития:
- запрос на вступление в публичный канал
gp.channels.on('event:join')
- запрос на вступление в приватный канал
gp.channels.on('event:joinRequest')
Запрос на вступление в публичный канал
Для создания запроса на вступление в канал с идентификатором channelId: 123
используется метод gp.channels.join
:
gp.channels.join({ channelId: 123 });
Если в канале установлен пароль, то его следует передать вместе с идентификатором:
gp.channels.join({ channelId: 123, password: "qwerty" });
Узнать наличие пароля канала можно с помощью метода gp.channels.fetchChannel({ channelId: 123 })
и посмотреть поле channel.hasPassword.
После вызова метода игрок автоматически вступает в канал, если канал был публичный. Если канал приватный, то отправляется запрос на вступление и его должны принять. Чтобы узнать приватный канал или нет, можно посмотреть поле channel.private.
Чтобы получить результат вызова метода, можно подписаться на события:
gp.channels.on('join', () => {
// успешно вступил или подал заявку на вступление
});
Выполнение с ошибкой
gp.channels.on('error:join', (err) => {
// завершен с ошибкой
});
Возможные ошибки приведены в таблице ниже:
базовые ошибки | сценарные ошибки |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | already_in_channel |
player_banned | already_requested 💡 |
internal_error | channel_capacity_reached |
invalid_password 💡 | |
already_in_channel |
already_requested 💡 - уже подал заявку на вступление. invalid_password 💡 - ошибка возникает если на публичный канал установлен пароль и пароль неверный. Если канал приватный, то пароль игнорируется, так как используется механизм подтверждения заявки владельцем.
Сделав запрос на вступление в публичный канал, игрок автоматически становится его участником и всем игрокам в канале приходит уведомление о вступлении:
gp.channels.on('event:join', (member) => {
// ID канала
member.channelId;
// ID вступившего игрока
member.id;
// Поля игрока (аватар, имя, кастомные поля)
member.state;
// Информация о мьюте игрока
member.mute;
});
Запрос на вступление в приватный канал
Всем игрокам в канале (если они могут принимать запросы на вступление) приходит уведомление о том, что новый игрок пытается вступить в канал:
gp.channels.on('event:joinRequest', (joinRequest) => {
// ID канала
joinRequest.channelId;
// ID игрока кто подал запрос на вступление
joinRequest.playerId;
// Поля игрока (аватар, имя, кастомные поля)
joinRequest.player;
// Дата запроса на вступление в ISO 8601 UTC "2022-12-01T04:52:26+0000"
joinRequest.date;
});
Игроки могут принять запрос, используя метод acceptJoinRequest
или отклонить через rejectJoinRequest
(подробнее см. в разделе Запросы).
Отмена запроса на вступление
Для отмены запроса на вступление в канал с идентификатором channelId: 123
используется метод gp.channels.cancelJoin
:
gp.channels.cancelJoin({ channelId: 123 });
Чтобы получить результат вызова метода, можно подписаться на события:
gp.channels.on('cancelJoin', () => {
// успешно отменил заявку на вступление
});
Выполнение с ошибкой:
gp.channels.on('error:cancelJoin', (err) => {
// завершен с ошибкой
});
Возможные ошибки приведены в таблице ниже:
базовые ошибки | сценарные ошибки |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | join_request_not_found 💡 |
player_banned | |
internal_error |
join_request_not_found 💡 - игрок не подавал заявку на вступление или отменил ее
Если игрок отменяет запрос на вступление в канал, то всем игрокам в канале (если они могут принимать запросы на вступление) приходит уведомление о том, что запрос на вступление был отменен:
gp.channels.on('event:cancelJoin', (joinRequest) => {
// ID канала
joinRequest.channelId;
// ID игрок, который подал запрос на вступление
joinRequest.playerId;
});
Выход из канала
Для выхода из канала с идентификатором channelId: 123
:
gp.channels.leave({ channelId: 123 });
Чтобы получить результат вызова метода, можно подписаться на события:
gp.channels.on('leave', () => {
// успешно покинул канал
});
Выполнение с ошибкой:
gp.channels.on('error:leave', (err) => {
// завершен с ошибкой
});
Возможные ошибки приведены в таблице ниже:
базовые ошибки | сценарные ошибки |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | player_not_in_channel |
player_banned | |
internal_error |
Игрок выходит из канала, и всем игрокам в канале приходит уведомление об этом событии event:leave
:
gp.channels.on('event:leave', (memberLeave) => {
// ID канала
memberLeave.channelId;
// ID вышедшего игрока
memberLeave.playerId;
// Причина выхода "leave"
memberLeave.reason;
});
Исключение участника из канала
Владельца канала нельзя исключить из него
Для исключения участника playerId: 123456
из канала channelId: 123
:
gp.channels.kick({ channelId: 123, playerId: 123456 });
Чтобы получить результат вызова метода, можно подписаться на события:
gp.channels.on('kick', () => {
// успешно исключен
});
Выполнение с ошибкой:
gp.channels.on('error:kick', (err) => {
// завершен с ошибкой
});
Возможные ошибки приведены в таблице ниже:
базовые ошибки | сценарные ошибки |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | access_denied |
player_banned | player_not_in_channel |
internal_error |
Игрок выходит из канала и всем игрокам в канале приходит уведомление об этом событии event:leave
:
gp.channels.on('event:leave', (memberLeave) => {
// ID канала
memberLeave.channelId;
// ID вышедшего игрока
memberLeave.playerId;
// Причина выхода "kick"
memberLeave.reason;
});
Получить участников
Можно посмотреть всех игроков (участников) в нужном канале и получить все их публичные данные. Присоединившись к чату, игрок будет видеть всех его участников:
const response = await gp.channels.fetchMembers({
channelId: 10,
// необязательные
// поиск по ID или имени или ID на площадке
search: '',
// искать только тех, кто в сети
onlyOnline: true,
// сколько запросить за раз, макс. 100
limit: 100,
// сколько записей пропустить, макс. 10000, используется для постраничной навигации или "подгрузить еще"
offset: 0
});
Чтобы получить результат вызова метода, можно подписаться на события:
gp.channels.on('fetchMembers', (result) => {
result.items - массив списка участников
result.canLoadMore - можно ли подгрузить еще участников
result.items.forEach((member) => {
// все поля участника
// id игрока
member.id
// сейчас в сети
member.isOnline
// публичные поля игрока
member.state
// Например имя, аватар и очки
member.state.name
member.state.avatar
member.state.score
// информация о мьюте игрока
member.mute
// замьючен или нет
member.mute.isMuted
// время снятия мьюта - дата в ISO 8601, если пустая строка - вечный мьют
member.mute.unmuteAt
});
});
Выполнение с ошибкой:
gp.channels.on('error:fetchMembers', (err) => {
// завершен с ошибкой
});
Возможные ошибки приведены в таблице ниже:
базовые ошибки | сценарные ошибки |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | |
player_banned | |
internal_error |
Чтобы дополнительно подгрузить участников по такому же запросу, существует удобный метод:
const response = await gp.channels.fetchMoreMembers({
channelId: 10,
// необязательные
// поиск по ID или имени или ID на площадке
search: '',
// искать только тех, кто в сети
onlyOnline: true,
// сколько запросить за раз, макс. 100
limit: 100,
});
Чтобы получить результат вызова метода, можно подписаться на события:
gp.channels.on('fetchMoreMembers', (result) => {
result.items - массив списка участников
result.canLoadMore - можно ли подгрузить еще участников
});
Выполнение с ошибкой:
gp.channels.on('error:fetchMoreMembers', (err) => {
// завершен с ошибкой
});
Возможные ошибки приведены в таблице ниже:
базовые ошибки | сценарные ошибки |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | |
player_banned | |
internal_error |
Мьют игрока 🔇
/mute. Владельца канала нельзя замьютить
Чтобы замьютить игрока playerId: 123456
в канале channelId: 123
используется метод gp.channels.mute
.
gp.channels.mute({ channelId: 123, playerId: 123456, unmuteAt: '2022-12-01T04:52:26+0000' });
Альтернативный вариант с возможностью задать количество секунд, на которые требуется замьютить игрока:
// замьютить на 5 минут
gp.channels.mute({ channelId: 123, playerId: 123456, seconds: 5 * 60 });
Разработчик самостоятельно устанавливает время, на которое следует замьютить игрока, с помощью unmuteAt
. Если значение unmuteAt
не передано, то игрок глушится на неограниченное время.
Чтобы получить результат вызова метода, можно подписаться на события:
gp.channels.on('mute', () => {
// успешно замьючен
});
Выполнение с ошибкой:
gp.channels.on('error:mute', (err) => {
// завершен с ошибкой
});
Возможные ошибки приведены в таблице ниже:
базовые ошибки | сценарные ошибки |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | access_denied |
player_banned | wrong_time_format 💡 |
internal_error |
wrong_time_format 💡 - передан неверный формат даты снятия блокировки
При заглушении игрока всем участникам в канале приходит уведомление:
gp.channels.on('event:mute', (mute) => {
// ID канала
mute.channelId;
// ID замьюченного игрока
mute.playerId;
// Дата размьюта
mute.unmuteAt;
});
Размьютить игрока 🔉
/unmute
Вновь разрешить игроку playerId: 123456
писать сообщение в канале channelId: 123
можно с помощью метода gp.channels.unmute
:
gp.channels.unmute({ channelId: 123, playerId: 123456 });
Чтобы получить результат вызова метода, можно подписаться на события:
gp.channels.on('unmute', () => {
// успешно размьючен
});
Выполнение с ошибкой:
gp.channels.on('error:unmute', (err) => {
// завершен с ошибкой
});
Возможные ошибки приведены в таблице ниже:
базовые ошибки | сценарные ошибки |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | access_denied |
player_banned | not_muted |
internal_error |
При этом всем участникам в канале приходит уведомление:
gp.channels.on('event:unmute', (mute) => {
// ID канала
mute.channelId;
// ID размьюченного игрока
mute.playerId;
});
Оставайтесь на связи
С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.
Сообщество GamePush в Telegram
: @gs_community.
Для ваших обращений e-mail
: [email protected]
Желаем вам успехов!