실시간 채팅 - HyperX Docs

HyperX 채팅은 프로젝트 안의 인증된 유저가 채널에 참여하고 메시지를 주고받는 기능입니다. 서버는 채널, 멤버십, 메시지 순서, 읽음 위치, 신고 상태를 저장하고 Console에서 운영자가 확인할 수 있습니다.

채널 만들기와 참여

var channel = await player.CreateChatChannel(
    channelKey: "global",
    channelType: HyperX.ChatChannelType.Project,
    displayName: "Global",
    retentionDays: 90
);

await player.JoinChat(channel.Id);

지원 채널 유형은 HyperX.ChatChannelType.Project, HyperX.ChatChannelType.Guild, HyperX.ChatChannelType.Party, HyperX.ChatChannelType.Direct, HyperX.ChatChannelType.Announcement입니다. 커스텀 값이 필요하면 기존 string 값을 전달할 수 있습니다. 공지 채널은 일반 유저가 읽기 전용으로 사용합니다.

메시지 보내기와 읽기

var sent = await player.SendChatMessage(
    channel.Id,
    "hello"
);

var messages = await player.ChatMessages(
    channel.Id,
    afterSequence: sent.Sequence - 1
);

await player.AcknowledgeChat(
    channel.Id,
    sent.Sequence
);

sequence는 채널 안에서 증가하는 메시지 번호입니다. 재접속 후 마지막으로 처리한 sequence를 afterSequence로 전달하면 놓친 메시지를 이어서 받을 수 있습니다.

Unity 구독

var subscription = player.SubscribeChat(
    channel.Id,
    message => Debug.Log(message.Body),
    error => Debug.LogWarning(error.Message),
    pollIntervalMilliseconds: 2000
);

// GameObject가 사라질 때 호출
subscription.Dispose();

채팅 화면이 열려 있을 때만 구독하고, 화면을 닫으면 Dispose를 호출해 불필요한 조회를 줄이세요. 구독은 마지막으로 처리한 sequence를 유지하고 새 메시지를 callback에 전달한 뒤 ack를 보냅니다. 일시적인 실패가 발생하면 SDK는 reconnecting 상태로 전환하고 최대 30초까지 제한된 backoff를 적용한 뒤 마지막 sequence부터 catch-up을 재개합니다. access token이 만료되면 Core.Users.Refresh(refreshToken)로 세션을 갱신하고 새 access token으로 구독을 다시 생성하세요.

신고와 운영 제어

await player.ReportChatMessage(
    channel.Id,
    messageId,
    reason: "spam"
);

운영자가 유저를 뮤트하거나 메시지를 숨기면 SDK 호출은 구조화된 오류를 받을 수 있습니다.

try
{
    await player.SendChatMessage(channel.Id, "hello");
}
catch (HyperX.HyperXServerException ex)
    when (ex.ErrorCode == "CHAT_SENDER_MUTED")
{
    Debug.Log("채팅 제한 상태입니다.");
}