Add Comments to Your iOS App

• Stabla komentara s ugniježđenim odgovorima i paginacijom
• Društveni feed s kreiranjem objava, reakcijama i medijskim prilozima
• Chat uživo s automatskim pomicanjem i separatorima datuma
• Ažuriranja u stvarnom vremenu putem WebSocket-a (novi komentari, glasovi, prisutnost)
• Jedinstvena prijava (Simple SSO za testiranje, Secure SSO za produkciju)
• Uređivanje bogatog teksta s podebljanim, kurzivom, kodom i @spominjanjima
• Glasanje s konfigurabilnim stilovima (strelice gore/dolje ili srca)
• Moderacijske radnje: prijava, prikvačivanje, zaključavanje, blokiranje
• Sveobuhvatno upravljanje temama s predlošcima i potpunom prilagodbom
• Prilagođeni gumbi na alatnoj traci za komentare i kreiranje objava u feedu
• Učitavanje slika
• Podrška za regiju EU
• Prisutnost korisnika (indikatori online/offline)
• Filtriranje feeda po oznakama
• Podrška za lokalizaciju

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

Dodajte FastCommentsUI u svoj projekt koristeći Swift Package Manager.

U Xcodeu: File > Add Package Dependencies, zatim unesite URL repozitorija.

Ili ga dodajte u svoj Package.swift:

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

Zatim dodajte proizvod vašem targetu:

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

Uvezite oba modula gdje je potrebno:

import FastCommentsUI
import FastCommentsSwift

Minimalna konfiguracija za prikaz widgeta za komentare:

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

Zamijenite "demo" sa svojim FastComments tenant ID-jem. urlId identificira stranicu ili nit na kojoj se komentari pohranjuju.

FastComments podržava tri načina autentikacije:

1. Anonimno -- bez SSO tokena; korisnici dobivaju identitete temeljene na sesiji
2. Jednostavni SSO -- klijentski token za demo i testiranje (nije sigurno)
3. Sigurni SSO -- token potpisan na serveru za produkciju

Jednostavni SSO

Koristan za demo i lokalno testiranje. Bilo tko može se predstaviti kao bilo koji korisnik pomoću Jednostavnog SSO-a, stoga ga nemojte koristiti 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đer podržava opcionalna polja:

• id -- ID korisnika (zadano na email ako nije postavljeno)
• displayName -- odvojeno prikazano ime
• displayLabel -- prilagođena oznaka prikazana pored imena (npr. "VIP")
• websiteUrl -- poveznica na korisničko ime
• locale -- kod lokalizacije
• isProfileActivityPrivate -- sakrij aktivnost profila (zadano na true)

Sigurni SSO

U produkciji, vaš backend generira potpisani SSO token koristeći vaš API secret. iOS aplikacija dohvaća taj token s vašeg servera i prosljeđ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 ovaj token svojoj 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 {
            // Dohvatite token s vašeg backenda
            let token = try? await fetchSSOTokenFromYourBackend()
            // Kreirajte novu konfiguraciju s tokenom, ili ga postavite prije učitavanja
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData podržava dodatna polja:

• optedInNotifications -- pristanak na e-mail obavijesti
• displayLabel -- prilagođena oznaka
• displayName -- prikazano ime
• websiteUrl -- URL web stranice
• 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

Zadani stil glasanja prikazuje strelice gore/dolje. Proslijedite ._1 za stil glasanja u obliku srca:

FastCommentsView(sdk: sdk, voteStyle: ._1)

Povratni pozivi događaja

Koristite povratne pozive u obliku modifikatora za rukovanje korisničkim interakcijama:

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

Primjena teme

Proslijedite temu putem SwiftUI okruženja:

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

Ili postavite izravno na SDK:

sdk.theme = FastCommentsTheme.modern

Smjer sortiranja

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

LiveChatView pruža iskustvo chata u stvarnom vremenu s automatskim pomicanjem, razdjelnicima datuma i kompaktim izgledom. Automatski konfigurira SDK za sortiranje od najstarijih prema najnovijima i trenutni prikaz 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 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 ove povratne pozive:

• .onCommentPosted -- pozvano kada korisnik pošalje poruku
• .onCommentDeleted -- pozvano kada se poruka izbriše
• .onUserClick -- pozvano kada se dodirne ime ili avatar korisnika

Sustav feeda je zaseban SDK (FastCommentsFeedSDK) s vlastitim 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 dijaloški okvir za dijeljenje
            }
            .onUserClick { context, userInfo, source in
                // Navigiraj do korisničkog profila
            }
            .onMediaClick { mediaItem, index in
                // Prikaži pregled slike preko cijelog zaslona
            }
            .task {
                try? await sdk.load()
            }
    }
}

Prikaz feeda automatski uključuje povlačenje za osvježavanje i beskonačno skrolanje.

Kreiranje objava

Koristite FeedPostCreateView za prikaz obrasca za stvaranje 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
        }
    )
}

Reakcije na objave

SDK upravlja reakcijama koristeći optimistička ažuriranja:

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

// Provjeri 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. Interno stvara instancu FastCommentsSDK koristeći konfiguraciju feed SDK-a:

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

Napomena: FeedPost mora implementirati Identifiable radi korištenja .sheet(item:). Dodajte ovo proširenje:

extension FeedPost: @retroactive Identifiable {}

Filtriranje feeda prema tagovima

Implementirajte protokol TagSupplier za filtriranje objava u feedu prema tagovima:

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

sdk.tagSupplier = TeamTagSupplier()

Vrati nil za nefiltrirani globalni feed.

Spremanje i vraćanje stanja feeda

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

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

Brisanje objava

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

Predlošci tema

Dostupna su četiri ugrađena predloška:

// Zadane sistemske vrijednosti
sdk.theme = FastCommentsTheme.default

// Kartice sa sjenama i velikim zaobljenim kutovima
sdk.theme = FastCommentsTheme.modern

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

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

Stilovi prikaza komentara

var theme = FastCommentsTheme()
theme.commentStyle = .flat    // Ravna lista s razdjelnicima (zadano)
theme.commentStyle = .card    // Zaobljene kartice sa sjenama
theme.commentStyle = .bubble  // Stil razgovornih mjehurića

Boje

Sva svojstva boja su opcionalna. Nepostavljene vrijednosti vraćaju se na razumne zadane vrijednosti sustava.

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)

// Akcijski gumbi
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)

// Poveznice
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          // Bodova između redova komentara
theme.nestingIndent = 20          // Bodova uvlačenja po razini ugnježđivanja
theme.avatarSize = 36             // Promjer avatara za komentare najviše razine
theme.replyAvatarSize = 28        // Promjer avatara za ugnježdene odgovore

Vizualni efekti

theme.showShadows = true          // Diskretne sjene na karticama
theme.showThreadLine = true       // Vertikalna linija koja povezuje ugnježdene odgovore
theme.animateVotes = true         // Animacija s efektom opruge pri promjeni glasova

Primjena tema

Dva pristupa:

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

// Izravno na SDK
sdk.theme = theme

Gumbi alatne trake za komentare

Implementirajte protokol CustomToolbarButton kako biste dodali gumbe u alatnu traku za unos komentara:

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // Naziv SF simbola
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // Neobavezni broj značke

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

    // Neobavezni overridei (zadano true)
    func isEnabled() -> Bool { true }
    func isVisible() -> Bool { true }
}

Proslijedite prilagođene gumbe prilikom stvaranja prikaza:

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

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

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

Gumbi alatne trake feeda

Implementirajte FeedCustomToolbarButton za obrazac za stvaranje objava:

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

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

Proslijedite ih prikazu za stvaranje:

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

Ili ih postavite globalno na feed SDK:

sdk.globalFeedToolbarButtons = [HashtagButton()]

Radnje dostupne svim korisnicima

• Prijavi/Otkaži prijavu -- prijavite komentar na pregled

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

• Blokiraj/Odblokiraj -- sakrij sve komentare od korisnika (po gledatelju)

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

Radnje samo za administratore

• Prikvači/Odveži -- prikvači komentar na vrh rasprave

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

• Zaključaj/Otključaj -- spriječi nove odgovore na komentar

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

Sve radnje moderiranja također su dostupne kroz kontekstni izbornik komentara u korisničkom sučelju. Administratorske radnje pojavljuju se samo kada je trenutni korisnik administrator web-mjesta (postavljeno putem SSO isAdmin zastavice ili konfiguracije nadzorne ploče).

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

• Novi komentari, izmjene i brisanja
• Glasovi (dodani i uklonjeni)
• Promjene stanja pričvršćivanja (pin), zaključavanja, označavanja (flag) i blokiranja
• Prisustvo korisnika (ulazak/izlazak)
• Otvaranje/zatvaranje teme
• Dodjela znački
• Ažuriranja konfiguracije poslužitelja

Kontrola prikaza uživo

Prema zadanim postavkama, novi komentari drugih korisnika pojavljuju se odmah:

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

Postavite ovo na false da biste nove komentare stavili u međuspremnik iza gumba "N novih komentara", dopuštajući korisniku da odabere kada ih otkriti:

sdk.showLiveRightAway = false

Prisustvo korisnika

Pokazivači online/offline statusa automatski se pojavljuju na avatarima korisnika kada poslužitelj omogući praćenje prisutnosti. Nije potrebna dodatna konfiguracija na klijentu.

Veličina stranice

// Komentari: zadano 30
sdk.pageSize = 50

// Feed: zadano 10
feedSDK.pageSize = 20

Učitavanje više komentara

UI automatski prikazuje kontrole za paginaciju. Također možete programatski pokrenuti paginaciju:

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

// Učitaj sve preostale (onemogućeno ako >2000 komentara zbog performansi)
try await sdk.loadAll()

// Provjeri stanje
sdk.hasMore            // Postoje li još stranica
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Paginacija podkomentara

Ugniježđeni odgovori se učitavaju lenjo. Kad korisnik proširi nit, prvih 5 podkomentara se učita. Pojavljuje se kontrola "učitaj još odgovora" ako ih ima više. Time se rukuje automatski u UI-ju.

I FastCommentsSDK i FastCommentsFeedSDK su klase ObservableObject s @Published svojstvima. Možete ih promatrati u svojim SwiftUI prikazima za reaktivna ažuriranja korisničkog sučelja.

FastCommentsSDK Objavljena svojstva

FastCommentsFeedSDK Objavljena svojstva

Stablo komentara

Stablo komentara dostupno je putem sdk.commentsTree:

// Ravan popis vidljivih čvorova za renderiranje
sdk.commentsTree.visibleNodes

// Potraži komentar po ID-u
sdk.commentsTree.commentsById["comment-id"]

Da biste koristili podatkovni centar EU, postavite polje region u vašoj konfiguraciji:

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

Ovo usmjerava sve API zahtjeve i WebSocket veze na eu.fastcomments.com.

Kad završite s instancom SDK-a (npr. pogled se zatvara), pozovite cleanup() da zatvorite WebSocket vezu i otkažete pozadinske zadatke:

sdk.cleanup()

Za poglede kojima upravlja SwiftUI-ov @StateObject, ovo se obično poziva u .onDisappear ili kada je pogled dealociran.

Komentari

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

Vraća URL string otpremljene slike.

Objave u feedu

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

// Otpremite više slika paralelno
let mediaItems = try await feedSDK.uploadImages(images: [
    (jpegData1, "photo1.jpg"),
    (jpegData2, "photo2.jpg")
])

Pretraživanje korisnika za podršku automatskom dovršavanju @mention:

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

Ugrađeni CommentInputBar automatski upravlja dovršavanjem @mention.

Uredi

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

Poslužitelj ponovno renderira HTML. Lokalni komentar se automatski ažurira.

Izbriši

try await sdk.deleteComment(commentId: commentId)

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

Obje radnje dostupne su putem kontekstnog izbornika komentara u korisničkom sučelju (UI) kada je trenutni korisnik autor komentara (ili administrator stranice).

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 pogreške iz API-ja
• reason -- engleski opis pogreške
• translatedError -- lokalizirana poruka o pogrešci koju pruža server

Blokirajuće pogreške također se automatski prikazuju putem sdk.blockingErrorMessage, koje ugrađeni prikazi prikazuju korisniku.

Proslijedite kod lokalizacije u konfiguraciji kako biste lokalizirali tekstove koje pruža poslužitelj:

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

Tekstovi korisničkog sučelja na strani klijenta koriste lokalizaciju temeljenu na iOS bundle-u.

Repozitorij sadrži kompletnu aplikaciju primjera u ExampleApp/ s demonstracijama:

• Komentari u nitima s SSO i prilagođenim temama
• Društveni feed s kreiranjem objava i filtriranjem po oznakama
• Razgovor uživo
• Jednostavni i sigurni SSO tokovi
• Prilagođeni gumbi alatne trake (komentari i feed)