Add Comments to Your iOS App

• 중첩된 답글과 페이징을 갖는 스레드형 댓글 트리
• 게시물 생성, 리액션, 미디어 첨부를 지원하는 소셜 피드
• 자동 스크롤 및 날짜 구분자가 있는 라이브 채팅 모드
• WebSocket을 통한 실시간 업데이트(새 댓글, 투표, 접속 상태)
• 싱글 사인온(Simple SSO는 테스트용, Secure SSO는 운영용)
• 굵게, 이탤릭, 코드, @멘션을 지원하는 리치 텍스트 편집
• 위/아래 화살표 또는 하트 등 설정 가능한 스타일의 투표
• 모더레이션 작업: 신고, 고정, 잠금, 차단
• 프리셋과 완전한 커스터마이징을 제공하는 종합적인 테마
• 댓글 및 피드 게시물 작성을 위한 맞춤 툴바 버튼
• 이미지 업로드
• EU 리전 지원
• 사용자 접속 상태(온라인/오프라인 표시)
• 태그 기반 피드 필터링
• 현지화 지원

• iOS 16 이상 또는 macOS 14 이상
• Swift 5.9 이상
• SwiftUI

Swift Package Manager를 사용하여 FastCommentsUI를 프로젝트에 추가하세요.

Xcode에서: File > Add Package Dependencies를 선택한 다음 저장소 URL을 입력하세요.

또는 Package.swift에 추가하세요:

dependencies: [
    .package(url: "https://github.com/fastcomments/fastcomments-ios.git", from: "1.0.0")
]

그런 다음 제품을 타깃에 추가하세요:

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "FastCommentsUI", package: "fastcomments-ios")
    ]
)

필요한 곳에서 두 모듈을 임포트하세요:

import FastCommentsUI
import FastCommentsSwift

댓글 위젯을 표시하기 위한 최소 설정:

import SwiftUI
import FastCommentsUI

struct ContentView: View {
    @StateObject private var sdk = FastCommentsSDK(
        config: FastCommentsWidgetConfig(
            tenantId: "demo",
            urlId: "my-page-1",
            url: "https://example.com/page-1",
            pageTitle: "My Page"
        )
    )

    var body: some View {
        FastCommentsView(sdk: sdk)
            .task {
                try? await sdk.load()
            }
    }
}

Replace "demo" with your FastComments tenant ID. The urlId identifies the page or thread where comments are stored.

FastComments는 세 가지 인증 모드를 지원합니다:

1. 익명 -- SSO 토큰 없음; 사용자는 세션 기반 식별자를 받습니다
2. 간단한 SSO -- 데모 및 테스트용 클라이언트 측 토큰(보안 아님)
3. 보안 SSO -- 프로덕션용 서버 서명 토큰

간단한 SSO

데모 및 로컬 테스트에 유용합니다. 간단한 SSO는 누구나 임의의 사용자를 가장할 수 있으므로 프로덕션 환경에서는 사용하지 마세요.

import FastCommentsSwift

let userData = SimpleSSOUserData(
    username: "Jane Doe",
    email: "jane@example.com",
    avatar: "https://example.com/avatar.jpg"
)
let sso = FastCommentsSSO.createSimple(simpleSSOUserData: userData)
let token = try? sso.prepareToSend()

let config = FastCommentsWidgetConfig(
    tenantId: "YOUR_TENANT_ID",
    urlId: "my-page-1",
    sso: token
)
let sdk = FastCommentsSDK(config: config)

SimpleSSOUserData는 또한 선택적 필드를 지원합니다:

• id -- 사용자 ID (설정하지 않으면 이메일을 기본값으로 사용)
• displayName -- 별도의 표시 이름
• displayLabel -- 이름 옆에 표시되는 사용자 지정 레이블(예: "VIP")
• websiteUrl -- 사용자 이름에 대한 링크
• locale -- 로케일 코드
• isProfileActivityPrivate -- 프로필 활동 숨기기(기본값: true)

보안 SSO

프로덕션에서는 백엔드가 API 시크릿을 사용하여 서명된 SSO 토큰을 생성합니다. iOS 앱은 이 토큰을 서버에서 가져와서 config에 전달합니다.

백엔드에서 (FastComments Swift SDK를 사용하거나 다른 언어로):

let userData = SecureSSOUserData(
    id: "user-123",
    email: "user@example.com",
    username: "Display Name",
    avatar: "https://example.com/avatar.jpg"
)
let sso = try FastCommentsSSO.createSecure(apiKey: "YOUR_API_KEY", secureSSOUserData: userData)
let token = try sso.prepareToSend()
// 이 토큰을 API를 통해 iOS 앱으로 반환하세요

iOS 앱에서:

struct MyView: View {
    @StateObject private var sdk = FastCommentsSDK(
        config: FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "my-page-1"
        )
    )
    @State private var isLoadingToken = true

    var body: some View {
        Group {
            if isLoadingToken {
                ProgressView("Loading...")
            } else {
                FastCommentsView(sdk: sdk)
            }
        }
        .task {
            // 백엔드에서 토큰을 가져옵니다
            let token = try? await fetchSSOTokenFromYourBackend()
            // 토큰으로 새 구성(config)을 생성하거나 로드 전에 설정하세요
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData는 추가 필드를 지원합니다:

• optedInNotifications -- 이메일 알림 수신 동의
• displayLabel -- 사용자 지정 레이블
• displayName -- 표시 이름
• websiteUrl -- 웹사이트 URL
• groupIds -- 그룹 소속
• isAdmin -- 관리자 권한
• isModerator -- 중재자 권한
• isProfileActivityPrivate -- 프로필 공개 여부

기본 사용법

struct CommentsPage: View {
    @StateObject private var sdk = FastCommentsSDK(
        config: FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "article-42",
            url: "https://example.com/article/42",
            pageTitle: "Article Title"
        )
    )

    var body: some View {
        FastCommentsView(sdk: sdk)
            .task {
                try? await sdk.load()
            }
    }
}

투표 스타일

기본 투표 스타일은 상/하 화살표를 표시합니다. 하트 스타일 투표를 사용하려면 ._1 을 전달하세요:

FastCommentsView(sdk: sdk, voteStyle: ._1)

이벤트 콜백

모디파이어 스타일의 콜백을 사용하여 사용자 상호작용을 처리하세요:

FastCommentsView(sdk: sdk)
    .onCommentPosted { comment in
        print("New comment: \(comment.commentHTML)")
    }
    .onReplyClick { renderableComment in
        print("Replying to: \(renderableComment.comment.id)")
    }
    .onUserClick { context, userInfo, source in
        // source는 .name 또는 .avatar 입니다
        print("Tapped \(userInfo.displayName)")
    }

테마 적용

SwiftUI 환경을 통해 테마를 전달하세요:

FastCommentsView(sdk: sdk)
    .fastCommentsTheme(myTheme)
    .task { try? await sdk.load() }

또는 SDK에 직접 설정하세요:

sdk.theme = FastCommentsTheme.modern

정렬 방향

sdk.defaultSortDirection = .nf  // 최신순 (기본값)
sdk.defaultSortDirection = .of  // 오래된 순
sdk.defaultSortDirection = .mr  // 관련성 높은 순

LiveChatView는 자동 스크롤, 날짜 구분선, 컴팩트 레이아웃을 갖춘 실시간 채팅 환경을 제공합니다. SDK를 가장 오래된 항목 우선 정렬 및 즉시 라이브 표시로 자동 구성합니다.

struct ChatView: View {
    @StateObject private var sdk: FastCommentsSDK = {
        let config = FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "chat-room-1",
            sso: ssoToken  // 사용자의 이름 표시를 위해 SSO 사용을 권장합니다
        )
        return FastCommentsSDK(config: config)
    }()

    var body: some View {
        LiveChatView(sdk: sdk)
            .onCommentPosted { comment in
                print("Sent: \(comment.commentHTML)")
            }
            .task {
                try? await sdk.load()
            }
    }
}

LiveChatView는 다음 콜백을 지원합니다:

• .onCommentPosted -- 사용자가 메시지를 보낼 때 호출됩니다
• .onCommentDeleted -- 메시지가 삭제될 때 호출됩니다
• .onUserClick -- 사용자의 이름이나 아바타를 탭했을 때 호출됩니다

피드 시스템은 자체 뷰를 가진 별도의 SDK (FastCommentsFeedSDK)입니다.

피드 로드 및 표시

struct FeedPage: View {
    @StateObject private var sdk: FastCommentsFeedSDK = {
        let config = FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "my-feed",
            sso: ssoToken
        )
        return FastCommentsFeedSDK(config: config)
    }()

    @State private var commentsPost: FeedPost?

    var body: some View {
        FastCommentsFeedView(sdk: sdk)
            .onPostSelected { post in
                commentsPost = post
            }
            .onCommentsRequested { post in
                commentsPost = post
            }
            .onSharePost { post in
                // 공유 시트 표시
            }
            .onUserClick { context, userInfo, source in
                // 사용자 프로필로 이동
            }
            .onMediaClick { mediaItem, index in
                // 전체 화면 이미지 뷰어 표시
            }
            .task {
                try? await sdk.load()
            }
    }
}

피드 뷰는 자동으로 풀 투 리프레시(pull-to-refresh)와 무한 스크롤을 포함합니다.

게시물 생성

게시물 작성 폼을 표시하려면 FeedPostCreateView를 사용하세요:

@State private var showCreatePost = false

// In your view body:
.sheet(isPresented: $showCreatePost) {
    FeedPostCreateView(
        sdk: sdk,
        onPostCreated: { post in
            showCreatePost = false
            Task { try? await sdk.refresh() }
        },
        onCancelled: {
            showCreatePost = false
        }
    )
}

게시물에 반응하기

SDK는 낙관적 업데이트(optimistic updates)로 반응을 처리합니다:

try await sdk.reactPost(postId: post.id, reactionType: "l")

// 반응 상태 확인
let hasLiked = sdk.hasUserReacted(postId: post.id, reactType: "l")
let likeCount = sdk.getLikeCount(postId: post.id)

게시물의 댓글 열기

피드 게시물의 댓글을 표시하려면 CommentsSheet를 사용하세요. 이 컴포넌트는 내부적으로 feed SDK의 구성(config)을 사용하여 FastCommentsSDK 인스턴스를 생성합니다:

.sheet(item: $commentsPost) { post in
    CommentsSheet(post: post, feedSDK: sdk, onUserClick: { context, userInfo, source in
        // 사용자 클릭 처리
    })
}

참고: FeedPost가 .sheet(item:)에 사용되려면 Identifiable을 준수해야 합니다. 다음 익스텐션을 추가하세요:

extension FeedPost: @retroactive Identifiable {}

태그 기반 피드 필터링

태그로 피드 게시물을 필터링하려면 TagSupplier 프로토콜을 구현하세요:

struct TeamTagSupplier: TagSupplier {
    func getTags(currentUser: UserSessionInfo?) -> [String]? {
        guard let user = currentUser else { return nil }
        return ["team:\(user.id ?? "")", "public"]
    }
}

sdk.tagSupplier = TeamTagSupplier()

필터링되지 않은 전역 피드의 경우 nil을 반환하세요.

피드 상태 저장 및 복원

뷰 수명 주기 이벤트 전반에 걸쳐 페이지네이션 상태를 보존하세요:

let state = sdk.savePaginationState()
// Later...
sdk.restorePaginationState(state)

게시물 삭제

sdk.onPostDeleted = { postId in
    print("Post \(postId) was deleted")
}

테마 프리셋

네 가지 내장 프리셋이 제공됩니다:

// 시스템 기본값
sdk.theme = FastCommentsTheme.default

// 그림자와 큰 둥근 모서리가 있는 카드
sdk.theme = FastCommentsTheme.modern

// 플랫(그림자 없음), 작은 모서리 반경, 스레드 라인 없음
sdk.theme = FastCommentsTheme.minimal

// 모든 액션 색상을 단일 브랜드 색상으로 설정
sdk.theme = FastCommentsTheme.allPrimary(.indigo)

댓글 표시 스타일

var theme = FastCommentsTheme()
theme.commentStyle = .flat    // 구분선이 있는 플랫 리스트 (기본)
theme.commentStyle = .card    // 그림자가 있는 둥근 카드
theme.commentStyle = .bubble  // 채팅 버블 스타일

색상

모든 색상 속성은 선택 사항입니다. 설정되지 않은 값은 적절한 시스템 기본값으로 대체됩니다.

var theme = FastCommentsTheme()

// 브랜드 색상
theme.primaryColor = .indigo
theme.primaryLightColor = .indigo.opacity(0.6)
theme.primaryDarkColor = Color(red: 0.2, green: 0.1, blue: 0.5)

// 배경
theme.commentBackgroundColor = Color(.secondarySystemGroupedBackground)
theme.containerBackgroundColor = Color(.systemGroupedBackground)

// 액션 버튼
theme.actionButtonColor = .indigo
theme.replyButtonColor = .indigo
theme.toggleRepliesButtonColor = .indigo.opacity(0.8)
theme.loadMoreButtonTextColor = .indigo

// 투표
theme.voteActiveColor = .red
theme.voteCountColor = .primary
theme.voteCountZeroColor = .secondary
theme.voteDividerColor = Color(.separator)

// 링크
theme.linkColor = .indigo
theme.linkColorPressed = .indigo.opacity(0.5)

// 다이얼로그
theme.dialogHeaderBackgroundColor = .indigo
theme.dialogHeaderTextColor = .white

// 입력 바
theme.inputBarBackgroundColor = Color(.systemBackground)
theme.inputBarBorderColor = Color(.separator)

// 기타
theme.onlineIndicatorColor = .green
theme.separatorColor = Color(.separator)
theme.badgeBackgroundColor = .gray.opacity(0.2)
theme.threadLineColor = .indigo.opacity(0.15)

타이포그래피

theme.commenterNameFont = .subheadline.weight(.bold)
theme.bodyFont = .body
theme.captionFont = .caption
theme.actionFont = .caption.weight(.medium)

레이아웃 및 간격

theme.cornerRadius = .large       // .none, .small, .medium, .large
theme.commentSpacing = 4          // 댓글 행 사이의 간격(포인트)
theme.nestingIndent = 20          // 중첩 수준당 들여쓰기(포인트)
theme.avatarSize = 36             // 루트 댓글의 아바타 지름
theme.replyAvatarSize = 28        // 중첩된 답글의 아바타 지름

시각 효과

theme.showShadows = true          // 카드에 미묘한 그림자
theme.showThreadLine = true       // 중첩된 답글을 연결하는 수직선
theme.animateVotes = true         // 투표 변경 시 스프링 애니메이션

테마 적용

두 가지 방법:

// Via SwiftUI environment (recommended for view hierarchy)
FastCommentsView(sdk: sdk)
    .fastCommentsTheme(theme)

// Directly on the SDK
sdk.theme = theme

Comment Toolbar Buttons

댓글 입력 툴바에 버튼을 추가하려면 CustomToolbarButton 프로토콜을 구현하세요:

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // SF 심볼 이름
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // 선택적 배지 카운트

    func onClick(text: Binding<String>) {
        text.wrappedValue += "\u{1F44D}"
    }

    // Optional overrides (default to true)
    func isEnabled() -> Bool { true }
    func isVisible() -> Bool { true }
}

뷰를 생성할 때 커스텀 버튼을 전달하세요:

FastCommentsView(
    sdk: sdk,
    customToolbarButtons: [EmojiButton(), CodeBlockButton()]
)

또는 SDK에 전역으로 추가하여 모든 인스턴스에 적용할 수 있습니다:

sdk.addGlobalCustomToolbarButton(EmojiButton())
sdk.removeGlobalCustomToolbarButton(id: "emoji")
sdk.clearGlobalCustomToolbarButtons()

Feed Toolbar Buttons

게시물 생성 폼에 대해 FeedCustomToolbarButton을 구현하세요:

struct HashtagButton: FeedCustomToolbarButton {
    let id = "hashtag"
    let iconSystemName = "number"
    let contentDescription = "Add Hashtag"

    func onClick(content: Binding<String>) {
        content.wrappedValue += "#"
    }
}

생성 뷰에 전달하세요:

FeedPostCreateView(
    sdk: sdk,
    customToolbarButtons: [HashtagButton()],
    onPostCreated: { _ in },
    onCancelled: { }
)

또는 피드 SDK에서 전역으로 설정하세요:

sdk.globalFeedToolbarButtons = [HashtagButton()]

모든 사용자에게 제공되는 작업

• 신고/신고 취소 -- 댓글을 검토를 위해 신고

try await sdk.flagComment(commentId: commentId)
try await sdk.unflagComment(commentId: commentId)

• 차단/차단 해제 -- 특정 사용자의 모든 댓글을 숨김 (뷰어별)

try await sdk.blockUser(commentId: commentId)
try await sdk.unblockUser(commentId: commentId)

관리자 전용 작업

• 고정/고정 해제 -- 스레드 상단에 댓글 고정

try await sdk.pinComment(commentId: commentId)
try await sdk.unpinComment(commentId: commentId)

• 잠금/잠금 해제 -- 댓글에 새 답글 작성 방지

try await sdk.lockComment(commentId: commentId)
try await sdk.unlockComment(commentId: commentId)

모든 중재 작업은 UI의 댓글 컨텍스트 메뉴에서도 사용할 수 있습니다. 관리자 작업은 현재 사용자가 사이트 관리자일 때만 표시됩니다(SSO의 isAdmin 플래그 또는 대시보드 구성으로 설정).

sdk.load()를 호출한 후, SDK는 구성된 urlId에 대한 WebSocket 이벤트를 자동으로 구독합니다. 다음 이벤트들이 처리됩니다:

• 새로운 댓글, 수정 및 삭제
• 투표 (새로운 투표 및 취소)
• 고정, 잠금, 신고 및 차단 상태 변경
• 사용자 접속(입장/퇴장)
• 스레드 열림/닫힘
• 배지 수여
• 서버 구성 업데이트

실시간 표시 제어

기본적으로 다른 사용자의 새 댓글은 즉시 표시됩니다:

sdk.showLiveRightAway = true   // 기본값: 즉시 표시

이를 false로 설정하면 새 댓글이 "N개의 새 댓글" 버튼 뒤에 버퍼되어 사용자가 언제 표시할지 선택할 수 있습니다:

sdk.showLiveRightAway = false

사용자 접속

서버가 접속 상태 추적을 활성화하면 온라인/오프라인 표시기가 사용자 아바타에 자동으로 표시됩니다. 클라이언트에서 추가 구성은 필요하지 않습니다.

Page Size

// 댓글: 기본값 30
sdk.pageSize = 50

// 피드: 기본값 10
feedSDK.pageSize = 20

Loading More Comments

The UI shows pagination controls automatically. You can also trigger pagination programmatically:

// 다음 페이지 로드
try await sdk.loadMore()

// 모든 남은 항목 로드 (성능 상 댓글이 2000개 초과인 경우 비활성화됨)
try await sdk.loadAll()

// 상태 확인
sdk.hasMore            // 더 많은 페이지가 있는지
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Child Comment Pagination

중첩된 답글은 지연 로드됩니다. 사용자가 스레드를 확장하면 처음 5개의 자식이 로드됩니다. 더 많은 항목이 있으면 "더 많은 답글 불러오기" 컨트롤이 나타납니다. 이 동작은 UI에서 자동으로 처리됩니다.

Both FastCommentsSDK와 FastCommentsFeedSDK는 @Published 속성을 가진 ObservableObject 클래스입니다. SwiftUI 뷰에서 이를 관찰하여 반응형 UI 업데이트를 할 수 있습니다.

FastCommentsSDK Published 속성

FastCommentsFeedSDK Published 속성

댓글 트리

댓글 트리는 sdk.commentsTree를 통해 접근할 수 있습니다:

// 렌더링을 위한 표시된 노드의 평탄(Flat) 목록
sdk.commentsTree.visibleNodes

// ID로 댓글 조회
sdk.commentsTree.commentsById["comment-id"]

EU 데이터 센터를 사용하려면 구성의 region 필드를 설정하세요:

let config = FastCommentsWidgetConfig(
    tenantId: "YOUR_TENANT_ID",
    urlId: "my-page",
    region: "eu"
)

이렇게 하면 모든 API 요청과 WebSocket 연결이 eu.fastcomments.com으로 라우팅됩니다.

SDK 인스턴스 사용을 마쳤을 때(예: 뷰가 닫히는 경우), WebSocket 연결을 닫고 백그라운드 작업을 취소하려면 cleanup()을 호출하세요:

sdk.cleanup()

SwiftUI의 @StateObject로 관리되는 뷰의 경우, 일반적으로 .onDisappear에서 호출하거나 뷰가 해제될 때 호출합니다.

댓글

let imageUrl = try await sdk.uploadImage(imageData: jpegData, filename: "photo.jpg")

업로드된 이미지의 URL 문자열을 반환합니다.

피드 게시물

let mediaItem = try await feedSDK.uploadImage(imageData: jpegData, filename: "photo.jpg")

// 여러 이미지를 병렬로 업로드
let mediaItems = try await feedSDK.uploadImages(images: [
    (jpegData1, "photo1.jpg"),
    (jpegData2, "photo2.jpg")
])

@mention 자동완성을 지원하기 위해 사용자를 검색:

let results = try await sdk.searchUsers(query: "jan")
// [UserSearchResult]를 반환합니다. userId, username, avatar 등을 포함합니다.

내장된 CommentInputBar가 @mention 자동완성을 자동으로 처리합니다.

편집

try await sdk.editComment(commentId: commentId, newText: "Updated text")

서버가 HTML을 다시 렌더링합니다. 로컬 댓글이 자동으로 업데이트됩니다.

삭제

try await sdk.deleteComment(commentId: commentId)

댓글을 삭제하면 그 댓글의 하위 댓글들도 로컬 트리에서 함께 제거됩니다.

두 작업 모두 현재 사용자가 댓글 작성자(또는 사이트 관리자)인 경우 UI의 댓글 컨텍스트 메뉴를 통해 이용할 수 있습니다.

SDK 메서드는 FastCommentsError를 던지며, 이는 LocalizedError를 준수합니다:

do {
    try await sdk.load()
} catch let error as FastCommentsError {
    print(error.translatedError ?? error.reason ?? "Unknown error")
} catch {
    print(error.localizedDescription)
}

FastCommentsError 속성:

• code -- API의 오류 코드
• reason -- 영어 오류 설명
• translatedError -- 서버에서 제공한 현지화된 오류 메시지

차단 오류는 또한 sdk.blockingErrorMessage를 통해 자동으로 노출되며, 내장 뷰가 이를 사용자에게 표시합니다.

서버 제공 문자열을 현지화하려면 구성에 로케일 코드를 전달하세요:

let config = FastCommentsWidgetConfig(
    tenantId: "YOUR_TENANT_ID",
    urlId: "my-page",
    locale: "fr_fr"
)

클라이언트 측 UI 문자열은 iOS 번들 기반의 현지화를 사용합니다.

레포지토리에는 ExampleApp/에 전체 예제 앱이 포함되어 있으며 다음을 시연합니다:

• SSO 및 커스텀 테마를 사용하는 스레드형 댓글
• 게시물 생성 및 태그 필터링이 가능한 소셜 피드
• 라이브 채팅
• 간단하고 안전한 SSO 흐름
• 맞춤 툴바 버튼(댓글 및 피드)