chzzkgo

package module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 18 Imported by: 0

README

chzzkgo

A Go library for streaming platform 치지직(CHZZK).

치지직 Open API의 Go SDK입니다. Go 1.26 이상이 필요합니다.

REST API와 세션 서버의 실시간 이벤트 수신을 모두 지원합니다. 실시간 이벤트에는 Socket.IO 2.x 클라이언트인 socketio2를 사용합니다.

이 프로젝트는 네이버(NAVER) 및 치지직(CHZZK)의 공식 라이브러리가 아닙니다.

Installation

go get github.com/fi-xz/chzzkgo

Quickstart

Client 인증(Client ID/Secret)만으로 호출 가능한 API는 토큰 없이 바로 사용할 수 있습니다.

package main

import (
    "context"
    "fmt"

    "github.com/fi-xz/chzzkgo"
)

func main() {
    chzzk := chzzkgo.New("SAMPLE_CLIENT_ID", "SAMPLE_CLIENT_SECRET", "http://localhost:8080/callback")

    lives, err := chzzk.GetLiveList(context.Background())

    if err != nil {
        panic(err)
    }

    for _, live := range lives.Data {
        fmt.Println(live.ChannelName, "-", live.LiveTitle)
    }
}

Client 인증 API: GetChannels, SearchCategory, GetLiveList, CreateSessionWithClient, GetSessionsWithClient 등.

API 커버리지

카테고리 상태 메서드
인증 ✅ GetAuthorizationURL, ExchangeCode, RequestToken, RevokeToken, LoginServer (Start / LoginHandler / CallbackHandler)
유저 ✅ GetUser
채널 ✅ GetChannels, GetChannelManagers, GetChannelFollowers, GetChannelSubscribers
카테고리 ✅ SearchCategory
라이브 ✅ GetLiveList, GetStreamKey, GetLiveSettings, SetLiveSettings
채팅 ✅ SendChatMessage, SetChatNotice, GetChatSettings, SetChatSettings, BlindChatMessage
활동제한 ✅ AddRestriction, RemoveRestriction, GetRestrictions, AddTemporaryRestriction, RemoveTemporaryRestriction
세션 (URL 발급·목록·이벤트 구독/해제) ✅ CreateSessionWithClient, CreateSessionWithUser, GetSessionsWithClient, GetSessionsWithUser, Subscribe·UnsubscribeChatEvent, Subscribe·UnsubscribeDonationEvent, Subscribe·UnsubscribeSubscriptionEvent
세션 (실시간 이벤트 수신) ✅ SessionSocket, ConnectSessionWithUser, ConnectSessionWithClient
드롭스 ❌ 미구현

OAuth 로그인

사용자 권한이 필요한 API는 OAuth 토큰이 필요합니다. 내장 LoginServer로 로그인 흐름을 처리할 수 있습니다.

chzzk := chzzkgo.New(clientID, clientSecret, "http://localhost:8080/callback")

// http://localhost:8080/login 접속 → 치지직 로그인 → 첫 로그인 성공 시 서버 자동 종료
tokens, err := chzzk.NewLoginServer().Start(context.Background())

if err != nil {
    panic(err)
}

// 일회용 모드에서는 발급된 토큰이 클라이언트에 자동 주입됩니다
user, err := chzzk.GetUser(context.Background())

여러 사용자의 로그인을 상시로 받는 endpoint는 WithKeepAlive와 WithOnLogin을 사용합니다. 이 경우 토큰은 클라이언트에 주입되지 않고 콜백으로만 전달됩니다.

server := chzzk.NewLoginServer(
    chzzkgo.WithKeepAlive(),
    chzzkgo.WithOnLogin(func(t chzzkgo.Tokens) { /* 계정별 토큰 저장 */ }),
)
_, err := server.Start(ctx) // ctx 취소 전까지 유지
기존 서버에 통합

이미 운영 중인 HTTP 서버가 있다면 Start 대신 핸들러를 직접 등록할 수 있습니다. Start는 아래 두 핸들러를 자체 서버에 얹어 주는 Wrapper입니다.

server := chzzk.NewLoginServer(
    chzzkgo.WithOnLogin(func(t chzzkgo.Tokens) { /* 토큰 저장 */ }),
)

http.Handle("/auth/chzzk", server.LoginHandler())       // state 발급 + 인가 페이지로 리다이렉트
http.Handle("/callback", server.CallbackHandler())      // state 검증 + 토큰 교환

핸들러를 직접 사용할 때 서버의 수명과 포트는 호출자가 관리합니다. WithKeepAlive의 서버 유지 동작은 Start 전용이며, 핸들러 사용 시에는 영향이 없습니다.

토큰 저장과 복원

토큰의 저장과 복원은 라이브러리 사용자가 직접 진행합니다.

// 저장해 둔 토큰 복원
chzzk.SetTokens(accessToken, refreshToken, chzzkgo.ParseScopes("유저 조회 채팅 메시지 쓰기"))

// 액세스 토큰 만료 시 자동 갱신됨 — 갱신된 토큰을 콜백으로 받아 저장
chzzk.OnTokenRefresh(func(t chzzkgo.Tokens) {
    saveToStorage(t) // t를 JSON으로 저장하면 Scope까지 원형 유지됨
})

Scope

치지직은 권한 이름으로 한국어 문자열을 사용하며, SDK는 이를 상수로 제공합니다. (chzzkgo.UserRead = "유저 조회" 등) 필요 권한이 토큰에 없으면 API 호출 전에 MissingScopeError를 반환합니다. 이는 편의를 위한 사전 검사이며, 최종 판정은 서버가 수행합니다.

설정 변경 (부분 업데이트)

방송/채팅 설정 변경은 포인터 필드 구조체를 사용합니다. nil 필드는 전송되지 않아 기존 값이 유지됩니다. 값 지정에는 내장 함수 new를 사용합니다.

err := chzzk.SetLiveSettings(ctx, chzzkgo.LiveSettingsPatch{
    DefaultLiveTitle: new("새 방송 제목"),
    Tags:             new([]string{"개발자"}),
})

실시간 이벤트 수신

세션 서버에 접속하면 채팅·후원·구독 이벤트를 실시간으로 받을 수 있습니다. 세션 URL을 발급받고 소켓에 연결한 뒤, 세션 키로 원하는 이벤트를 구독하는 순서입니다.

socket, err := chzzk.ConnectSessionWithUser(ctx, func(s *chzzkgo.SessionSocket) {
    // 핸들러는 반드시 연결 전에 등록합니다.
    s.OnChat(func(e chzzkgo.ChatEvent) {
        fmt.Printf("%s: %s\n", e.Profile.Nickname, e.Content)
    })
    s.OnDonation(func(e chzzkgo.DonationEvent) {
        fmt.Printf("%s님이 %d원 후원\n", e.DonatorNickname, e.PayAmount)
    })
})

if err != nil {
    return err
}

defer socket.Close()

// 연결만으로는 이벤트가 오지 않습니다. 세션 키로 구독해야 합니다.
if err := chzzk.SubscribeChatEvent(ctx, socket.SessionKey()); err != nil {
    return err
}

<-socket.Done()
return socket.Err()

세션 URL을 직접 다루려면 NewSessionSocket을 사용합니다.

session, err := chzzk.CreateSessionWithUser(ctx)
socket := chzzkgo.NewSessionSocket(session.URL)
socket.OnChat(...)
err = socket.Connect(ctx)

Connect는 서버가 세션 키를 보낼 때까지 기다린 뒤 반환하므로, 반환 직후 SessionKey()로 구독을 시작할 수 있습니다.

재연결은 하지 않습니다

세션 URL은 한 번만 쓸 수 있어 같은 URL로 다시 접속할 수 없습니다. Done()이 닫히면 Err()로 원인을 확인하고 세션을 새로 발급받아 다시 연결하세요. ConnectSessionWithUser를 반복 호출하면 발급과 연결을 한 번에 처리할 수 있습니다.

for {
    socket, err := chzzk.ConnectSessionWithUser(ctx, register)
    if err != nil {
        return err
    }

    if err := chzzk.SubscribeChatEvent(ctx, socket.SessionKey()); err != nil {
        return err
    }

    <-socket.Done()
    socket.Close()
}

서버가 구독을 취소하면 OnSystem으로 revoked 시스템 이벤트가 전달됩니다. 이 경우 연결은 살아 있지만 해당 이벤트는 더 이상 오지 않으므로 다시 구독해야 합니다.

이벤트 시각

eventSentAt은 오프셋 표기 없이 KST로 전달되므로 EventTime이 이를 해석합니다. ChatEvent.MessageTime은 epoch 밀리초(UTC)이며 MessageAt()으로 변환합니다. 채팅 블라인드에 필요한 값은 BlindRequest()로 바로 만들 수 있습니다.

s.OnChat(func(e chzzkgo.ChatEvent) {
    if strings.Contains(e.Content, "금지어") {
        chzzk.BlindChatMessage(ctx, e.BlindRequest())
    }
})

다른 채널 토큰으로 호출

세션 이벤트 구독 등에서 다른 계정의 액세스 토큰을 일시적으로 사용할 수 있습니다.

ctx := chzzkgo.WithAccessToken(context.Background(), otherChannelToken)
err := chzzk.SubscribeChatEvent(ctx, sessionKey)

다중 계정을 다룰 때는 계정당 Client 하나를 사용하는 것이 기본 방침이며, 토큰 오버라이드는 위와 같은 특수 케이스 전용입니다.

에러 처리

user, err := chzzk.GetUser(ctx)

var apiErr *chzzkgo.APIError
var missing *chzzkgo.MissingScopeError

switch {
case errors.Is(err, chzzkgo.ErrNotAuthenticated):
    // 토큰 미설정 — OAuth 로그인 필요
case errors.As(err, &missing):
    // 권한 부족: missing.Scope
case errors.As(err, &apiErr):
    // 서버 오류: apiErr.StatusCode, apiErr.Code, apiErr.Message
}

알려진 제한

구독 이벤트는 미검증입니다

SubscriptionEvent 구조체는 공식 문서만을 근거로 정의했습니다. 구독 기능이 치지직 프로 회원에게만 열려 있어 실제 페이로드를 관측하지 못했고, 스튜디오의 구독 알림 테스트는 후원 알림과 달리 세션 소켓으로 전달되지 않습니다.

문서의 타입 표기가 실제와 다른 전례가 있으므로(후원의 payAmount는 문서상 문자열이지만 실제로는 숫자입니다) 값이 비어 있다면 OnAny로 원본을 확인하세요.

드롭스 API는 미구현입니다

Testing

go test ./...            # 오프라인 테스트 — 네트워크·계정 불필요, 로컬 mock 서버 사용
go test -tags live ./... # 라이브 스모크 — .test.env에 CLIENT_ID 등 필요 (미설정 시 skip)

기본 빌드에는 라이브 테스트가 포함되지 않으므로 go test ./...는 항상 안전합니다.

License

MIT

Documentation

Index

Constants

View Source 
const (
	// ChatAvailableConditionNone은 채팅 허용 조건 없음이다.
	ChatAvailableConditionNone ChatAvailableCondition = "NONE"
	// ChatAvailableConditionRealName은 실명인증 사용자만 채팅을 허용한다.
	ChatAvailableConditionRealName ChatAvailableCondition = "REAL_NAME"

	// ChatAvailableGroupAll은 전체 사용자에게 채팅을 허용한다.
	ChatAvailableGroupAll ChatAvailableGroup = "ALL"
	// ChatAvailableGroupFollower는 팔로워에게만 채팅을 허용한다.
	ChatAvailableGroupFollower ChatAvailableGroup = "FOLLOWER"
	// ChatAvailableGroupManager는 관리자에게만 채팅을 허용한다.
	ChatAvailableGroupManager ChatAvailableGroup = "MANAGER"
	// ChatAvailableGroupSubscriber는 구독자에게만 채팅을 허용한다.
	ChatAvailableGroupSubscriber ChatAvailableGroup = "SUBSCRIBER"
)

Variables

View Source 
var ErrNotAuthenticated = errors.New("chzzkgo: not authenticated, please complete OAuth flow first")

ErrNotAuthenticated는 OAuth 토큰이 필요한 API를 토큰 없이 호출했을 때 반환된다.

View Source 
var ErrSessionClosed = errors.New("chzzkgo: session socket closed")

ErrSessionClosed는 세션 소켓이 닫힌 뒤에 사용하려 할 때 반환된다.

Functions

func WithAccessToken 

func WithAccessToken(ctx context.Context, accessToken string) context.Context

WithAccessToken은 반환된 context로 실행되는 요청에 한해 클라이언트에 설정된 토큰 대신 강제 지정한 액세스 토큰을 사용한다.

Client 인증으로 발급받은 세션 키에 다른 채널의 토큰으로 이벤트를 구독하는 경우 등에 사용한다. Client.SubscribeChatEvent, Client.SubscribeDonationEvent, Client.SubscribeSubscriptionEvent 참고.

이 토큰의 Scope 검증은 서버에서 수행되며, 권한 부족 시 서버 오류가 반환된다.

Types

type APIError 

type APIError struct {
	// StatusCode는 HTTP 상태 코드이다.
	StatusCode int
	// Code는 응답 본문에 포함된 치지직 API 오류 코드이다.
	Code int
	// Message는 응답 본문에 포함된 오류 메시지이다.
	Message string
	// Path는 요청한 API 경로이다.
	Path string
	// Method는 요청한 HTTP 메서드이다.
	Method string
}

APIError는 치지직 Open API가 2xx 외의 상태 코드를 반환했을 때의 오류이다.

func (*APIError) Error 

func (e *APIError) Error() string

type Category 

type Category struct {
	// 카테고리 타입. [CategoryType] 상수 참고.
	CategoryType CategoryType `json:"categoryType"`
	// 내부 카테고리 ID, 영문/숫자/특수문자 조합
	CategoryID string `json:"categoryId"`
	// 한국어로 표시되는 카테고리 이름
	CategoryValue string `json:"categoryValue"`
	// 카테고리 포스트 이미지 URL
	PosterImageURL string `json:"posterImageUrl"`
}

Category는 치지직에서 사용되는 카테고리 정보를 나타낸다.

type CategoryPages 

type CategoryPages struct {
	// 카테고리 정보 목록
	Data []Category `json:"data"`
}

CategoryPages는 카테고리 검색 결과를 담는 구조체이다.

type CategoryType 

type CategoryType string

CategoryType은 카테고리의 유형을 나타낸다. 

const (
	// CategoryTypeGame은 게임 카테고리이다.
	CategoryTypeGame CategoryType = "GAME"
	// CategoryTypeSports는 스포츠 카테고리이다.
	CategoryTypeSports CategoryType = "SPORTS"
	// CategoryTypeEtc는 기타 카테고리이다.
	CategoryTypeEtc CategoryType = "ETC"
)

type Channel 

type Channel struct {
	// 치지직 채널 ID (예: c42cd75ec4855a9edf204a407c3c1dd2)
	ChannelID string `json:"channelId"`
	// 치지직 채널 이름 (예: 치지직)
	ChannelName string `json:"channelName"`
	// 치지직 채널 이미지 URL
	ChannelImageURL string `json:"channelImageUrl"`
	// 치지직 채널 팔로워 수
	FollowerCount int `json:"followerCount"`
	// 채널 인증 마크 여부
	VerifiedMark bool `json:"verifiedMark"`
}

Channel은 치지직에서 사용되는 채널 정보를 나타낸다.

type ChannelFollower 

type ChannelFollower struct {
	// 팔로워 채널 ID
	ChannelID string `json:"channelId"`
	// 팔로워 채널 이름
	ChannelName string `json:"channelName"`
	// 팔로우 일자
	CreatedDate string `json:"createdDate"`
}

ChannelFollower는 치지직에서 사용되는 채널 팔로워 정보를 나타낸다.

type ChannelFollowerPages 

type ChannelFollowerPages struct {
	// 채널 팔로워 정보 목록
	Data []ChannelFollower `json:"data"`
	// 현재 페이지 번호
	Page int `json:"page"`
	// 총 팔로워 수
	TotalCount int `json:"totalCount"`
	// 총 페이지 수
	TotalPages int `json:"totalPages"`
}

ChannelFollowerPages는 채널 팔로워 검색 결과를 담는 구조체이다.

type ChannelPages 

type ChannelPages struct {
	// 채널 정보 목록
	Data []Channel `json:"data"`
}

ChannelPages는 채널 검색 결과를 담는 구조체이다.

type ChannelSubscriber 

type ChannelSubscriber struct {
	// 구독자 채널 ID
	ChannelID string `json:"channelId"`
	// 구독자 채널 이름
	ChannelName string `json:"channelName"`
	// 구독 기간 (개월)
	Month int `json:"month"`
	// 구독 티어 (1, 2)
	TierNo int `json:"tierNo"`
	// 구독 일자
	CreatedDate string `json:"createdDate"`
}

ChannelSubscriber는 치지직에서 사용되는 채널 구독자 정보를 나타낸다.

type ChannelSubscriberPages 

type ChannelSubscriberPages struct {
	// 채널 구독자 정보 목록
	Data []ChannelSubscriber `json:"data"`
	// 현재 페이지 번호
	Page int `json:"page"`
	// 총 구독자 수
	TotalCount int `json:"totalCount"`
	// 총 페이지 수
	TotalPages int `json:"totalPages"`
}

ChannelSubscriberPages는 채널 구독자 검색 결과를 담는 구조체이다.

type ChatAvailableCondition 

type ChatAvailableCondition string

ChatAvailableCondition은 채팅 허용 조건을 나타낸다.

type ChatAvailableGroup 

type ChatAvailableGroup string

ChatAvailableGroup은 채팅 허용 그룹을 나타낸다.

type ChatBadge added in v0.3.0 

type ChatBadge struct {
	// 뱃지 이미지 URL
	ImageURL string `json:"imageUrl"`
}

ChatBadge는 채팅 발신자에게 표시되는 뱃지이다.

type ChatBlindRequest 

type ChatBlindRequest struct {
	// 채팅 채널 ID
	ChatChannelID string `json:"chatChannelId"`
	// 메시지 전송 시간 (long, milliseconds)
	MessageTime int64 `json:"messageTime"`
	// 발신자 채널 ID
	SenderChannelID string `json:"senderChannelId"`
}

ChatBlindRequest는 채팅 블라인드 요청 정보를 나타낸다.

type ChatEvent added in v0.3.0 

type ChatEvent struct {
	// 이벤트가 발생한 채널 ID
	ChannelID string `json:"channelId"`
	// 채팅 채널 ID. 채팅 블라인드와 임시 제한에 사용한다.
	ChatChannelID string `json:"chatChannelId"`
	// 발신자 채널 ID
	SenderChannelID string `json:"senderChannelId"`
	// 발신자 프로필
	Profile ChatProfile `json:"profile"`
	// 채팅 메시지 내용
	Content string `json:"content"`
	// 사용된 이모티콘. 이모티콘 ID를 이미지 URL에 대응시킨다.
	Emojis map[string]string `json:"emojis"`
	// 메시지 전송 시각. epoch 밀리초(UTC)이며 [ChatEvent.MessageAt]으로 변환할 수 있다.
	// 채팅 블라인드에 이 값이 그대로 필요하므로 원본을 유지한다.
	MessageTime int64 `json:"messageTime"`
	// 서버가 이벤트를 보낸 시각. 공식 문서에는 없다.
	EventSentAt EventTime `json:"eventSentAt"`
}

ChatEvent는 세션에서 수신한 채팅 이벤트이다.

func (ChatEvent) BlindRequest added in v0.3.0 

func (e ChatEvent) BlindRequest() ChatBlindRequest

BlindRequest는 이 채팅을 블라인드 처리하기 위한 요청을 만든다. [Client.BlindChatMessage]에 그대로 전달할 수 있다.

func (ChatEvent) MessageAt added in v0.3.0 

func (e ChatEvent) MessageAt() time.Time

MessageAt은 [ChatEvent.MessageTime]을 KST 기준 시각으로 변환해 반환한다.

type ChatNoticeRequest 

type ChatNoticeRequest struct {
	// 채팅 공지 메시지 내용
	Message string `json:"message"`
	// 채팅 공지 메시지 ID
	MessageID string `json:"messageId"`
}

ChatNoticeRequest는 채팅 공지 설정 요청 정보를 나타낸다.

type ChatProfile added in v0.3.0 

type ChatProfile struct {
	// 발신자 닉네임
	Nickname string `json:"nickname"`
	// 발신자 채널의 인증 마크 여부
	VerifiedMark bool `json:"verifiedMark"`
	// 발신자에게 표시되는 뱃지 목록
	Badges []ChatBadge `json:"badges"`
	// 발신자 역할. [UserRoleCode] 상수 참고.
	//
	// 공식 문서는 이 필드를 최상위에 두고 있으나 실제 응답에서는 프로필 안에 있다.
	UserRoleCode UserRoleCode `json:"userRoleCode"`
}

ChatProfile은 채팅 발신자의 프로필 정보이다.

type ChatSettings 

type ChatSettings struct {
	// 채팅 허용 조건, [ChatAvailableCondition] 참고
	ChatAvailableCondition ChatAvailableCondition `json:"chatAvailableCondition"`
	// 채팅 허용 그룹, [ChatAvailableGroup] 참고
	ChatAvailableGroup ChatAvailableGroup `json:"chatAvailableGroup"`
	// 최소 채널 팔로우 시간(분), 0이면 제한 없음
	MinFollowerMinute int `json:"minFollowerMinute"`
	// 팔로워 전용 모드에서 구독자 채팅 허용 여부
	AllowSubscriberInFollowerMode bool `json:"allowSubscriberInFollowerMode"`
	// 채팅 슬로우 모드 시간(초), 0이면 제한 없음
	ChatSlowModeSec int `json:"chatSlowModeSec"`
	// 채팅 이모지 전용 모드 여부
	ChatEmojiMode bool `json:"chatEmojiMode"`
}

ChatSettings는 조회된 채팅 설정 정보를 나타낸다.

type ChatSettingsPatch 

type ChatSettingsPatch struct {
	// 채팅 허용 조건, [ChatAvailableCondition] 참고
	ChatAvailableCondition *ChatAvailableCondition `json:"chatAvailableCondition,omitempty"`
	// 채팅 허용 그룹, [ChatAvailableGroup] 참고
	ChatAvailableGroup *ChatAvailableGroup `json:"chatAvailableGroup,omitempty"`
	// 최소 채널 팔로우 시간(분), 0이면 제한 없음.
	// 허용 값: 0, 5, 10, 30, 60, 1440, 10080, 43200, 86400, 129600, 172800, 216000, 259200
	MinFollowerMinute *int `json:"minFollowerMinute,omitempty"`
	// 팔로워 전용 모드에서 구독자 채팅 허용 여부
	AllowSubscriberInFollowerMode *bool `json:"allowSubscriberInFollowerMode,omitempty"`
	// 채팅 슬로우 모드 시간(초), 0이면 제한 없음.
	// 허용 값: 0, 3, 5, 10, 30, 60, 120, 300
	ChatSlowModeSec *int `json:"chatSlowModeSec,omitempty"`
	// 채팅 이모지 전용 모드 여부
	ChatEmojiMode *bool `json:"chatEmojiMode,omitempty"`
}

ChatSettingsPatch는 [Client.SetChatSettings]로 변경할 채팅 설정 정보를 나타낸다.

nil인 필드는 요청에서 제외되어 변경되지 않는다. 값 지정에는 내장 함수 new를 사용할 수 있다. (예: new(true))

type Client added in v0.4.0 

type Client struct {
	// ClientID는 치지직 개발자 센터에서 발급받은 클라이언트 ID이다.
	ClientID string
	// ClientSecret은 치지직 개발자 센터에서 발급받은 클라이언트 시크릿이다.
	ClientSecret string
	// RedirectURI는 애플리케이션에 등록한 OAuth 리디렉션 URI이다.
	RedirectURI string
	// contains filtered or unexported fields
}

Client는 치지직 Open API 호출을 위한 클라이언트이다.

[New]로 생성한다. OAuth 토큰이 필요한 API를 호출하려면 [Client.SetTokens]로 토큰을 주입하거나 [LoginServer]를 통해 로그인해야 한다. 토큰의 저장과 복원은 사용자 책임이며, 갱신된 토큰은 Client.OnTokenRefresh 콜백으로 전달받아 저장할 수 있다.

func New added in v0.4.0 

func New(clientID, clientSecret, redirectURI string) *Client

New는 새 [Client]를 생성한다.

clientID와 clientSecret은 치지직 개발자 센터에서 발급받은 값을, redirectURI는 애플리케이션에 등록한 리디렉션 URI를 전달한다.

func NewWithoutAuth added in v0.4.0 

func NewWithoutAuth() *Client

NewWithoutAuth는 자격 증명 없이 새 [Client]를 생성한다.

이미 액세스 토큰을 가지고 있어 세션 발급 정도만 하면 되는 경우처럼, [New]에 넘길 값이 마땅치 않을 때 클라이언트를 빠르게 만드는 용도이다. 필요한 값은 ClientID 등의 필드에 직접 채우거나 Client.SetTokens, [Client.SetAccessToken]으로 주입한다.

채우지 않은 값에 의존하는 API는 호출할 수 없다. 액세스 토큰만 주입한 상태라면 Client 인증 API(ClientID/ClientSecret 필요)와 자동 토큰 갱신(리프레시 토큰 필요)은 동작하지 않는다.

func (*Client) AddRestriction added in v0.4.0 

func (c *Client) AddRestriction(ctx context.Context, targetChannelID string) error

AddRestriction은 targetChannelId에 대해 활동 제한을 추가한다.

RestrictionWrite(활동제한 쓰기) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) AddTemporaryRestriction added in v0.4.0 

func (c *Client) AddTemporaryRestriction(ctx context.Context, targetChannelID, chatChannelID string) error

AddTemporaryRestriction은 targetChannelId에 대해 임시 제한을 추가한다.

임시 제한을 위해서는 chatChannelID(채팅 채널 ID)가 필요하다. 이는 Session의 채팅 구독 이벤트 메시지 값에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#message-event-subscribe-chat)

RestrictionWrite(활동제한 쓰기) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) BlindChatMessage added in v0.4.0 

func (c *Client) BlindChatMessage(ctx context.Context, req ChatBlindRequest) error

BlindChatMessage는 특정 채팅 메시지를 블라인드 처리한다.

req에는 블라인드 처리할 채팅 메시지의 정보를 담은 ChatBlindRequest 구조체를 전달한다.

채팅 블라인드를 위해서는 채팅 채널 ID(ChatChannelID), 메시지 전송 시간(MessageTime), 발신자 채널 ID(SenderChannelID)가 필요하다. 이는 Session의 채팅 구독 이벤트 메시지 값에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#message-event-subscribe-chat)

ChatMessageWrite(채팅 메시지 쓰기) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) ConnectSessionWithClient added in v0.4.0 

func (c *Client) ConnectSessionWithClient(ctx context.Context, setup func(*SessionSocket), opts ...SessionSocketOption) (*SessionSocket, error)

ConnectSessionWithClient는 클라이언트 인증으로 세션을 새로 발급받아 소켓을 연결한다.

Client 인증을 사용하므로 OAuth 토큰 없이 호출 가능하다. setup은 접속 전에 호출되므로 여기에서 핸들러를 등록한다. Client.ConnectSessionWithUser 참고.

func (*Client) ConnectSessionWithUser added in v0.4.0 

func (c *Client) ConnectSessionWithUser(ctx context.Context, setup func(*SessionSocket), opts ...SessionSocketOption) (*SessionSocket, error)

ConnectSessionWithUser는 사용자 인증으로 세션을 새로 발급받아 소켓을 연결한다.

setup은 접속 전에 호출되므로 여기에서 핸들러를 등록한다. 연결이 끊긴 뒤 다시 붙을 때도 이 함수를 다시 호출하면 된다. 세션 URL은 한 번만 쓸 수 있어 같은 URL로 재접속할 수 없기 때문이다. 

register := func(s *chzzkgo.SessionSocket) {
	s.OnChat(func(e chzzkgo.ChatEvent) { ... })
}

for {
	socket, err := chzzk.ConnectSessionWithUser(ctx, register)
	if err != nil {
		return err
	}

	if err := chzzk.SubscribeChatEvent(ctx, socket.SessionKey()); err != nil {
		return err
	}

	<-socket.Done()
}

func (*Client) CreateSessionWithClient added in v0.4.0 

func (c *Client) CreateSessionWithClient(ctx context.Context) (*SessionURLResponse, error)

CreateSessionWithClient은 클라이언트 인증 방식으로 세션을 생성하고, 세션 URL을 반환한다.

Client 인증을 사용하므로 OAuth 토큰 없이 호출 가능하다.

func (*Client) CreateSessionWithUser added in v0.4.0 

func (c *Client) CreateSessionWithUser(ctx context.Context) (*SessionURLResponse, error)

CreateSessionWithUser은 사용자 인증 방식으로 세션을 생성하고, 세션 URL을 반환한다.

func (*Client) ExchangeCode added in v0.4.0 

func (c *Client) ExchangeCode(ctx context.Context, code, state string) (*Tokens, error)

ExchangeCode는 OAuth 리디렉션으로 전달받은 인증 코드를 토큰으로 교환하여 반환한다.

반환된 토큰은 클라이언트에 자동으로 주입되지 않는다. 이 클라이언트로 API를 호출하려면 [Client.SetTokens]로 직접 주입해야 한다. state의 생성과 검증은 호출자가 관리한다.

func (*Client) GetAuthorizationURL added in v0.4.0 

func (c *Client) GetAuthorizationURL(state string) string

GetAuthorizationURL은 사용자를 이동시킬 치지직 OAuth 인증 페이지 URL을 반환한다.

state는 CSRF 방지를 위한 값으로, 호출자가 생성하고 리디렉션 시 검증해야 한다.

func (*Client) GetChannelFollowers added in v0.4.0 

func (c *Client) GetChannelFollowers(ctx context.Context, opts ...QueryOption) (*ChannelFollowerPages, error)

GetChannelFollowers는 현재 인증된 사용자의 채널 팔로워 정보를 조회한다.

ChannelInfoRead(채널 정보 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

선택적 파라미터로 size, page를 지정할 수 있다. WithSize, [WithPage]를 참고. size가 지정되지 않았다면 서버에서 기본값 30을 사용하며, 최소 1에서 최대 50까지 지정 가능하다. page는 0부터 시작하며, 지정되지 않았다면 서버에서 기본값 0을 사용한다.

func (*Client) GetChannelManagers added in v0.4.0 

func (c *Client) GetChannelManagers(ctx context.Context) (*StreamingRolePages, error)

GetChannelManagers는 현재 인증된 사용자의 채널 관리자 정보를 조회한다.

ChannelManagerRead(채널 관리자 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) GetChannelSubscribers added in v0.4.0 

func (c *Client) GetChannelSubscribers(ctx context.Context, opts ...QueryOption) (*ChannelSubscriberPages, error)

GetChannelSubscribers는 현재 인증된 사용자의 채널 구독자 정보를 조회한다.

ChannelInfoRead(채널 정보 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

선택적 파라미터로 size를 지정할 수 있다. [WithSize]를 참고. size가 지정되지 않았다면 서버에서 기본값 30을 사용하며, 최소 1에서 최대 50까지 지정 가능하다.

func (*Client) GetChannels added in v0.4.0 

func (c *Client) GetChannels(ctx context.Context, channelIDs []string) (*ChannelPages, error)

GetChannels는 입력된 channelIDs에 대해 채널 정보를 조회한다.

조회를 원하는 채널 ID들이 포함된 channelIDs가 필요하다. channelIDs는 최대 20개까지 요청 가능하다.

Client 인증을 사용하므로 OAuth 토큰 없이 호출 가능하다.

func (*Client) GetChatSettings added in v0.4.0 

func (c *Client) GetChatSettings(ctx context.Context) (*ChatSettings, error)

GetChatSettings는 채팅 설정 정보를 조회한다.

ChatSettingsRead(채팅 설정 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) GetLiveList added in v0.4.0 

func (c *Client) GetLiveList(ctx context.Context, opts ...QueryOption) (*LivePages, error)

GetLiveList는 현재 치지직에 존재하는 생방송 목록을 조회한다.

Client 인증을 사용하므로 OAuth 토큰 없이 호출 가능하다. 선택적 파라미터로 size, next를 지정할 수 있다. WithSize, [WithNext]를 참고. size의 경우, 지정되지 않았다면 서버에서 기본값 20을 사용하며, 최소 1에서 최대 20까지 지정 가능하다.

func (*Client) GetLiveSettings added in v0.4.0 

func (c *Client) GetLiveSettings(ctx context.Context) (*LiveSettings, error)

GetLiveSettings는 방송 설정 정보를 조회한다.

LiveSettingRead(방송 설정 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) GetRestrictions added in v0.4.0 

func (c *Client) GetRestrictions(ctx context.Context, opts ...QueryOption) (*RestrictionPages, error)

GetRestrictions는 활동 제한된 채널 목록을 조회한다.

RestrictionRead(활동제한 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다. 선택적 파라미터로 size, next를 지정할 수 있다. WithSize, [WithNext]를 참고. size의 경우, 지정되지 않았다면 서버에서 기본값 30을 사용하며, 최소 1에서 최대 30까지 지정 가능하다.

func (*Client) GetSessionsWithClient added in v0.4.0 

func (c *Client) GetSessionsWithClient(ctx context.Context, opts ...QueryOption) (*SessionPages, error)

GetSessionsWithClient은 클라이언트 인증 방식으로 세션 목록을 조회한다.

Client 인증을 사용하므로 OAuth 토큰 없이 호출 가능하다. 선택적 파라미터로 size, page를 지정할 수 있다. WithSize, [WithPage]를 참고. size의 경우, 지정되지 않았다면 서버에서 기본값 20을 사용하며, 최소 1에서 최대 50까지 지정 가능하다. page는 0부터 시작하며, 지정되지 않았다면 서버에서 기본값 0을 사용한다.

func (*Client) GetSessionsWithUser added in v0.4.0 

func (c *Client) GetSessionsWithUser(ctx context.Context, opts ...QueryOption) (*SessionPages, error)

GetSessionsWithUser는 사용자 인증 방식으로 세션 목록을 조회한다.

선택적 파라미터로 size, page를 지정할 수 있다. WithSize, [WithPage]를 참고. size의 경우, 지정되지 않았다면 서버에서 기본값 20을 사용하며, 최소 1에서 최대 50까지 지정 가능하다. page는 0부터 시작하며, 지정되지 않았다면 서버에서 기본값 0을 사용한다.

func (*Client) GetStreamKey added in v0.4.0 

func (c *Client) GetStreamKey(ctx context.Context) (*LiveStreamKey, error)

GetStreamKey는 방송 스트림 키를 조회한다.

LiveStreamKeyRead(방송 스트림키 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) GetUser added in v0.4.0 

func (c *Client) GetUser(ctx context.Context) (*User, error)

GetUser는 현재 인증된 사용자의 정보를 조회한다.

UserRead(유저 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) NewLoginServer added in v0.4.0 

func (c *Client) NewLoginServer(opts ...LoginServerOption) *LoginServer

NewLoginServer는 새 [LoginServer]를 생성한다.

기본값은 일회용 모드로, 첫 로그인 성공 시 서버가 종료되고 발급된 토큰이 클라이언트에 주입된다. 상시 모드는 [WithKeepAlive]를 참고.

func (*Client) OnTokenRefresh added in v0.4.0 

func (c *Client) OnTokenRefresh(callback func(Tokens))

OnTokenRefresh는 자동 토큰 갱신 성공 시 새 토큰을 전달받을 콜백을 등록한다.

갱신된 토큰을 저장소에 반영하는 용도로 사용한다. 콜백은 별도 goroutine에서 호출되므로 클라이언트 메서드를 자유롭게 호출할 수 있다.

func (*Client) RemoveRestriction added in v0.4.0 

func (c *Client) RemoveRestriction(ctx context.Context, targetChannelID string) error

RemoveRestriction은 targetChannelId에 대해 활동 제한을 해제한다.

RestrictionWrite(활동제한 쓰기) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) RemoveTemporaryRestriction added in v0.4.0 

func (c *Client) RemoveTemporaryRestriction(ctx context.Context, targetChannelID, chatChannelID string) error

RemoveTemporaryRestriction은 targetChannelId에 대해 임시 제한을 해제한다.

임시 제한 해제를 위해서는 chatChannelID(채팅 채널 ID)가 필요하다. 이는 Session의 채팅 구독 이벤트 메시지 값에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#message-event-subscribe-chat)

RestrictionWrite(활동제한 쓰기) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) RequestToken added in v0.4.0 

func (c *Client) RequestToken(ctx context.Context, body TokenRequest) (*Tokens, error)

RequestToken은 토큰 발급/갱신 API를 직접 호출한다.

일반적으로는 [Client.ExchangeCode]와 자동 토큰 갱신을 사용하면 되며, 발급 흐름을 직접 제어해야 하는 경우에만 사용한다.

func (*Client) RevokeToken added in v0.4.0 

func (c *Client) RevokeToken(ctx context.Context, body RevokeTokenRequest) error

RevokeToken은 Access Token 또는 Refresh Token을 제거한다.

body에는 제거할 토큰(Token)과 토큰 종류(TokenTypeHint)를 담은 [RevokeTokenRequest]를 전달한다. ClientID와 ClientSecret이 비어 있으면 클라이언트에 설정된 값이 자동으로 채워진다. 제거된 토큰은 더 이상 API 호출에 사용할 수 없으며, 리프레시 토큰 제거 시 액세스 토큰도 함께 무효화된다.

func (*Client) SearchCategory added in v0.4.0 

func (c *Client) SearchCategory(ctx context.Context, query string, opts ...QueryOption) (*CategoryPages, error)

SearchCategory는 입력된 query에 대해 카테고리 정보를 검색한다.

Client 인증을 사용하므로 OAuth 토큰 없이 호출 가능하다. 선택적 파라미터로 size를 지정할 수 있다. [WithSize]를 참고. size가 지정되지 않았다면 서버에서 기본값 20을 사용하며, 최소 1에서 최대 50까지 지정 가능하다.

func (*Client) SendChatMessage added in v0.4.0 

func (c *Client) SendChatMessage(ctx context.Context, message string) (*MessageResult, error)

SendChatMessage는 채팅 메시지를 전송한다.

message에는 전송할 채팅 메시지를 담은 문자열을 전달한다. 메시지 길이는 최대 100자까지 허용된다.

ChatMessageWrite(채팅 메시지 쓰기) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) SetAccessToken added in v0.4.0 

func (c *Client) SetAccessToken(accessToken string)

SetAccessToken은 클라이언트가 API 호출에 사용할 Access Token 데이터만을 주입한다.

func (*Client) SetBaseURL added in v0.4.0 

func (c *Client) SetBaseURL(u string)

SetBaseURL은 API 요청의 기본 URL을 교체한다. 테스트 서버나 프록시를 경유할 때 사용하며, 기본값은 https://openapi.chzzk.naver.com 이다. API 호출을 시작하기 전에 설정해야 한다.

func (*Client) SetChatNotice added in v0.4.0 

func (c *Client) SetChatNotice(ctx context.Context, req ChatNoticeRequest) error

SetChatNotice는 채팅 공지를 설정한다.

req에는 채팅 공지 메시지 내용과 메시지 ID를 담은 ChatNoticeRequest 구조체를 전달한다. 구조체 내의 필드 중 최소한 하나는 설정되어야 한다.

Message를 지정할 경우 채팅 공지 메시지 내용을 새로 전송하여 설정하고, MessageID를 지정할 경우 이미 전송된 채팅 메시지를 공지로 설정한다. 두 필드 모두 설정하지 않으면 에러를 반환한다.

ChatNoticeWrite(채팅 공지 쓰기) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) SetChatSettings added in v0.4.0 

func (c *Client) SetChatSettings(ctx context.Context, newChatSettings ChatSettingsPatch) (*ChatSettings, error)

SetChatSettings는 채팅 설정 정보를 변경한다.

newChatSettings에는 변경할 채팅 설정 정보를 담은 ChatSettingsPatch 구조체를 전달한다. nil 필드는 전송되지 않으며, 서버는 전송되지 않은 필드의 기존 값을 유지한다.

ChatSettingsWrite(채팅 설정 변경) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) SetLiveSettings added in v0.4.0 

func (c *Client) SetLiveSettings(ctx context.Context, settings LiveSettingsPatch) error

SetLiveSettings는 방송 설정 정보를 변경한다.

settings에는 변경할 방송 설정 정보를 담은 LiveSettingsPatch 구조체를 전달한다. nil인 필드는 요청에서 제외되어 변경되지 않는다.

LiveSettingWrite(방송 설정 변경) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

func (*Client) SetLogger added in v0.4.0 

func (c *Client) SetLogger(l *slog.Logger)

SetLogger는 클라이언트 내부 동작(토큰 갱신 등)을 기록할 로거를 설정한다. 설정하지 않으면 아무것도 기록하지 않는다.

func (*Client) SetRefreshToken added in v0.4.0 

func (c *Client) SetRefreshToken(refreshToken string)

SetRefreshToken은 클라이언트가 API 호출에 사용할 Refresh Token 데이터만을 주입한다.

func (*Client) SetScopes added in v0.5.0 

func (c *Client) SetScopes(scope Scopes)

SetScopes는 클라이언트가 API 호출에 사용할 Scope 데이터만을 주입한다.

func (*Client) SetTokens added in v0.4.0 

func (c *Client) SetTokens(accessToken, refreshToken string, scope Scopes)

SetTokens은 클라이언트가 API 호출에 사용할 인증 토큰 데이터를 주입한다.

저장해 둔 토큰을 복원하거나 [Client.ExchangeCode]로 발급받은 토큰을 등록할 때 사용한다. scope는 토큰 발급 시 부여된 권한 목록을 전달한다.

func (*Client) SubscribeChatEvent added in v0.4.0 

func (c *Client) SubscribeChatEvent(ctx context.Context, sessionKey string) error

SubscribeChatEvent는 세션에서 채팅 이벤트를 구독한다.

이벤트 구독을 위해서는 세션 키(sessionKey)가 필요하다. 해당 값은 세션 생성 시 반환되는 URL에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined) (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined-1)

ChatMessageRead(채팅 메시지 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

세션 구독 Event의 경우, Client 인증 방식일 경우 다른 사람의 Access Token을 사용하여 호출 해 타 채널의 이벤트를 구독할 수 있다. 따라서, Client 인증 방식으로 호출 시 타 채널의 이벤트를 구독하고 싶은 경우 Access Token을 Override하여 호출하는 것을 권장한다. WithAccessToken 참고. 

chzzkgo.SubscribeChatEvent(ctx, sessionKey) // 현재 인증된 사용자의 채팅 이벤트 구독

chzzkgo.SubscribeChatEvent(chzzkgo.WithAccessToken(ctx, otherChannelToken), sessionKey) // 다른 채널의 채팅 이벤트 구독

func (*Client) SubscribeDonationEvent added in v0.4.0 

func (c *Client) SubscribeDonationEvent(ctx context.Context, sessionKey string) error

SubscribeDonationEvent는 세션에서 후원 이벤트를 구독한다.

이벤트 구독을 위해서는 세션 키(sessionKey)가 필요하다. 해당 값은 세션 생성 시 반환되는 URL에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined) (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined-1)

DonationRead(후원 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

세션 구독 Event의 경우, Client 인증 방식일 경우 다른 사람의 Access Token을 사용하여 호출 해 타 채널의 이벤트를 구독할 수 있다. 따라서, Client 인증 방식으로 호출 시 타 채널의 이벤트를 구독하고 싶은 경우 Access Token을 Override하여 호출하는 것을 권장한다. WithAccessToken 참고. 

chzzkgo.SubscribeDonationEvent(ctx, sessionKey) // 현재 인증된 사용자의 후원 이벤트 구독

chzzkgo.SubscribeDonationEvent(chzzkgo.WithAccessToken(ctx, otherChannelToken), sessionKey) // 다른 채널의 후원 이벤트 구독

func (*Client) SubscribeSubscriptionEvent added in v0.4.0 

func (c *Client) SubscribeSubscriptionEvent(ctx context.Context, sessionKey string) error

SubscribeSubscriptionEvent는 세션에서 구독 이벤트를 구독한다.

이벤트 구독을 위해서는 세션 키(sessionKey)가 필요하다. 해당 값은 세션 생성 시 반환되는 URL에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined) (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined-1)

SubscriptionRead(구독 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

세션 구독 Event의 경우, Client 인증 방식일 경우 다른 사람의 Access Token을 사용하여 호출 해 타 채널의 이벤트를 구독할 수 있다. 따라서, Client 인증 방식으로 호출 시 타 채널의 이벤트를 구독하고 싶은 경우 Access Token을 Override하여 호출하는 것을 권장한다. WithAccessToken 참고. 

chzzkgo.SubscribeSubscriptionEvent(ctx, sessionKey) // 현재 인증된 사용자의 구독 이벤트 구독

chzzkgo.SubscribeSubscriptionEvent(chzzkgo.WithAccessToken(ctx, otherChannelToken), sessionKey) // 다른 채널의 구독 이벤트 구독

func (*Client) UnsubscribeChatEvent added in v0.4.0 

func (c *Client) UnsubscribeChatEvent(ctx context.Context, sessionKey string) error

UnsubscribeChatEvent는 세션에서 채팅 이벤트 구독을 해제한다.

이벤트 구독 해제를 위해서는 세션 키(sessionKey)가 필요하다. 해당 값은 세션 생성 시 반환되는 URL에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined) (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined-1)

ChatMessageRead(채팅 메시지 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

세션 구독 Event의 경우, Client 인증 방식일 경우 다른 사람의 Access Token을 사용하여 호출 해 타 채널의 이벤트를 구독 해제할 수 있다. 따라서, Client 인증 방식으로 호출 시 타 채널의 이벤트를 구독 해제하고 싶은 경우 Access Token을 Override하여 호출하는 것을 권장한다. WithAccessToken 참고. 

chzzkgo.UnsubscribeChatEvent(ctx, sessionKey) // 현재 인증된 사용자의 채팅 이벤트 구독 해제

chzzkgo.UnsubscribeChatEvent(chzzkgo.WithAccessToken(ctx, otherChannelToken), sessionKey) // 다른 채널의 채팅 이벤트 구독 해제

func (*Client) UnsubscribeDonationEvent added in v0.4.0 

func (c *Client) UnsubscribeDonationEvent(ctx context.Context, sessionKey string) error

UnsubscribeDonationEvent는 세션에서 후원 이벤트 구독을 해제한다.

이벤트 구독 해제를 위해서는 세션 키(sessionKey)가 필요하다. 해당 값은 세션 생성 시 반환되는 URL에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined) (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined-1)

DonationRead(후원 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

세션 구독 Event의 경우, Client 인증 방식일 경우 다른 사람의 Access Token을 사용하여 호출 해 타 채널의 이벤트를 구독 해제할 수 있다. 따라서, Client 인증 방식으로 호출 시 타 채널의 이벤트를 구독 해제하고 싶은 경우 Access Token을 Override하여 호출하는 것을 권장한다. WithAccessToken 참고. 

chzzkgo.UnsubscribeDonationEvent(ctx, sessionKey) // 현재 인증된 사용자의 후원 이벤트 구독 해제

chzzkgo.UnsubscribeDonationEvent(chzzkgo.WithAccessToken(ctx, otherChannelToken), sessionKey) // 다른 채널의 후원 이벤트 구독 해제

func (*Client) UnsubscribeSubscriptionEvent added in v0.4.0 

func (c *Client) UnsubscribeSubscriptionEvent(ctx context.Context, sessionKey string) error

UnsubscribeSubscriptionEvent는 세션에서 구독 이벤트 구독을 해제한다.

이벤트 구독 해제를 위해서는 세션 키(sessionKey)가 필요하다. 해당 값은 세션 생성 시 반환되는 URL에서 확인할 수 있다. (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined) (https://chzzk.gitbook.io/chzzk/chzzk-api/session#undefined-1)

SubscriptionRead(구독 조회) [Scope]가 필요하며, 없으면 [MissingScopeError]를 반환한다.

세션 구독 Event의 경우, Client 인증 방식일 경우 다른 사람의 Access Token을 사용하여 호출 해 타 채널의 이벤트를 구독 해제할 수 있다. 따라서, Client 인증 방식으로 호출 시 타 채널의 이벤트를 구독 해제하고 싶은 경우 Access Token을 Override하여 호출하는 것을 권장한다. WithAccessToken 참고. 

chzzkgo.UnsubscribeSubscriptionEvent(ctx, sessionKey) // 현재 인증된 사용자의 구독 이벤트 구독 해제

chzzkgo.UnsubscribeSubscriptionEvent(chzzkgo.WithAccessToken(ctx, otherChannelToken), sessionKey) // 다른 채널의 구독 이벤트 구독 해제

type DonationEvent added in v0.3.0 

type DonationEvent struct {
	// 후원 종류. [DonationType] 상수 참고.
	DonationType DonationType `json:"donationType"`
	// 이벤트가 발생한 채널 ID
	ChannelID string `json:"channelId"`
	// 후원자 채널 ID
	DonatorChannelID string `json:"donatorChannelId"`
	// 후원자 닉네임
	DonatorNickname string `json:"donatorNickname"`
	// 후원 금액. 공식 문서는 문자열로 표기하고 있으나 실제 응답은 숫자이다.
	PayAmount int `json:"payAmount"`
	// 후원자가 입력한 메시지
	DonationText string `json:"donationText"`
	// 사용된 이모티콘. 이모티콘 ID를 이미지 URL에 대응시킨다.
	Emojis map[string]string `json:"emojis"`
	// 서버가 이벤트를 보낸 시각. 공식 문서에는 없다.
	EventSentAt EventTime `json:"eventSentAt"`
}

DonationEvent는 세션에서 수신한 후원 이벤트이다.

type DonationType added in v0.3.0 

type DonationType string

DonationType은 후원의 종류를 나타낸다. 

const (
	// DonationTypeChat은 채팅 후원이다.
	DonationTypeChat DonationType = "CHAT"
	// DonationTypeVideo는 영상 후원이다.
	DonationTypeVideo DonationType = "VIDEO"
)

type Event 

type Event string

Event는 세션에서 구독된 이벤트 종류를 나타낸다. 

const (
	// EventTypeChat은 채팅 이벤트이다.
	EventTypeChat Event = "CHAT"
	// EventTypeDonation은 후원 알림 이벤트이다.
	EventTypeDonation Event = "DONATION"
	// EventTypeSubscription은 구독 알림 이벤트이다.
	EventTypeSubscription Event = "SUBSCRIPTION"
)

type EventTime added in v0.3.0 

type EventTime struct {
	time.Time
}

EventTime은 세션 이벤트의 발신 시각을 나타낸다.

서버는 이 값을 "2026-07-26T03:14:18.629843820"처럼 오프셋 없이 보내지만 실제 기준은 KST이다. UTC로 해석하면 9시간이 어긋나며 파싱 단계에서 오류도 나지 않으므로, 이 타입이 언마샬 시 Asia/Seoul 위치를 지정한다.

func (EventTime) MarshalJSON added in v0.3.0 

func (t EventTime) MarshalJSON() ([]byte, error)

MarshalJSON은 서버가 보낸 것과 같은 형식의 KST 시각 문자열로 직렬화한다. 제로 값은 null로 표기한다.

func (*EventTime) UnmarshalJSON added in v0.3.0 

func (t *EventTime) UnmarshalJSON(b []byte) error

UnmarshalJSON은 시각 문자열을 해석한다.

오프셋이 붙어 있으면 그대로 따르고, 없을 때만 KST를 씌운다. null이나 빈 문자열은 제로 값으로 둔다.

type Events 

type Events struct {
	// 이벤트 종류, [Event] 참고
	EventType Event `json:"eventType"`
	// 이벤트 구독 대상 채널 ID
	ChannelID string `json:"channelId"`
}

Events는 세션에서 구독된 이벤트 정보를 나타낸다.

type Live 

type Live struct {
	// 생방송 ID
	LiveID int `json:"liveId"`
	// 생방송 제목
	LiveTitle string `json:"liveTitle"`
	// 생방송 썸네일 이미지 URL
	LiveThumbnailImageURL string `json:"liveThumbnailImageUrl"`
	// 동시 시청자 수
	ConcurrentUserCount int `json:"concurrentUserCount"`
	// 생방송 시작 날짜
	OpenDate string `json:"openDate"`
	// 연령 제한 방송 여부
	Adult bool `json:"adult"`
	// 생방송 태그. 지정되지 않은 경우 빈 배열
	Tags []string `json:"tags"`
	// 생방송 카테고리, [CategoryType] 참고. 지정되지 않은 경우 null
	CategoryType CategoryType `json:"categoryType,omitempty"`
	// 생방송 카테고리 ID, [Category.CategoryID]와 동일. 지정되지 않은 경우 null
	LiveCategory string `json:"liveCategory,omitempty"`
	// 생방송 카테고리 이름, [Category.CategoryValue]와 동일. 지정되지 않은 경우 null
	LiveCategoryValue string `json:"liveCategoryValue,omitempty"`
	// 생방송 채널 ID
	ChannelID string `json:"channelId"`
	// 생방송 채널 이름
	ChannelName string `json:"channelName"`
	// 생방송 채널 프로필 이미지 URL
	ChannelImageURL string `json:"channelImageUrl"`
}

Live는 치지직에서 사용되는 생방송 정보를 나타낸다.

type LivePages 

type LivePages struct {
	// 생방송 정보 목록
	Data []Live `json:"data"`
	// 다음 페이지 조회를 위한 구조체, 마지막 페이지인 경우 null
	Page struct {
		// 다음 페이지 조회를 위한 토큰
		Next string `json:"next"`
	} `json:"page"`
}

LivePages는 생방송 검색 결과를 담는 구조체이다.

type LiveSettings 

type LiveSettings struct {
	// 생방송 기본 제목
	DefaultLiveTitle string `json:"defaultLiveTitle"`
	// 생방송 카테고리, [Category] 참고
	Category Category `json:"category"`
	// 생방송 태그
	Tags []string `json:"tags"`
}

LiveSettings는 생방송 설정 정보를 나타낸다.

type LiveSettingsPatch 

type LiveSettingsPatch struct {
	// 생방송 기본 제목.
	DefaultLiveTitle *string `json:"defaultLiveTitle,omitempty"`
	// 생방송 카테고리 종류, [CategoryType] 참고.
	CategoryType *CategoryType `json:"categoryType,omitempty"`
	// 생방송 카테고리 ID, [Category.CategoryID]와 동일. 제거를 원하는 경우 빈 문자열("")을 지정한다.
	CategoryID *string `json:"categoryId,omitempty"`
	// 생방송 태그. 공백 및 특수문자 비허용. 제거를 원하는 경우 빈 슬라이스를 지정한다.
	Tags *[]string `json:"tags,omitempty"`
}

LiveSettingsPatch는 [Client.SetLiveSettings]로 변경할 방송 설정 정보를 나타낸다.

nil 필드는 전송되지 않으며, 서버는 전송되지 않은 필드의 기존 값을 유지한다. 값 지정에는 내장 함수 new를 사용할 수 있다. (예: new("새 제목"))

type LiveStreamKey 

type LiveStreamKey struct {
	// 생방송 스트림 키
	StreamKey string `json:"streamKey"`
}

LiveStreamKey는 생방송 스트림 키 정보를 나타낸다.

type LoginServer 

type LoginServer struct {
	// contains filtered or unexported fields
}

LoginServer는 치지직 OAuth 로그인 흐름을 처리한다.

[Client.NewLoginServer]로 생성하며, 두 가지 방식으로 사용할 수 있다.

[LoginServer.Start]는 자체 HTTP 서버를 열고 블록하는 편의 방식으로, /login 경로에서 인증 페이지로 리디렉션하고 RedirectURI 경로에서 인증 코드를 받아 토큰으로 교환한다.

기존 HTTP 서버에 통합하려면 [LoginServer.LoginHandler]와 [LoginServer.CallbackHandler]를 원하는 경로에 직접 등록한다. 이 경우 서버의 수명과 포트는 호출자가 관리한다.

state는 crypto/rand로 생성되어 10분간 유효하며 일회용으로 소비된다.

func (*LoginServer) CallbackHandler added in v0.2.0 

func (s *LoginServer) CallbackHandler() http.HandlerFunc

CallbackHandler는 OAuth 리디렉션을 처리하는 핸들러를 반환한다.

state를 검증·소비하고 인증 코드를 토큰으로 교환한 뒤, 일회용 모드에서는 클라이언트에 토큰을 주입하고 WithOnLogin 콜백이 있으면 호출한다. 응답으로는 [WithSuccessPage]로 설정한 HTML을 표시한다.

기존 HTTP 서버에 통합할 때 RedirectURI 경로에 등록한다. 서버의 수명과 포트는 호출자가 관리하며, [WithKeepAlive]의 서버 유지 여부는 LoginServer.Start 전용이다.

func (*LoginServer) LoginHandler added in v0.2.0 

func (s *LoginServer) LoginHandler() http.HandlerFunc

LoginHandler는 state를 발급하고 치지직 로그인 페이지로 리다이렉트하는 핸들러를 반환한다.

기존 HTTP 서버에 통합할 때 로그인 시작 경로에 등록한다. 서버의 수명과 포트는 호출자가 관리하며, 발급된 state는 [LoginServer.CallbackHandler]가 검증한다.

func (*LoginServer) Start 

func (s *LoginServer) Start(ctx context.Context) (*Tokens, error)

Start는 RedirectURI에서 파싱한 포트로 서버를 열고 블록한다. 일회용 모드: 첫 로그인 성공 후 자동 종료, 발급 토큰 반환. 상시 모드(WithKeepAlive): ctx 취소 전까지 유지, 토큰은 WithOnLogin 콜백으로만 전달.

내부적으로 [LoginServer.LoginHandler]를 /login에, [LoginServer.CallbackHandler]에 해당하는 핸들러를 RedirectURI 경로에 등록한 자체 서버를 실행하는 편의 래퍼이다.

type LoginServerOption 

type LoginServerOption func(*LoginServer)

LoginServerOption은 [LoginServer]의 동작을 설정하는 함수이다. WithKeepAlive, WithOnLogin, WithSuccessPage 참고.

func WithKeepAlive 

func WithKeepAlive() LoginServerOption

WithKeepAlive는 로그인 성공 후에도 서버를 유지한다. 여러 사용자의 로그인을 받는 상시 endpoint에 사용한다.

func WithOnLogin 

func WithOnLogin(fn func(Tokens)) LoginServerOption

WithOnLogin은 로그인 성공 시마다 발급된 토큰을 전달받을 콜백을 등록한다.

func WithSuccessPage 

func WithSuccessPage(html string) LoginServerOption

WithSuccessPage는 로그인 완료 시 브라우저에 표시할 HTML을 교체한다.

type MessageResult 

type MessageResult struct {
	// 전송된 채팅의 메시지 ID
	MessageID string `json:"messageId"`
}

MessageResult는 채팅 메시지 전송 결과를 나타낸다.

type MissingScopeError 

type MissingScopeError struct {
	// Scope는 부족한 권한이다.
	Scope Scope
}

MissingScopeError는 API 호출에 필요한 [Scope]가 토큰에 없을 때의 오류이다.

이 검사는 클라이언트에 설정된 권한 목록 기준의 사전 검사이며, 실제 권한 판정은 서버가 수행한다.

func (*MissingScopeError) Error 

func (e *MissingScopeError) Error() string

type QueryOption 

type QueryOption func(url.Values)

QueryOption은 조회 API의 선택적 쿼리 파라미터를 설정하는 함수이다. WithPage, WithSize, WithSort, WithNext 참고.

func WithNext 

func WithNext(next string) QueryOption

WithNext는 다음 페이지 조회를 위한 토큰을 지정한다. 이전 응답의 Page.Next 값을 전달한다.

func WithPage 

func WithPage(page int) QueryOption

WithPage는 조회할 페이지 번호를 지정한다. 페이지는 0부터 시작한다.

func WithSize 

func WithSize(size int) QueryOption

WithSize는 한 페이지에 조회할 항목 개수를 지정한다. 허용 범위는 API마다 다르며, 각 메서드의 문서를 참고한다.

func WithSort 

func WithSort(sort string) QueryOption

WithSort는 정렬 기준을 지정한다.

type Restriction 

type Restriction struct {
	// 활동 제한된 채널 ID
	RestrictedChannelID string `json:"restrictedChannelId"`
	// 활동 제한된 채널 이름
	RestrictedChannelName string `json:"restrictedChannelName"`
	// 생성 날짜
	CreatedDate string `json:"createdDate"`
	// 해제 날짜, 영구 제한의 경우 null
	ReleaseDate string `json:"releaseDate,omitempty"`
}

Restriction은 치지직에서 사용되는 활동 제한 정보를 나타낸다.

type RestrictionPages 

type RestrictionPages struct {
	// 활동 제한 정보 목록
	Data []Restriction `json:"data"`
	// 다음 페이지 조회를 위한 구조체, 마지막 페이지인 경우 null
	Page struct {
		// 다음 페이지 조회를 위한 토큰
		Next string `json:"next"`
	} `json:"page"`
}

RestrictionPages는 활동 제한 검색 결과를 담는 구조체이다.

type RevokeTokenRequest 

type RevokeTokenRequest struct {
	// ClientID는 치지직 개발자 센터에서 발급받은 클라이언트 ID이다.
	// 비어 있으면 클라이언트에 설정된 값이 사용된다.
	ClientID string `json:"clientId"`
	// ClientSecret은 치지직 개발자 센터에서 발급받은 클라이언트 시크릿이다.
	// 비어 있으면 클라이언트에 설정된 값이 사용된다.
	ClientSecret string `json:"clientSecret"`
	// Token은 제거할 토큰이다. (액세스 토큰 또는 리프레시 토큰)
	Token string `json:"token"`
	// TokenTypeHint는 제거할 토큰의 종류이다. ("access_token" 또는 "refresh_token")
	TokenTypeHint string `json:"tokenTypeHint,omitempty"`
}

RevokeTokenRequest는 토큰 제거 요청의 본문을 나타낸다. [Client.RevokeToken]에 전달한다.

type Scope 

type Scope string

Scope는 치지직 Open API의 권한 단위를 나타낸다. 치지직은 권한 이름으로 한국어 문자열을 사용한다. 

const (
	// ChannelInfoRead는 채널 정보 조회 권한이다.
	ChannelInfoRead Scope = "채널 정보 조회"
	// ChannelManagerRead는 채널 관리자 조회 권한이다.
	ChannelManagerRead Scope = "채널 관리자 조회"
	// LiveStreamKeyRead는 방송 스트림키 조회 권한이다.
	LiveStreamKeyRead Scope = "방송 스트림키 조회"
	// LiveSettingRead는 방송 설정 조회 권한이다.
	LiveSettingRead Scope = "방송 설정 조회"
	// LiveSettingWrite는 방송 설정 변경 권한이다.
	LiveSettingWrite Scope = "방송 설정 변경"
	// UserRead는 유저 조회 권한이다.
	UserRead Scope = "유저 조회"
	// ChatMessageRead는 채팅 메시지 조회 권한이다.
	ChatMessageRead Scope = "채팅 메시지 조회"
	// ChatMessageWrite는 채팅 메시지 쓰기 권한이다.
	ChatMessageWrite Scope = "채팅 메시지 쓰기"
	// ChatNoticeWrite는 채팅 공지 쓰기 권한이다.
	ChatNoticeWrite Scope = "채팅 공지 쓰기"
	// ChatSettingsRead는 채팅 설정 조회 권한이다.
	ChatSettingsRead Scope = "채팅 설정 조회"
	// ChatSettingsWrite는 채팅 설정 변경 권한이다.
	ChatSettingsWrite Scope = "채팅 설정 변경"
	// RestrictionWrite는 활동제한 쓰기 권한이다.
	RestrictionWrite Scope = "활동제한 쓰기"
	// RestrictionRead는 활동제한 조회 권한이다.
	RestrictionRead Scope = "활동제한 조회"
	// DonationRead는 후원 조회 권한이다.
	DonationRead Scope = "후원 조회"
	// SubscriptionRead는 구독 조회 권한이다.
	SubscriptionRead Scope = "구독 조회"
)

type Scopes 

type Scopes []Scope

Scopes는 [Scope]의 목록이다.

func ParseScopes 

func ParseScopes(raw string) Scopes

ParseScopes는 공백으로 구분된 권한 문자열을 [Scopes]로 파싱한다.

치지직 API는 권한 목록을 "채널 정보 조회 유저 조회"처럼 하나의 문자열로 반환하므로, 종결자(조회/변경/쓰기)를 기준으로 개별 [Scope]를 분리한다.

func (Scopes) Has 

func (s Scopes) Has(scope Scope) bool

Has는 권한 목록에 scope가 포함되어 있는지 반환한다.

func (Scopes) MarshalJSON 

func (s Scopes) MarshalJSON() ([]byte, error)

MarshalJSON은 권한 목록을 API 응답과 동일한 공백 구분 문자열로 직렬화한다. [Tokens]를 JSON으로 저장했다가 복원해도 원형이 유지된다.

func (Scopes) String 

func (s Scopes) String() string

String은 권한 목록을 공백으로 구분된 하나의 문자열로 반환한다.

func (*Scopes) UnmarshalJSON 

func (s *Scopes) UnmarshalJSON(b []byte) error

UnmarshalJSON은 공백으로 구분된 권한 문자열을 [ParseScopes]로 파싱하여 담는다.

type Session 

type Session struct {
	// 세션 키
	SessionKey string `json:"sessionKey"`
	// 연결된 날짜
	ConnectedDate string `json:"connectedDate"`
	// 연결 해제된 날짜, 연결이 유지 중인 경우 null
	DisconnectedDate string `json:"disconnectedDate,omitempty"`
	// 구독된 이벤트 목록
	SubscribedEvents []Events `json:"subscribedEvents"`
}

Session은 세션 정보를 나타낸다.

type SessionPages 

type SessionPages struct {
	// 세션 정보 목록
	Data []Session `json:"data"`
	// 현재 페이지 번호
	Page int `json:"page"`
	// 총 세션 개수
	TotalCount int `json:"totalCount"`
	// 총 페이지 개수
	TotalPages int `json:"totalPages"`
}

SessionPages는 세션 목록 결과를 담는 구조체이다.

type SessionSocket added in v0.3.0 

type SessionSocket struct {
	// contains filtered or unexported fields
}

SessionSocket은 세션 서버에 접속해 실시간 이벤트를 수신한다.

[Client.CreateSessionWithClient]나 [Client.CreateSessionWithUser]가 반환한 세션 URL로 [NewSessionSocket]을 만들어 사용한다. 

socket := chzzkgo.NewSessionSocket(session.URL)
socket.OnChat(func(e chzzkgo.ChatEvent) { ... })

if err := socket.Connect(ctx); err != nil {
	return err
}
defer socket.Close()

// 연결만으로는 이벤트가 오지 않는다. 세션 키로 구독해야 한다.
if err := chzzk.SubscribeChatEvent(ctx, socket.SessionKey()); err != nil {
	return err
}

<-socket.Done()
return socket.Err()

핸들러는 SessionSocket.Connect 전에 등록해야 한다. 서버가 연결 직후 SYSTEM 이벤트를 보내므로 연결한 뒤에 등록하면 놓칠 수 있다.

재연결은 하지 않는다. 세션 URL은 한 번만 쓸 수 있어 같은 URL로 다시 접속하는 것이 옳지 않기 때문이다. [SessionSocket.Done]이 닫히면 [SessionSocket.Err]로 원인을 확인하고, 세션을 새로 발급받아 소켓을 다시 만들어야 한다. [Client.ConnectSessionWithUser]와 [Client.ConnectSessionWithClient]가 이 과정을 대신해 준다.

func NewSessionSocket added in v0.3.0 

func NewSessionSocket(sessionURL string, opts ...SessionSocketOption) *SessionSocket

NewSessionSocket은 세션 URL에 접속할 소켓을 만든다. 실제 접속은 [SessionSocket.Connect]에서 이루어진다.

func (*SessionSocket) Close added in v0.3.0 

func (s *SessionSocket) Close() error

Close는 연결을 닫는다.

func (*SessionSocket) Connect added in v0.3.0 

func (s *SessionSocket) Connect(ctx context.Context) error

Connect는 세션 서버에 접속하고, 서버가 세션 키를 보낼 때까지 기다린 뒤 반환한다.

반환 후에는 [SessionSocket.SessionKey]로 세션 키를 얻어 구독 API를 호출할 수 있다. ctx는 접속이 끝날 때까지만 사용되며, 연결 수명은 [SessionSocket.Close]를 호출하거나 서버가 연결을 끊을 때까지이다.

한 소켓은 한 번만 연결할 수 있다.

func (*SessionSocket) Done added in v0.3.0 

func (s *SessionSocket) Done() <-chan struct{}

Done은 연결이 끝나면 닫히는 채널을 반환한다. 끝난 이유는 [SessionSocket.Err]로 확인한다.

func (*SessionSocket) Err added in v0.3.0 

func (s *SessionSocket) Err() error

Err은 연결이 끝난 이유를 반환한다. 아직 연결 중이면 nil이고, [SessionSocket.Close]로 정상 종료했다면 [ErrSessionClosed]이다.

func (*SessionSocket) OnAny added in v0.3.0 

func (s *SessionSocket) OnAny(fn func(event string, payload json.RawMessage))

OnAny는 모든 이벤트의 원본 본문을 받는 핸들러를 등록한다. payload는 이중 인코딩을 한 겹 벗긴 JSON이다.

문서에 없는 필드나 알 수 없는 이벤트를 확인할 때 사용한다. 이름별 핸들러보다 먼저 호출된다.

func (*SessionSocket) OnChat added in v0.3.0 

func (s *SessionSocket) OnChat(fn func(ChatEvent))

OnChat은 채팅 이벤트 핸들러를 등록한다.

ChatMessageRead(채팅 메시지 조회) [Scope]로 채팅 이벤트를 구독해야 호출된다. Client.SubscribeChatEvent 참고.

func (*SessionSocket) OnDisconnect added in v0.3.0 

func (s *SessionSocket) OnDisconnect(fn func(reason string))

OnDisconnect는 서버가 연결을 끊었을 때 호출될 핸들러를 등록한다.

func (*SessionSocket) OnDonation added in v0.3.0 

func (s *SessionSocket) OnDonation(fn func(DonationEvent))

OnDonation은 후원 이벤트 핸들러를 등록한다.

DonationRead(후원 조회) [Scope]로 후원 이벤트를 구독해야 호출된다. Client.SubscribeDonationEvent 참고.

func (*SessionSocket) OnError added in v0.3.0 

func (s *SessionSocket) OnError(fn func(error))

OnError는 이벤트 본문을 해석하지 못했을 때와 연결을 유지한 채 발생한 하위 계층 오류를 알리는 핸들러를 등록한다. 연결이 끊기는 오류는 [SessionSocket.Err]로 확인한다.

func (*SessionSocket) OnSubscription added in v0.3.0 

func (s *SessionSocket) OnSubscription(fn func(SubscriptionEvent))

OnSubscription은 구독 이벤트 핸들러를 등록한다.

SubscriptionRead(구독 조회) [Scope]로 구독 이벤트를 구독해야 호출된다. Client.SubscribeSubscriptionEvent 참고.

[SubscriptionEvent]는 실제 페이로드를 관측하지 못한 미검증 구조체이다.

func (*SessionSocket) OnSystem added in v0.3.0 

func (s *SessionSocket) OnSystem(fn func(SystemEvent))

OnSystem은 시스템 이벤트 핸들러를 등록한다.

구독이 시작·해제되거나 서버가 구독을 취소할 때 호출된다. [SystemEventTypeRevoked]는 서버가 구독을 끊은 것이므로 그대로 두면 이후 이벤트가 오지 않는다.

연결 직후 오는 [SystemEventTypeConnected]는 [SessionSocket.SessionKey]로도 확인할 수 있으므로 이 핸들러에서 따로 처리하지 않아도 된다.

func (*SessionSocket) SessionKey added in v0.3.0 

func (s *SessionSocket) SessionKey() string

SessionKey는 서버가 보낸 세션 키를 반환한다.

이 값으로 Client.SubscribeChatEvent 등을 호출해야 실제 이벤트가 오기 시작한다. [SessionSocket.Connect]가 성공했다면 항상 채워져 있다.

type SessionSocketOption added in v0.3.0 

type SessionSocketOption func(*sessionSocketOptions)

SessionSocketOption은 [NewSessionSocket]에 넘기는 설정이다.

func WithSocketOptions added in v0.3.0 

func WithSocketOptions(opts ...socketio2.Option) SessionSocketOption

WithSocketOptions는 하위 Socket.IO 클라이언트에 전달할 설정을 지정한다. HTTP 클라이언트나 읽기 제한 등을 바꿀 때 사용한다. 

chzzkgo.NewSessionSocket(url, chzzkgo.WithSocketOptions(socketio2.WithReadLimit(4<<20)))

type SessionURLResponse 

type SessionURLResponse struct {
	// 생성된 세션 URL
	URL string `json:"url"`
}

SessionURLResponse는 세션 생성 시 반환되는 URL 정보를 담는 구조체이다.

type StreamingRole 

type StreamingRole struct {
	// 매니저/관리자 채널 ID
	ManagerChannelID string `json:"managerChannelId"`
	// 매니저/관리자 채널 이름
	ManagerChannelName string `json:"managerChannelName"`
	// 사용자 역할. [UserRole] 상수 참고.
	UserRole UserRole `json:"userRole"`
	// 권한이 부여된 날짜
	CreatedDate string `json:"createdDate"`
}

StreamingRole은 치지직에서 사용되는 권한 체계를 나타낸다.

type StreamingRolePages 

type StreamingRolePages struct {
	// 권한 정보 목록
	Data []StreamingRole `json:"data"`
}

StreamingRolePages는 권한 검색 결과를 담는 구조체이다.

type SubscriptionEvent added in v0.3.0 

type SubscriptionEvent struct {
	// 이벤트가 발생한 채널 ID
	ChannelID string `json:"channelId"`
	// 구독자 채널 ID
	SubscriberChannelID string `json:"subscriberChannelId"`
	// 구독자 닉네임
	SubscriberNickname string `json:"subscriberNickname"`
	// 구독 티어 (1 또는 2)
	TierNo int `json:"tierNo"`
	// 구독 티어 이름
	TierName string `json:"tierName"`
	// 구독 개월 수
	Month int `json:"month"`
	// 서버가 이벤트를 보낸 시각.
	// 다른 이벤트에 있는 것으로 미루어 넣어 두었을 뿐 확인된 바 없다.
	EventSentAt EventTime `json:"eventSentAt"`
}

SubscriptionEvent는 세션에서 수신한 구독 이벤트이다.

구독 기능이 치지직 프로 회원에게만 열려 있어 실제 페이로드를 관측하지 못했다. 이 구조체는 공식 문서만을 근거로 정의한 미검증 상태이며, 필드 이름과 타입이 실제와 다를 수 있다. 실제로 후원의 payAmount는 문서와 달리 문자열이 아닌 숫자였으므로 TierNo와 Month의 타입도 확인이 필요하다. 값이 비어 있다면 [SessionSocket.OnAny]로 원본을 확인할 것.

type SystemEvent added in v0.3.0 

type SystemEvent struct {
	// 이벤트 종류. [SystemEventType] 상수 참고.
	// 문서에 없는 값이 올 수도 있으므로 알 수 없는 값은 무시하는 편이 안전하다.
	Type SystemEventType `json:"type"`
	// 이벤트 본문
	Data SystemEventData `json:"data"`
}

SystemEvent는 세션 상태 변화를 알리는 시스템 이벤트이다.

type SystemEventData added in v0.3.0 

type SystemEventData struct {
	// 세션 키. connected에서만 채워진다.
	SessionKey string `json:"sessionKey"`
	// 대상 이벤트 종류. subscribed, unsubscribed, revoked에서 채워진다.
	EventType Event `json:"eventType"`
	// 대상 채널 ID. subscribed, unsubscribed, revoked에서 채워진다.
	ChannelID string `json:"channelId"`
}

SystemEventData는 시스템 이벤트의 본문이다. 채워지는 필드는 [SystemEvent.Type]에 따라 다르다.

type SystemEventType added in v0.3.0 

type SystemEventType string

SystemEventType은 시스템 이벤트의 종류를 나타낸다. 

const (
	// SystemEventTypeConnected는 세션 연결이 완료되었음을 알린다. 세션 키가 함께 온다.
	SystemEventTypeConnected SystemEventType = "connected"
	// SystemEventTypeSubscribed는 이벤트 구독이 시작되었음을 알린다.
	SystemEventTypeSubscribed SystemEventType = "subscribed"
	// SystemEventTypeUnsubscribed는 이벤트 구독이 해제되었음을 알린다.
	SystemEventTypeUnsubscribed SystemEventType = "unsubscribed"
	// SystemEventTypeRevoked는 서버가 구독을 취소했음을 알린다.
	// 이 이후로는 해당 이벤트가 오지 않으므로 다시 구독하거나 세션을 정리해야 한다.
	SystemEventTypeRevoked SystemEventType = "revoked"
)

type TokenRequest 

type TokenRequest struct {
	// GrantType은 발급 방식이다. ("authorization_code" 또는 "refresh_token")
	GrantType string `json:"grantType"`
	// ClientID는 치지직 개발자 센터에서 발급받은 클라이언트 ID이다.
	ClientID string `json:"clientId"`
	// ClientSecret은 치지직 개발자 센터에서 발급받은 클라이언트 시크릿이다.
	ClientSecret string `json:"clientSecret"`
	// Code는 OAuth 인증 후 리디렉션으로 전달받은 인증 코드이다. (authorization_code 방식)
	Code string `json:"code,omitempty"`
	// State는 인증 요청 시 전달한 state 값이다. (authorization_code 방식)
	State string `json:"state,omitempty"`
	// RefreshToken은 토큰 갱신에 사용할 리프레시 토큰이다. (refresh_token 방식)
	RefreshToken string `json:"refreshToken,omitempty"`
}

TokenRequest는 토큰 발급/갱신 요청의 본문을 나타낸다. 일반적으로 직접 사용할 일은 없으며, [Client.ExchangeCode]와 자동 토큰 갱신이 내부적으로 사용한다.

type Tokens 

type Tokens struct {
	// AccessToken은 API 호출에 사용하는 액세스 토큰이다.
	AccessToken string `json:"accessToken"`
	// RefreshToken은 액세스 토큰 갱신에 사용하는 리프레시 토큰이다.
	RefreshToken string `json:"refreshToken"`
	// ExpiresIn은 액세스 토큰의 유효 기간(초)이다.
	ExpiresIn int `json:"expiresIn"`
	// Scope는 토큰에 부여된 권한 목록이다.
	Scope Scopes `json:"scope"`
}

Tokens는 발급된 OAuth 토큰 정보를 나타낸다.

type User 

type User struct {
	// 사용자의 채널 ID
	ChannelID string `json:"channelId"`
	// 사용자의 채널 이름
	ChannelName string `json:"channelName"`
	// 사용자의 닉네임 (공식 문서에는 없으나 실응답에 포함됨)
	Nickname string `json:"nickname"`
}

User는 현재 인증된 사용자의 정보를 나타낸다.

type UserRole 

type UserRole string

UserRole은 치지직에서 사용되는 사용자 역할을 나타낸다. 

const (
	// StreamingChannelOwner는 치지직 채널 소유자이다. (미사용으로 추정 - [Streamer] 참고)
	StreamingChannelOwner UserRole = "STREAMING_CHANNEL_OWNER"
	// StreamingChannelManager는 치지직 채널 관리자이다.
	StreamingChannelManager UserRole = "STREAMING_CHANNEL_MANAGER"
	// StreamingChatManager는 치지직 채널 채팅 관리자이다.
	StreamingChatManager UserRole = "STREAMING_CHAT_MANAGER"
	// StreamingSettlementManager는 치지직 채널 정산 관리자이다.
	StreamingSettlementManager UserRole = "STREAMING_SETTLEMENT_MANAGER"
	// Streamer는 스트리머 본인이다. (공식 문서에는 없으나 실응답에서 확인된 역할)
	Streamer UserRole = "STREAMER"
)

type UserRoleCode added in v0.3.0 

type UserRoleCode string

UserRoleCode는 채팅 발신자의 역할을 나타낸다.

채널 관리자 조회에 쓰이는 [UserRole]과는 값 체계가 다르다. 

const (
	// UserRoleCodeStreamer는 방송인 본인이다.
	UserRoleCodeStreamer UserRoleCode = "streamer"
	// UserRoleCodeCommonUser는 일반 시청자이다.
	UserRoleCodeCommonUser UserRoleCode = "common_user"
	// UserRoleCodeStreamingChannelManager는 채널 관리자이다.
	UserRoleCodeStreamingChannelManager UserRoleCode = "streaming_channel_manager"
	// UserRoleCodeStreamingChatManager는 채팅 관리자이다.
	UserRoleCodeStreamingChatManager UserRoleCode = "streaming_chat_manager"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.