Dodajte komentare u vašu iOS aplikaciju

Obezbedite svom kodirajućem agentu FastComments kontekst koji mu je potreban – vidžeti, konfiguracija, Secure SSO, REST API i SDK‑ovi:

npx skills add fastcomments/skills

Radi sa Claude Code, Codex, Cursor, Copilot, Gemini i svakim drugim agentom koji podržava skills CLI.

• Ugnježdena stabla komentara sa ugnježdenim odgovorima i paginacijom
• Društveni feed sa kreiranjem objava, reakcijama i prilozima medija
• Režim četa uživo sa automatskim skrolovanjem i separatorima datuma
• Ažuriranja u realnom vremenu preko WebSocket-a (novi komentari, glasovi, prisutnost)
• Single Sign-On (Simple SSO za testiranje, Secure SSO za produkciju)
• Uređivanje bogatog teksta sa podebljanim, kurzivom, kodom i @pominjanjima
• Glasanje sa konfigurisanim stilovima (strelice gore/dole ili srca)
• Moderacione akcije: prijavi, zakači, zaključaj, blokiraj
• Sveobuhvatno temiranje sa presetima i potpunom prilagodljivošću
• Prilagođena dugmad na alatnoj traci za komentare i kreiranje objava u feedu
• Otpremanje slika
• Podrška za region EU
• Prisutnost korisnika (indikatori online/offline)
• Filtriranje feeda po tagovima
• Podrška za lokalizaciju

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

Dodajte FastCommentsUI u vaš projekat koristeći Swift Package Manager.

U Xcode-u: File > Add Package Dependencies, zatim unesite URL repozitorijuma.

Ili ga dodajte u vaš Package.swift:

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

Zatim dodajte proizvod u vaš target:

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

Uvezite oba modula gde je potrebno:

import FastCommentsUI
import FastCommentsSwift

Minimalna podešavanja za prikaz komentarskog widgeta:

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

Zamenite "demo" sa vašim FastComments tenant ID. Polje urlId identifikuje stranicu ili nit gde se komentari čuvaju.

FastComments podržava tri režima autentifikacije:

1. Anonimni -- bez SSO tokena; korisnici dobijaju identitete zasnovane na sesiji
2. Jednostavni SSO -- token na klijentskoj strani za demonstracije i testiranje (nije siguran)
3. Sigurni SSO -- token potpisan na serveru za produkciju

Jednostavni SSO

Korisno za demonstracije i lokalno testiranje. Bilo ko može da se predstavi kao bilo koji korisnik pomoću Jednostavnog SSO-a, pa ga ne koristite u produkciji.

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 takođe podržava opcione polja:

• id -- ID korisnika (podrazumevano email ako nije postavljen)
• displayName -- odvojeni ime za prikaz
• displayLabel -- prilagođena oznaka prikazana pored imena (npr. "VIP")
• websiteUrl -- link na korisničkom imenu
• locale -- kod lokalizacije
• isProfileActivityPrivate -- sakrij aktivnost profila (podrazumevano true)

Sigurni SSO

U produkciji, vaš backend generiše potpisani SSO token koristeći vašu API tajnu. iOS aplikacija preuzima ovaj token sa vašeg servera i prosleđuje ga u konfiguraciju.

Na vašem backendu (koristeći FastComments Swift SDK ili bilo koji jezik):

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()
// Vratite ovu token vašoj iOS aplikaciji putem vašeg API-ja

U vašoj iOS aplikaciji:

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 {
            // Preuzmite token sa vašeg backend-a
            let token = try? await fetchSSOTokenFromYourBackend()
            // Kreirajte novu konfiguraciju sa tokenom, ili ga postavite pre učitavanja
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData podržava dodatna polja:

• optedInNotifications -- prijava za email obaveštenja
• displayLabel -- prilagođena oznaka
• displayName -- ime za prikaz
• websiteUrl -- URL veb-sajta
• groupIds -- članstva u grupama
• isAdmin -- administratorske privilegije
• isModerator -- moderatorske privilegije
• isProfileActivityPrivate -- privatnost profila

Osnovna upotreba

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

Stilovi glasanja

Podrazumevani stil glasanja prikazuje strelice gore/dole. Prosledite ._1 za glasanje u obliku srca:

FastCommentsView(sdk: sdk, voteStyle: ._1)

Povratni pozivi događaja

Koristite callback funkcije u stilu modifikatora za rukovanje interakcijama korisnika:

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
        // izvor je .name ili .avatar
        print("Tapped \(userInfo.displayName)")
    }

Primena teme

Prosledite temu kroz SwiftUI okruženje:

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

Ili je postavite direktno na SDK:

sdk.theme = FastCommentsTheme.modern

Smer sortiranja

sdk.defaultSortDirection = .nf  // Najnovije prvo (podrazumevano)
sdk.defaultSortDirection = .of  // Najstarije prvo
sdk.defaultSortDirection = .mr  // Najrelevantnije

LiveChatView pruža iskustvo chata u realnom vremenu sa automatskim skrolovanjem, separatorima po datumima i kompaktnim izgledom. Automatski konfiguriše SDK za sortiranje od najstarijih i trenutno prikazivanje uživo.

struct ChatView: View {
    @StateObject private var sdk: FastCommentsSDK = {
        let config = FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "chat-room-1",
            sso: ssoToken  // Preporučeno je korišćenje SSO kako bi korisnici imali imena
        )
        return FastCommentsSDK(config: config)
    }()

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

LiveChatView podržava sledeće povratne pozive:

• .onCommentPosted -- se poziva kada korisnik pošalje poruku
• .onCommentDeleted -- se poziva kada je poruka obrisana
• .onUserClick -- se poziva kada se klikne ime ili avatar korisnika

Sistem feed-a je zaseban SDK (FastCommentsFeedSDK) sa sopstvenim prikazom.

Učitavanje i prikaz feeda

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
                // Prikaži dijalog za deljenje
            }
            .onUserClick { context, userInfo, source in
                // Otvori korisnički profil
            }
            .onMediaClick { mediaItem, index in
                // Prikaži prikaz slike preko celog ekrana
            }
            .task {
                try? await sdk.loadIfNeeded()
            }
    }
}

Prikaz feeda automatski podržava povlačenje za osvežavanje i beskonačno skrolovanje. Koristite loadIfNeeded() pri ponovnom učitavanju ekrana da postojeći ili vraćeni feed ne bi bio resetovan na stranicu 1.

Kreiranje objava

Koristite FeedPostCreateView za prikaz forme za kreiranje objave:

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

Reagovanje na objave

SDK upravlja reakcijama koristeći optimističke promene:

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

// Proveri stanje reakcije
let hasLiked = sdk.hasUserReacted(postId: post.id, reactType: "l")
let likeCount = sdk.getLikeCount(postId: post.id)

Otvaranje komentara na objavu

Koristite CommentsSheet za prikaz komentara za objavu u feedu. Pri tome interno kreira FastCommentsSDK instancu koristeći konfiguraciju feed SDK-a:

.sheet(item: $commentsPost) { post in
    CommentsSheet(post: post, feedSDK: sdk, onUserClick: { context, userInfo, source in
        // Obradi klik na korisnika
    })
}

Napomena: FeedPost mora da se pridržava Identifiable za .sheet(item:). Dodajte ovo proširenje:

extension FeedPost: @retroactive Identifiable {}

Filtriranje feeda po tagovima

Implementirajte TagSupplier protokol da filtrirate objave u feedu po tagovima:

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

sdk.tagSupplier = TeamTagSupplier()

Vratite nil za nefiltrirani globalni feed.

Čuvanje i vraćanje stanja feeda

Sačuvajte stanje paginacije kroz događaje životnog ciklusa prikaza:

let state = sdk.savePaginationState()
// Later...
sdk.restorePaginationState(state)
try? await sdk.loadIfNeeded()

Ako se vaš ekran privremeno sakrije, prikaz feeda automatski pauzira live ažuriranja i nastavlja ih kada se ponovo pojavi, bez brisanja učitanih objava. Pozovite sdk.cleanup() samo kada ste zaista završili sa tom SDK instancom.

Brisanje objava

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

Predlošci teme

Dostupna su četiri ugrađena predloška:

// Sistemske podrazumevane vrednosti
sdk.theme = FastCommentsTheme.default

// Kartice sa senkama i velikim zaobljenim uglovima
sdk.theme = FastCommentsTheme.modern

// Ravno, bez senki, mali radijus uglova, bez linija niti
sdk.theme = FastCommentsTheme.minimal

// Podesi sve boje akcija na jednu boju brenda
sdk.theme = FastCommentsTheme.allPrimary(.indigo)

Stilovi prikaza komentara

var theme = FastCommentsTheme()
theme.commentStyle = .flat    // Ravna lista sa separatorima (podrazumevano)
theme.commentStyle = .card    // Zaobljene kartice sa senkama
theme.commentStyle = .bubble  // Stil poruka u balončićima

Boje

Sva svojstva boja su opciona. Nepodešene vrednosti vraćaju se na razumne sistemske podrazumevane vrednosti.

var theme = FastCommentsTheme()

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

// Pozadine
theme.commentBackgroundColor = Color(.secondarySystemGroupedBackground)
theme.containerBackgroundColor = Color(.systemGroupedBackground)

// Dugmad za akcije
theme.actionButtonColor = .indigo
theme.replyButtonColor = .indigo
theme.toggleRepliesButtonColor = .indigo.opacity(0.8)
theme.loadMoreButtonTextColor = .indigo

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

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

// Dijalozi
theme.dialogHeaderBackgroundColor = .indigo
theme.dialogHeaderTextColor = .white

// Traka za unos
theme.inputBarBackgroundColor = Color(.systemBackground)
theme.inputBarBorderColor = Color(.separator)

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

Tipografija

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

Raspored i razmaci

theme.cornerRadius = .large       // .none, .small, .medium, .large
theme.commentSpacing = 4          // Tačaka između redova komentara
theme.nestingIndent = 20          // Tačaka uvlačenja po nivou ugnježđivanja
theme.avatarSize = 36             // Prečnik avatara za korenske komentare
theme.replyAvatarSize = 28        // Prečnik avatara za ugnježdene odgovore

Vizuelni efekti

theme.showShadows = true          // Suptilne senke na karticama
theme.showThreadLine = true       // Vertikalna linija koja povezuje ugnježdene odgovore
theme.animateVotes = true         // Animacija sa oprugom pri promenama glasova

Primena tema

Dva pristupa:

// Preko SwiftUI okruženja (preporučeno za hijerarhiju prikaza)
FastCommentsView(sdk: sdk)
    .fastCommentsTheme(theme)

// Direktno na SDK-u
sdk.theme = theme

Dugmad trake sa alatima za komentare

Implementirajte protokol CustomToolbarButton da biste dodali dugmad na traku sa alatima za unos komentara:

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // SF Symbol name
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // Optional badge count

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

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

Prosledite prilagođena dugmad prilikom kreiranja prikaza:

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

Ili ih dodajte globalno na SDK (primenjuje se na sve instance):

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

Dugmad trake sa alatima za feed

Implementirajte FeedCustomToolbarButton za formu kreiranja objave:

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

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

Prosledite ih prikazu za kreiranje:

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

Ili ih postavite globalno na feed SDK:

sdk.globalFeedToolbarButtons = [HashtagButton()]

Radnje dostupne svim korisnicima

• Flag/Unflag -- prijavi komentar za reviziju

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

• Block/Unblock -- sakrij sve komentare od korisnika (po gledatelju)

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

Akcije samo za admina

• Pin/Unpin -- zakači komentar na vrh teme

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

• Lock/Unlock -- spriječi nove odgovore na komentar i blokiraj uređivanja i brisanje dok se ne otključa (važi za sve, uključujući moderatore)

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

Sve akcije moderacije takođe su dostupne kroz kontekstni meni komentara u UI. Administratorske akcije se prikazuju samo kada je trenutni korisnik admin sajta (postavljen putem SSO isAdmin flag ili konfiguracijom na kontrolnoj tabli).

Nakon poziva sdk.load(), SDK se automatski pretplaćuje na WebSocket događaje za konfigurisani urlId. Sledeći događaji se obrađuju:

• Novi komentari, izmene i brisanja
• Glasovi (novi i uklonjeni)
• Promene stanja pin, lock, flag i block
• Prisutnost korisnika (pridruživanje/napuštanje)
• Otvaranje/zatvaranje thread-a
• Dodeljivanje bedževa
• Ažuriranja konfiguracije servera

Kontrola prikaza uživo

Podrazumevano, novi komentari drugih korisnika pojavljuju se odmah:

sdk.showLiveRightAway = true   // Podrazumevano: prikaži odmah

Postavite ovo na false da biste keširali nove komentare iza dugmeta "N novih komentara", dopuštajući korisniku da izabere kada će ih prikazati:

sdk.showLiveRightAway = false

Prisutnost korisnika

Indikatori online/offline se automatski pojavljuju na avatarima korisnika kada server omogući praćenje prisustva. Na klijentskoj strani nije potrebna dodatna konfiguracija.

Veličina stranice

// Komentari: podrazumevano 30
sdk.pageSize = 50

// Feed: podrazumevano 10
feedSDK.pageSize = 20

Učitavanje više komentara

UI automatski prikazuje kontrole za paginaciju. Takođe možete pokrenuti paginaciju programski:

// Učitaj sledeću stranicu
try await sdk.loadMore()

// Učitaj sve preostalo (onemogućeno ako ima >2000 komentara, radi performansi)
try await sdk.loadAll()

// Proveri stanje
sdk.hasMore            // Da li postoje dodatne stranice
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Paginacija podređenih komentara

Ugnježdeni odgovori se učitavaju lenjo. Kada korisnik proširi nit, učitava se prvih 5 podređenih komentara. Ako ih ima više, pojavljuje se kontrola "učitaj još odgovora". Ovo UI automatski rešava.

I FastCommentsSDK i FastCommentsFeedSDK su ObservableObject klase sa @Published svojstvima. Možete ih posmatrati u vašim SwiftUI prikazima za reaktivna ažuriranja UI-ja.

FastCommentsSDK Published Properties

FastCommentsFeedSDK Published Properties

Stablo komentara

Stablu komentara se može pristupiti preko sdk.commentsTree:

// Flat list of visible nodes for rendering
sdk.commentsTree.visibleNodes

// Lookup a comment by ID
sdk.commentsTree.commentsById["comment-id"]

Da biste koristili EU data centar, postavite polje region u svojoj konfiguraciji:

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

Ovo usmerava sve API zahteve i WebSocket konekcije na eu.fastcomments.com.

Kada završite sa instancom SDK-a (npr. kada se prikaz odbacuje), pozovite cleanup() da zatvorite WebSocket konekciju i otkažete pozadinske zadatke:

sdk.cleanup()

Za poglede koje upravlja SwiftUI-jev @StateObject, ovo se obično poziva u .onDisappear ili kada se prikaz dealocira.

Komentari

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

Vraća URL (kao string) otpremljene slike.

Objave u feedu

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

// Upload multiple images in parallel
let mediaItems = try await feedSDK.uploadImages(images: [
    (jpegData1, "photo1.jpg"),
    (jpegData2, "photo2.jpg")
])

Pretražite korisnike da biste podržali automatsko dovršavanje @mention:

let results = try await sdk.searchUsers(query: "jan")
// Vraća [UserSearchResult] sa userId, username, avatar, itd.

Ugrađeni CommentInputBar automatski omogućava dovršavanje @mention.

Izmeni

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

Server ponovo renderuje HTML. Lokalni komentar se automatski ažurira.

Obriši

try await sdk.deleteComment(commentId: commentId)

Brisanje komentara takođe uklanja njegove potomke iz lokalnog stabla.

Obe radnje su dostupne kroz kontekstni meni komentara u UI kada je trenutni korisnik autor komentara (ili administrator sajta).

SDK metode bacaju FastCommentsError, koji se pridržava protokola LocalizedError:

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

FastCommentsError svojstva:

• code -- kod greške iz API-ja
• reason -- opis greške na engleskom jeziku
• translatedError -- lokalizovana poruka o grešci koju pruža server

Blokirajuće greške se takođe automatski prikazuju preko sdk.blockingErrorMessage, a ugrađeni prikazi ih prikazuju korisniku.

Prosledite kod lokala u konfiguraciji da biste lokalizovali stringove koje obezbeđuje server:

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

Tekstovi korisničkog interfejsa na klijentskoj strani koriste lokalizaciju zasnovanu na iOS bundle-u.

Repozitorijum sadrži kompletan primer aplikacije u ExampleApp/ sa demonstracijama of:

• Ugnježdeni komentari sa SSO i prilagođenim temama
• Društveni feed sa kreiranjem objava i filtriranjem po tagovima
• Chat uživo
• Jednostavni i sigurni SSO tokovi
• Prilagođena dugmad na alatnoj traci (komentari i feed)