Add Comments to Your iOS App

• Drzewiaste wątki komentarzy z zagnieżdżonymi odpowiedziami i paginacją
• Kanał społecznościowy z tworzeniem postów, reakcjami i załącznikami multimedialnymi
• Tryb czatu na żywo z automatycznym przewijaniem i separatorami dat
• Aktualizacje w czasie rzeczywistym poprzez WebSocket (nowe komentarze, głosy, obecność)
• Logowanie jednokrotne (Simple SSO do testów, Secure SSO do produkcji)
• Edytor tekstu sformatowanego z pogrubieniem, kursywą, kodem i @wzmiankami
• Głosowanie z konfigurowalnymi stylami (strzałki góra/dół lub serduszka)
• Działania moderacyjne: zgłoś, przypnij, zamknij, zablokuj
• Kompleksowe motywy z presetami i pełną możliwością dostosowania
• Niestandardowe przyciski paska narzędzi do tworzenia komentarzy i postów w kanale
• Przesyłanie obrazów
• Obsługa regionu UE
• Obecność użytkowników (wskaźniki online/offline)
• Filtrowanie kanału oparte na tagach
• Obsługa lokalizacji

• iOS 16+ lub macOS 14+
• Swift 5.9+
• SwiftUI

Dodaj FastCommentsUI do swojego projektu przy użyciu Menedżera pakietów Swift (Swift Package Manager).

W Xcode: File > Add Package Dependencies, następnie wpisz URL repozytorium.

Albo dodaj go do swojego Package.swift:

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

Następnie dodaj produkt do swojego targetu:

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

Zaimportuj oba moduły w miejscach, gdzie są potrzebne:

import FastCommentsUI
import FastCommentsSwift

Minimalna konfiguracja do wyświetlenia widżetu komentarzy:

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()
            }
    }
}

Zastąp "demo" swoim identyfikatorem najemcy FastComments. urlId identyfikuje stronę lub wątek, w którym przechowywane są komentarze.

FastComments obsługuje trzy tryby uwierzytelniania:

1. Anonimowy -- brak tokena SSO; użytkownicy otrzymują tożsamości oparte na sesji
2. Proste SSO -- token po stronie klienta do demo i testów (niebezpieczne)
3. Bezpieczne SSO -- token podpisany przez serwer do produkcji

Proste SSO

Przydatne do demo i testów lokalnych. Każdy może podszyć się pod dowolnego użytkownika przy użyciu Prostego SSO, więc nie używaj go w produkcji.

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 obsługuje również opcjonalne pola:

• id -- identyfikator użytkownika (domyślnie email, jeśli nie ustawiono)
• displayName -- osobna nazwa wyświetlana
• displayLabel -- niestandardowa etykieta pokazywana obok nazwy (np. "VIP")
• websiteUrl -- odnośnik przy nazwie użytkownika
• locale -- kod lokalizacji
• isProfileActivityPrivate -- ukryj aktywność profilu (domyślnie true)

Bezpieczne SSO

W produkcji twój backend generuje podpisany token SSO używając sekretu API. Aplikacja iOS pobiera ten token z twojego serwera i przekazuje go do konfiguracji.

Po stronie backendu (używając FastComments Swift SDK lub dowolnego języka):

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()
// Zwróć ten token do swojej aplikacji iOS za pośrednictwem API

W Twojej aplikacji 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 {
            // Pobierz token z twojego backendu
            let token = try? await fetchSSOTokenFromYourBackend()
            // Utwórz nową konfigurację z tokenem lub ustaw go przed załadowaniem
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData obsługuje dodatkowe pola:

• optedInNotifications -- zgoda na powiadomienia e-mail
• displayLabel -- niestandardowa etykieta
• displayName -- nazwa wyświetlana
• websiteUrl -- URL strony internetowej
• groupIds -- identyfikatory grup
• isAdmin -- uprawnienia administratora
• isModerator -- uprawnienia moderatora
• isProfileActivityPrivate -- ustawienie prywatności aktywności profilu

Podstawowe użycie

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()
            }
    }
}

Style głosowania

Domyślny styl głosowania pokazuje strzałki w górę/w dół. Przekaż ._1 dla głosów w stylu serca:

FastCommentsView(sdk: sdk, voteStyle: ._1)

Wywołania zwrotne zdarzeń

Użyj wywołań zwrotnych w stylu modyfikatorów, aby obsłużyć interakcje użytkownika:

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
        // źródło to .name lub .avatar
        print("Tapped \(userInfo.displayName)")
    }

Zastosowanie motywu

Przekaż motyw przez środowisko SwiftUI:

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

Lub ustaw go bezpośrednio w SDK:

sdk.theme = FastCommentsTheme.modern

Kierunek sortowania

sdk.defaultSortDirection = .nf  // Najnowsze pierwsze (domyślnie)
sdk.defaultSortDirection = .of  // Najstarsze pierwsze
sdk.defaultSortDirection = .mr  // Najbardziej istotne

LiveChatView zapewnia doświadczenie czatu w czasie rzeczywistym z automatycznym przewijaniem, separatorami dat i kompaktowym układem. Automatycznie konfiguruje SDK do sortowania od najstarszych oraz natychmiastowego wyświetlania na żywo.

struct ChatView: View {
    @StateObject private var sdk: FastCommentsSDK = {
        let config = FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "chat-room-1",
            sso: ssoToken  // SSO zalecane, aby użytkownicy mieli nazwy
        )
        return FastCommentsSDK(config: config)
    }()

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

LiveChatView obsługuje te wywołania zwrotne:

• .onCommentPosted -- wywoływane, gdy użytkownik wysyła wiadomość
• .onCommentDeleted -- wywoływane, gdy wiadomość zostanie usunięta
• .onUserClick -- wywoływane, gdy kliknięto nazwę użytkownika lub awatar

System feedów to oddzielne SDK (FastCommentsFeedSDK) z własnym widokiem.

Ładowanie i wyświetlanie feedu

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
                // Pokaż arkusz udostępniania
            }
            .onUserClick { context, userInfo, source in
                // Przejdź do profilu użytkownika
            }
            .onMediaClick { mediaItem, index in
                // Pokaż przeglądarkę obrazów na pełnym ekranie
            }
            .task {
                try? await sdk.load()
            }
    }
}

Widok feedu automatycznie obsługuje pull-to-refresh i nieskończone przewijanie.

Tworzenie postów

Użyj FeedPostCreateView, aby pokazać formularz tworzenia postu:

@State private var showCreatePost = false

// W ciele widoku:
.sheet(isPresented: $showCreatePost) {
    FeedPostCreateView(
        sdk: sdk,
        onPostCreated: { post in
            showCreatePost = false
            Task { try? await sdk.refresh() }
        },
        onCancelled: {
            showCreatePost = false
        }
    )
}

Reakcje na posty

SDK obsługuje reakcje z optymistycznymi aktualizacjami:

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

// Check reaction state
let hasLiked = sdk.hasUserReacted(postId: post.id, reactType: "l")
let likeCount = sdk.getLikeCount(postId: post.id)

Otwieranie komentarzy do posta

Użyj CommentsSheet, aby wyświetlić komentarze dla posta z feedu. Tworzy ona wewnętrznie instancję FastCommentsSDK używając konfiguracji feed SDK:

.sheet(item: $commentsPost) { post in
    CommentsSheet(post: post, feedSDK: sdk, onUserClick: { context, userInfo, source in
        // Obsłuż kliknięcie użytkownika
    })
}

Uwaga: FeedPost musi implementować protokół Identifiable dla .sheet(item:). Dodaj to rozszerzenie:

extension FeedPost: @retroactive Identifiable {}

Filtrowanie feedu według tagów

Zaimplementuj protokół TagSupplier, aby filtrować posty feedu według tagów:

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

sdk.tagSupplier = TeamTagSupplier()

Zwróć nil, aby uzyskać niefiltrowany, globalny feed.

Zapisywanie i przywracanie stanu feedu

Zachowaj stan paginacji pomiędzy zdarzeniami cyklu życia widoku:

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

Usuwanie postów

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

Presety motywów

Dostępne są cztery wbudowane presety:

// Ustawienia domyślne systemu
sdk.theme = FastCommentsTheme.default

// Karty z cieniami i dużymi zaokrąglonymi narożnikami
sdk.theme = FastCommentsTheme.modern

// Płaski, bez cieni, mały promień narożników, bez linii wątków
sdk.theme = FastCommentsTheme.minimal

// Ustaw wszystkie kolory akcji na pojedynczy kolor marki
sdk.theme = FastCommentsTheme.allPrimary(.indigo)

Style wyświetlania komentarzy

var theme = FastCommentsTheme()
theme.commentStyle = .flat    // Lista płaska z separatorami (domyślnie)
theme.commentStyle = .card    // Zaokrąglone karty z cieniami
theme.commentStyle = .bubble  // Styl dymków czatu

Kolory

Wszystkie właściwości kolorów są opcjonalne. Nieustawione wartości domyślnie użyją sensownych ustawień systemowych.

var theme = FastCommentsTheme()

// Kolory marki
theme.primaryColor = .indigo
theme.primaryLightColor = .indigo.opacity(0.6)
theme.primaryDarkColor = Color(red: 0.2, green: 0.1, blue: 0.5)

// Tła
theme.commentBackgroundColor = Color(.secondarySystemGroupedBackground)
theme.containerBackgroundColor = Color(.systemGroupedBackground)

// Przyciski akcji
theme.actionButtonColor = .indigo
theme.replyButtonColor = .indigo
theme.toggleRepliesButtonColor = .indigo.opacity(0.8)
theme.loadMoreButtonTextColor = .indigo

// Głosy
theme.voteActiveColor = .red
theme.voteCountColor = .primary
theme.voteCountZeroColor = .secondary
theme.voteDividerColor = Color(.separator)

// Linki
theme.linkColor = .indigo
theme.linkColorPressed = .indigo.opacity(0.5)

// Okna dialogowe
theme.dialogHeaderBackgroundColor = .indigo
theme.dialogHeaderTextColor = .white

// Pasek wprowadzania
theme.inputBarBackgroundColor = Color(.systemBackground)
theme.inputBarBorderColor = Color(.separator)

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

Typografia

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

Układ i odstępy

theme.cornerRadius = .large       // .none, .small, .medium, .large
theme.commentSpacing = 4          // Punkty między wierszami komentarzy
theme.nestingIndent = 20          // Punkty wcięcia na poziom zagnieżdżenia
theme.avatarSize = 36             // Średnica avatara dla komentarzy głównych
theme.replyAvatarSize = 28        // Średnica avatara dla zagnieżdżonych odpowiedzi

Efekty wizualne

theme.showShadows = true          // Subtelne cienie na kartach
theme.showThreadLine = true       // Pionowa linia łącząca zagnieżdżone odpowiedzi
theme.animateVotes = true         // Animacja sprężynowa przy zmianie głosów

Zastosowanie motywów

Dwa sposoby:

// Poprzez środowisko SwiftUI (zalecane dla hierarchii widoków)
FastCommentsView(sdk: sdk)
    .fastCommentsTheme(theme)

// Bezpośrednio w SDK
sdk.theme = theme

Przyciski paska narzędzi komentarza

Zaimplementuj protokół CustomToolbarButton, aby dodać przyciski do paska narzędzi pola wprowadzania komentarza:

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // nazwa symbolu SF
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // Opcjonalny licznik odznaki

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

    // Opcjonalne nadpisania (domyślnie true)
    func isEnabled() -> Bool { true }
    func isVisible() -> Bool { true }
}

Przekaż niestandardowe przyciski podczas tworzenia widoku:

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

Lub dodaj je globalnie do SDK (ma zastosowanie do wszystkich instancji):

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

Przyciski paska narzędzi kanału

Zaimplementuj FeedCustomToolbarButton dla formularza tworzenia posta:

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

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

Przekaż je do widoku tworzenia:

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

Lub ustaw je globalnie w SDK kanału:

sdk.globalFeedToolbarButtons = [HashtagButton()]

Akcje dostępne dla wszystkich użytkowników

• Zgłoś/Usuń zgłoszenie -- zgłoś komentarz do przeglądu

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

• Zablokuj użytkownika/Odblokuj użytkownika -- ukryj wszystkie komentarze od użytkownika (dla danego widza)

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

Akcje tylko dla administratorów

• Przypnij/Odprzypnij -- przypnij komentarz na górze wątku

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

• Zablokuj/Odblokuj -- uniemożliwić dodawanie nowych odpowiedzi do komentarza

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

Wszystkie akcje moderacyjne są również dostępne poprzez menu kontekstowe komentarza w interfejsie użytkownika. Akcje administracyjne pojawiają się tylko, gdy bieżący użytkownik jest administratorem serwisu (ustawione poprzez flagę SSO isAdmin lub konfigurację w panelu administracyjnym).

Po wywołaniu sdk.load() SDK automatycznie subskrybuje zdarzenia WebSocket dla skonfigurowanego urlId. Obsługiwane są następujące zdarzenia:

• Nowe komentarze, edycje i usunięcia
• Głosy (dodane i usunięte)
• Zmiany stanu przypięcia, blokady, zgłaszania i blokowania
• Obecność użytkowników (wejście/wyjście)
• Otwarcie/zamknięcie wątku
• Przyznawanie odznak
• Aktualizacje konfiguracji serwera

Sterowanie wyświetlaniem na żywo

Domyślnie nowe komentarze od innych użytkowników pojawiają się natychmiast:

sdk.showLiveRightAway = true   // Domyślnie: pokaż od razu

Ustaw to na false, aby buforować nowe komentarze za przyciskiem "N nowych komentarzy", pozwalając użytkownikowi wybrać, kiedy je ujawnić:

sdk.showLiveRightAway = false

Obecność użytkowników

Wskaźniki online/offline pojawiają się automatycznie na avatarach użytkowników, gdy serwer włącza śledzenie obecności. Po stronie klienta nie jest wymagana dodatkowa konfiguracja.

Rozmiar strony

// Komentarze: domyślnie 30
sdk.pageSize = 50

// Kanał: domyślnie 10
feedSDK.pageSize = 20

Ładowanie kolejnych komentarzy

Interfejs użytkownika automatycznie wyświetla kontrolki paginacji. Możesz też wywołać paginację programowo:

// Załaduj następną stronę
try await sdk.loadMore()

// Załaduj wszystkie pozostałe (wyłączone jeśli >2000 komentarzy ze względów wydajnościowych)
try await sdk.loadAll()

// Sprawdź stan
sdk.hasMore            // Czy istnieją kolejne strony
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Paginacja komentarzy podrzędnych

Zagnieżdżone odpowiedzi ładują się leniwie. Gdy użytkownik rozwija wątek, ładowane są pierwsze 5 odpowiedzi podrzędnych. Pojawia się kontrolka "załaduj więcej odpowiedzi", jeśli istnieją kolejne. Jest to obsługiwane automatycznie przez interfejs użytkownika.

Obie FastCommentsSDK i FastCommentsFeedSDK są klasami ObservableObject z właściwościami @Published. Możesz obserwować je w swoich widokach SwiftUI, aby uzyskać reaktywne aktualizacje interfejsu użytkownika.

Właściwości publikowane FastCommentsSDK

Właściwości publikowane FastCommentsFeedSDK

Drzewo komentarzy

Drzewo komentarzy jest dostępne przez sdk.commentsTree:

// Płaska lista widocznych węzłów do renderowania
sdk.commentsTree.visibleNodes

// Wyszukaj komentarz po ID
sdk.commentsTree.commentsById["comment-id"]

Aby korzystać z centrum danych UE, ustaw pole region w swojej konfiguracji:

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

Spowoduje to przekierowanie wszystkich żądań API i połączeń WebSocket do eu.fastcomments.com.

Gdy zakończysz pracę z instancją SDK (np. gdy widok jest zamykany), wywołaj cleanup(), aby zamknąć połączenie WebSocket i anulować zadania w tle:

sdk.cleanup()

W przypadku widoków zarządzanych przez SwiftUI przy użyciu @StateObject, zwykle wywołuje się to w .onDisappear lub gdy widok zostanie zdealokowany.

KomenTarze

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

Zwraca ciąg URL przesłanego obrazu.

Posty w kanale

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

// Prześlij wiele obrazów równolegle
let mediaItems = try await feedSDK.uploadImages(images: [
    (jpegData1, "photo1.jpg"),
    (jpegData2, "photo2.jpg")
])

Wyszukaj użytkowników, aby obsłużyć autouzupełnianie @mention:

let results = try await sdk.searchUsers(query: "jan")
// Zwraca [UserSearchResult] z userId, username, avatar, itd.

Wbudowany CommentInputBar automatycznie obsługuje autouzupełnianie @mention.

Edytuj

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

Serwer ponownie renderuje HTML. Lokalny komentarz aktualizuje się automatycznie.

Usuń

try await sdk.deleteComment(commentId: commentId)

Usunięcie komentarza usuwa również jego potomków z lokalnego drzewa.

Obie akcje są dostępne w menu kontekstowym komentarza w interfejsie użytkownika, gdy aktualny użytkownik jest autorem komentarza (lub administratorem strony).

Metody SDK zgłaszają FastCommentsError, który implementuje LocalizedError:

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

FastCommentsError properties:

• code -- kod błędu z API
• reason -- opis błędu w języku angielskim
• translatedError -- lokalizowany komunikat o błędzie dostarczony przez serwer

Błędy blokujące są również automatycznie udostępniane przez sdk.blockingErrorMessage, a wbudowane widoki wyświetlają je użytkownikowi.

Przekaż kod lokalizacji w konfiguracji, aby zlokalizować ciągi dostarczane przez serwer:

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

Ciągi interfejsu użytkownika po stronie klienta korzystają z lokalizacji opartej na bundle iOS.

Repozytorium zawiera pełną aplikację przykładową w ExampleApp/ z demonstracjami:

• Komentarze w wątkach z SSO i niestandardowymi motywami
• Kanał społecznościowy z tworzeniem postów i filtrowaniem po tagach
• Czat na żywo
• Proste i bezpieczne przepływy SSO
• Niestandardowe przyciski paska narzędzi (komentarze i kanał)