Add Comments to Your iOS App

• 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: Datoteka > Dodaj zavisnosti paketa, zatim unesite URL repozitorijuma.

Ili dodajte ga u vaš Package.swift:

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

Zatim dodajte product 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 načina autentifikacije:

1. Anonymous -- nema SSO tokena; korisnici dobijaju identitete zasnovane na sesiji
2. Simple SSO -- token na strani klijenta za demo i testiranje (nije sigurno)
3. Secure SSO -- token potpisan na serveru za produkciju

Simple SSO

Koristan za demo i lokalno testiranje. Bilo ko može da se predstavi kao bilo koji korisnik pomoću Simple SSO, zato 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đe podržava opciona polja:

• id -- ID korisnika (podrazumevano email ako nije podešeno)
• displayName -- posebno prikazano ime
• displayLabel -- prilagođena oznaka prikazana pored imena (npr. "VIP")
• websiteUrl -- link na imenu korisnika
• locale -- jezički kod
• isProfileActivityPrivate -- sakrij aktivnost profila (podrazumevano je true)

Secure SSO

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

On your backend (using the FastComments Swift SDK or any language):

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()
// Return this token to your iOS app via your API

In your iOS app:

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 backenda
            let token = try? await fetchSSOTokenFromYourBackend()
            // Kreirajte novu konfiguraciju sa tokenom, ili je postavite pre učitavanja
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData podržava dodatna polja:

• optedInNotifications -- prijava za email notifikacije
• displayLabel -- prilagođena oznaka
• displayName -- prikazano ime
• websiteUrl -- URL vebsajta
• groupIds -- članstva u grupama
• isAdmin -- adminske privilegije
• isModerator -- moderatorske privilegije
• isProfileActivityPrivate -- privatnost aktivnosti 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 feed-a

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 sheet za deljenje
            }
            .onUserClick { context, userInfo, source in
                // Navigiraj do korisničkog profila
            }
            .onMediaClick { mediaItem, index in
                // Prikaži pregledač slike preko celog ekrana
            }
            .task {
                try? await sdk.load()
            }
    }
}

Prikaz feed-a uključuje pull-to-refresh i infinite scroll automatski.

Kreiranje objava

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

Reakcije na objave

SDK upravlja reakcijama sa optimističkim ažuriranjima:

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)

Otvaranje komentara na objavi

Koristite CommentsSheet za prikaz komentara za feed objavu. On kreira FastCommentsSDK instancu interno 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 da implementira Identifiable za .sheet(item:). Dodajte ovo proširenje:

extension FeedPost: @retroactive Identifiable {}

Filtriranje feed-a po tagovima

Implementirajte TagSupplier protokol da filtrirate feed objave 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 nefiltriran globalni feed.

Čuvanje i vraćanje stanja feed-a

Sačuvajte stanje paginacije preko događaja životnog ciklusa prikaza:

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

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

Comment Toolbar Buttons

Implementirajte CustomToolbarButton protokol da biste dodali dugmad u traku za unos komentara:

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // Ime SF simbola
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // Opcioni broj na bedžu

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

    // Opcione override metode (podrazumevano: 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 (važi za sve instance):

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

Feed Toolbar Buttons

Implementirajte FeedCustomToolbarButton za formu za kreiranje 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 objave:

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

Ili ih postavite globalno na feed SDK:

sdk.globalFeedToolbarButtons = [HashtagButton()]

Akcije dostupne svim korisnicima

• Prijavi/Ukloni prijavu -- prijavi komentar na pregled

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

• Blokiraj/Odblokiraj -- sakrij sve komentare korisnika (za pojedinačnog gledatelja)

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

Samo za administratore

• Zakači/Otkači -- zakači komentar na vrh niti

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

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

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

Sve moderacijske radnje su takođe dostupne kroz kontekstni meni komentara u UI. Administratorske radnje se pojavljuju samo kada je trenutni korisnik administrator sajta (podešeno putem SSO isAdmin flag ili konfiguracije 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.

Page Size

// Komentari: podrazumevano 30
sdk.pageSize = 50

// Feed: podrazumevano 10
feedSDK.pageSize = 20

Loading More Comments

UI automatski prikazuje kontrole paginacije. Takođe možete programatski pokrenuti paginaciju:

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

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

// Proveri stanje
sdk.hasMore            // Da li postoje još stranica
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Child Comment Pagination

Ugnježdeni odgovori se učitavaju na zahtev. Kada korisnik proširi nit, učitava se prvih 5 podkomentara. Pojavi se kontrola "učitaj još odgovora" ako ima više. Ovo se automatski obavlja u UI-ju.

Oba FastCommentsSDK i FastCommentsFeedSDK su klase ObservableObject sa @Published svojstvima. Možete ih posmatrati u svojim SwiftUI prikazima radi reaktivnih ažuriranja korisničkog interfejsa (UI).

FastCommentsSDK Published Properties

FastCommentsFeedSDK Published Properties

Comment Tree

Stablo komentara je dostupno preko sdk.commentsTree:

// Ravan spisak vidljivih čvorova za prikaz
sdk.commentsTree.visibleNodes

// Pronađi komentar po ID-u
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)