Перейти к основному содержимому

Участники

Обзор

Когда игрок вступает в гильдию, групповой чат или лобби, он становится участником канала. Игровой процесс может быть построен таким образом, что игроку потребуется самостоятельно инициировать или отменить запрос на вступление в канал. Участника канала можно исключить, замьютить и так далее.

tip

Взаимодействие участника с каналом - это, например, механизм подачи заявки на вступление в клан

Ниже представлен полный список методов, реализованных для управления участниками канала:

  • gp.channels.join - запрос на вступление +1 Request
  • gp.channels.cancelJoin - отмена запроса на вступление +1 Request
  • gp.channels.leave - выход участника из канала +1 Request
  • gp.channels.kick - исключение участника из канала +1 Request
  • gp.channels.mute - мьют игрока в канале +1 Request
  • gp.channels.unmute - отменить мьют игрока +1 Request

Вступление в канал

Чтобы вступить в канал, следует создать запрос на вступление. В этом случае может быть два сценария развития:

  • Канал публичный. В него могут вступить все желающие. Тогда игрок автоматически становится участником.
  • Канал приватный. Создается запрос на вступление, который должен принять владелец канала, либо любой участник, если есть права.

Запрос на вступление

+1 Request

Для создания запроса на вступление в канал с идентификатором 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_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedalready_in_channel
player_bannedalready_requested 💡
internal_errorchannel_capacity_reached
invalid_password 💡
already_in_channel
info

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 (подробнее см. в разделе Запросы).

Отмена запроса на вступление

+1 Request

Для отмены запроса на вступление в канал с идентификатором channelId: 123 используется метод gp.channels.cancelJoin:

gp.channels.cancelJoin({ channelId: 123 });

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('cancelJoin', () => {
// успешно отменил заявку на вступление
});

Выполнение с ошибкой:

gp.channels.on('error:cancelJoin', (err) => {
// завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибкисценарные ошибки
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedjoin_request_not_found 💡
player_banned
internal_error
info

join_request_not_found 💡 - игрок не подавал заявку на вступление или отменил ее

Если игрок отменяет запрос на вступление в канал, то всем игрокам в канале (если они могут принимать запросы на вступление) приходит уведомление о том, что запрос на вступление был отменен:

gp.channels.on('event:cancelJoin', (joinRequest) => {
// ID канала
joinRequest.channelId;
// ID игрок, который подал запрос на вступление
joinRequest.playerId;
});

Выход из канала

+1 Request

Для выхода из канала с идентификатором channelId: 123:

gp.channels.leave({ channelId: 123 });

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('leave', () => {
// успешно покинул канал
});

Выполнение с ошибкой:

gp.channels.on('error:leave', (err) => {
// завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибкисценарные ошибки
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedplayer_not_in_channel
player_banned
internal_error

Игрок выходит из канала, и всем игрокам в канале приходит уведомление об этом событии event:leave:

gp.channels.on('event:leave', (memberLeave) => {
// ID канала
memberLeave.channelId;
// ID вышедшего игрока
memberLeave.playerId;
// Причина выхода "leave"
memberLeave.reason;
});

Исключение участника из канала

+1 Request
tip

Владельца канала нельзя исключить из него

Для исключения участника playerId: 123456 из канала channelId: 123:

gp.channels.kick({ channelId: 123, playerId: 123456 });

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('kick', () => {
// успешно исключен
});

Выполнение с ошибкой:

gp.channels.on('error:kick', (err) => {
// завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибкисценарные ошибки
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedaccess_denied
player_bannedplayer_not_in_channel
internal_error

Игрок выходит из канала и всем игрокам в канале приходит уведомление об этом событии event:leave:

gp.channels.on('event:leave', (memberLeave) => {
// ID канала
memberLeave.channelId;
// ID вышедшего игрока
memberLeave.playerId;
// Причина выхода "kick"
memberLeave.reason;
});

Получить участников

+1 Request

Можно посмотреть всех игроков (участников) в нужном канале и получить все их публичные данные. Присоединившись к чату, игрок будет видеть всех его участников:

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_foundempty_channel_id
project_not_foundchannel_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_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowed
player_banned
internal_error

Мьют игрока 🔇

+1 Request
tip

/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 });
info

Разработчик самостоятельно устанавливает время, на которое следует замьютить игрока, с помощью unmuteAt. Если значение unmuteAt не передано, то игрок глушится на неограниченное время.

Чтобы получить результат вызова метода, можно подписаться на события:

gp.channels.on('mute', () => {
// успешно замьючен
});

Выполнение с ошибкой:

gp.channels.on('error:mute', (err) => {
// завершен с ошибкой
});

Возможные ошибки приведены в таблице ниже:

базовые ошибкисценарные ошибки
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedaccess_denied
player_bannedwrong_time_format 💡
internal_error
info

wrong_time_format 💡 - передан неверный формат даты снятия блокировки

При заглушении игрока всем участникам в канале приходит уведомление:

gp.channels.on('event:mute', (mute) => {
// ID канала
mute.channelId;
// ID замьюченного игрока
mute.playerId;
// Дата размьюта
mute.unmuteAt;
});

Размьютить игрока 🔉

+1 Request
tip

/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_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedaccess_denied
player_bannednot_muted
internal_error

При этом всем участникам в канале приходит уведомление:

gp.channels.on('event:unmute', (mute) => {
// ID канала
mute.channelId;
// ID размьюченного игрока
mute.playerId;
});

Оставайтесь на связи

С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.

Сообщество GamePush в Telegram: @gs_community.

Для ваших обращений e-mail: [email protected]

Желаем вам успехов!