Add Comments to Your iOS App

• Gnezdena drevesa komentarjev z odgovori in paginacijo
• Družbeni tok s ustvarjanjem objav, reakcijami in medijskimi prilogami
• Način klepeta v živo z avtomatskim pomikanjem in ločili datumov
• Posodobitve v realnem času prek WebSocket (novi komentarji, glasovi, prisotnost)
• Enkratna prijava (preprosti SSO za testiranje, varen SSO za produkcijo)
• Urejanje obogatenega besedila z odebeljenim, poševnim, kodo in @omenami
• Glasovanje z nastavljivimi slogi (puščice gor/dol ali srca)
• Moderacijska dejanja: označi, pripni, zakleni, blokiraj
• Celovito oblikovanje tem s prednastavitvami in popolno prilagoditvijo
• Prilagojeni gumbi orodne vrstice za komentarje in ustvarjanje objav v toku
• Nalaganje slik
• Podpora za regijo EU
• Prisotnost uporabnikov (indikatorji na spletu/izven spleta)
• Filtriranje toka na podlagi oznak
• Podpora za lokalizacijo

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

Dodajte FastCommentsUI v vaš projekt z uporabo Swift Package Managerja.

V Xcode: File > Add Package Dependencies, nato vnesite URL repozitorija.

Ali ga dodajte v vaš Package.swift:

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

Nato dodajte produkt v vaš target:

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

Uvozite oba modula, kjer ju potrebujete:

import FastCommentsUI
import FastCommentsSwift

Najmanjša nastavitev za prikaz pripomočka za komentarje:

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

Zamenjajte "demo" z vašim FastComments tenant ID. urlId identificira stran ali nit, kjer so komentarji shranjeni.

FastComments podpira tri načine preverjanja pristnosti:

1. Anonimno -- brez SSO žetona; uporabniki dobijo identitete, vezane na sejo
2. Preprosti SSO -- odjemalski žeton za predstavitve in testiranje (ni varen)
3. Varen SSO -- strežniško podpisan žeton za produkcijo

Preprosti SSO

Uporabno za predstavitve in lokalno testiranje. Z Preprostim SSO lahko kdorkoli prevzame identiteto kateregakoli uporabnika, zato ga ne uporabljajte v 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 also supports optional fields:

• id -- user ID (defaults to email if not set)
• displayName -- separate display name
• displayLabel -- custom label shown next to the name (e.g. "VIP")
• websiteUrl -- link on the user's name
• locale -- locale code
• isProfileActivityPrivate -- hide profile activity (defaults to true)

Varen SSO

V v produkciji vaš backend ustvari podpisan SSO žeton z uporabo vašega API tajnega ključa. iOS aplikacija pridobi ta žeton z vašega strežnika in ga posreduje konfiguraciji.

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 {
            // Fetch the token from your backend
            let token = try? await fetchSSOTokenFromYourBackend()
            // Create a new config with the token, or set it before load
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData supports additional fields:

• optedInNotifications -- email notification opt-in
• displayLabel -- custom label
• displayName -- display name
• websiteUrl -- website URL
• groupIds -- group memberships
• isAdmin -- admin privileges
• isModerator -- moderator privileges
• isProfileActivityPrivate -- profile privacy

Osnovna uporaba

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

Slogi glasovanja

Privzeti slog glasovanja prikazuje puščici gor/dol. Uporabite ._1 za slog glasovanja s srcem:

FastCommentsView(sdk: sdk, voteStyle: ._1)

Povratni klici dogodkov

Uporabite povratne klice v obliki modifierjev za obravnavo interakcij uporabnika:

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

Uporaba teme

Posredujte temo prek SwiftUI okolja:

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

Ali jo nastavite neposredno na SDK:

sdk.theme = FastCommentsTheme.modern

Smer sortiranja

sdk.defaultSortDirection = .nf  // Najnovejše najprej (privzeto)
sdk.defaultSortDirection = .of  // Najstarejše najprej
sdk.defaultSortDirection = .mr  // Najbolj relevantno

LiveChatView nudi izkušnjo klepeta v realnem času z avtomatskim pomikanjem, ločilci datumov in kompaktno postavitvijo. Samodejno konfigurira SDK za razvrščanje od najstarejših naprej in takojšnji prikaz v živo.

struct ChatView: View {
    @StateObject private var sdk: FastCommentsSDK = {
        let config = FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "chat-room-1",
            sso: ssoToken  // Priporočamo SSO, da imajo uporabniki 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 podpira naslednje povratne klice:

• .onCommentPosted -- sproži se, ko uporabnik pošlje sporočilo
• .onCommentDeleted -- sproži se, ko je sporočilo izbrisano
• .onUserClick -- sproži se, ko je kliknjen uporabnikovo ime ali avatar

Sistem feeda je ločen SDK (FastCommentsFeedSDK) s svojim pogledom.

Nalaganje in 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 delilni list
            }
            .onUserClick { context, userInfo, source in
                // Pojdi na profil uporabnika
            }
            .onMediaClick { mediaItem, index in
                // Prikaži pregledovalnik slike na celotnem zaslonu
            }
            .task {
                try? await sdk.load()
            }
    }
}

Pogled feeda samodejno podpira vlečenje za osvežitev in neskončno pomikanje.

Ustvarjanje objav

Uporabite FeedPostCreateView za prikaz obrazca za ustvarjanje objave:

@State private var showCreatePost = false

// V telesu vašega pogleda:
.sheet(isPresented: $showCreatePost) {
    FeedPostCreateView(
        sdk: sdk,
        onPostCreated: { post in
            showCreatePost = false
            Task { try? await sdk.refresh() }
        },
        onCancelled: {
            showCreatePost = false
        }
    )
}

Reakcije na objave

SDK obravnava reakcije z optimističnimi posodobitvami:

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

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

Odpiranje komentarjev na objavi

Uporabite CommentsSheet za prikaz komentarjev pri feed objavi. Znotraj ustvari primer FastCommentsSDK z uporabo konfiguracije feed SDK-ja:

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

Opomba: FeedPost mora ustrezati protokolu Identifiable za .sheet(item:). Dodajte to razširitev:

extension FeedPost: @retroactive Identifiable {}

Filtriranje feeda na podlagi oznak

Implementirajte protokol TagSupplier za filtriranje feed objav po oznakah:

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

sdk.tagSupplier = TeamTagSupplier()

Vrnite nil za nefiltriran globalni feed.

Shranjevanje in obnavljanje stanja feeda

Ohranite stanje paginacije med dogodki življenjskega cikla pogleda:

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

Brisanje objav

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

Prednastavitve teme

Na voljo so štiri vgrajene prednastavitve:

// Sistemske privzete
sdk.theme = FastCommentsTheme.default

// Karte z zasenčenjem in velikimi zaobljenimi vogali
sdk.theme = FastCommentsTheme.modern

// Ravno, brez senc, majhen radij vogalov, brez črt niti
sdk.theme = FastCommentsTheme.minimal

// Nastavi vse barve dejanj na eno barvo znamke
sdk.theme = FastCommentsTheme.allPrimary(.indigo)

Slogi prikaza komentarjev

var theme = FastCommentsTheme()
theme.commentStyle = .flat    // Ravni seznam z ločili (privzeto)
theme.commentStyle = .card    // Zaobljene kartice s sencami
theme.commentStyle = .bubble  // Slog pogovorne oblačke

Barve

Vse lastnosti barv so neobvezne. Nenastavljene vrednosti se vrnejo na smiselne sistemske privzete vrednosti.

var theme = FastCommentsTheme()

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

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

// Gumbi za dejanja
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)

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

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

// Vnosna vrstica
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)

Postavitev in razmiki

theme.cornerRadius = .large       // .none, .small, .medium, .large
theme.commentSpacing = 4          // Točke med vrsticami komentarjev
theme.nestingIndent = 20          // Točke zamika za vsako raven zagnieždenja
theme.avatarSize = 36             // Premer avatarja za korenske komentarje
theme.replyAvatarSize = 28        // Premer avatarja za gnezdene odgovore

Vizualni učinki

theme.showShadows = true          // Nežne sence na karticah
theme.showThreadLine = true       // Navpična črta, ki povezuje gnezdene odgovore
theme.animateVotes = true         // Vzmetna animacija ob spremembah glasov

Uporaba tem

Dva pristopa:

// Preko SwiftUI okolja (priporočeno za hierarhijo pogledov)
FastCommentsView(sdk: sdk)
    .fastCommentsTheme(theme)

// Neposredno na SDK
sdk.theme = theme

Gumbi orodne vrstice za komentarje

Implementirajte protokol CustomToolbarButton, da dodate gumbe v orodno vrstico za vnos komentarja:

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // Ime SF simbola
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // Neobvezen števec značke

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

    // Neobvezne preglasitve (privzeto true)
    func isEnabled() -> Bool { true }
    func isVisible() -> Bool { true }
}

Posredujte prilagojene gumbe pri ustvarjanju pogleda:

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

Ali jih dodajte globalno v SDK (velja za vse primere):

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

Gumbi orodne vrstice vira

Implementirajte FeedCustomToolbarButton za obrazec za ustvarjanje objave:

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

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

Posredujte jih v pogled za ustvarjanje objave:

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

Ali jih nastavite globalno v SDK vira:

sdk.globalFeedToolbarButtons = [HashtagButton()]

Dejanja na voljo vsem uporabnikom

• Prijavi/Prekliči prijavo -- prijavi komentar v pregled

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

• Blokiraj/Odblokiraj -- skrij vse komentarje od uporabnika (za posameznega gledalca)

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

Dejanja samo za skrbnike

• Pripni/Odpripni -- pripni komentar na vrh niti

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

• Zakleni/Odkleni -- prepreči nove odgovore na komentarju

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

Vsa moderacijska dejanja so na voljo tudi prek kontekstnega menija komentarja v uporabniškem vmesniku (UI). Dejavnosti skrbnika se prikažejo samo, ko je trenutni uporabnik skrbnik strani (nastavljeno prek SSO zastavice isAdmin ali konfiguracije nadzorne plošče).

Po klicu sdk.load(), se SDK samodejno prijavi na WebSocket dogodke za konfiguriran urlId. Obdelani so naslednji dogodki:

• Novi komentarji, urejanja in izbris
• Glasovi (novi in odstranjeni)
• Spremembe stanja pripenjanja, zaklepanja, prijave in blokiranja
• Prisotnost uporabnikov (prihod/odhod)
• Odpiranje/zapiranje niti
• Podelitve značk
• Posodobitve konfiguracije strežnika

Nadzor prikaza v živo

Privzeto se novi komentarji drugih uporabnikov prikažejo takoj:

sdk.showLiveRightAway = true   // Privzeto: prikaži takoj

Nastavite to na false, da se novi komentarji zadržijo za gumbom "N novih komentarjev", kar uporabniku omogoča, da izbere, kdaj jih razkrije:

sdk.showLiveRightAway = false

Prisotnost uporabnikov

Indikatorji "na spletu"/"brez povezave" se samodejno prikažejo na avatarjih uporabnikov, ko strežnik omogoči sledenje prisotnosti. Na odjemalcu ni potrebna dodatna konfiguracija.

Velikost strani

// Komentarji: privzeto 30
sdk.pageSize = 50

// Feed: privzeto 10
feedSDK.pageSize = 20

Nalaganje več komentarjev

UI samodejno prikaže krmilnike za paginacijo. Paginacijo lahko sprožite tudi programatično:

// Naloži naslednjo stran
try await sdk.loadMore()

// Naloži vse preostale (onemogočeno, če >2000 komentarjev zaradi zmogljivosti)
try await sdk.loadAll()

// Preveri stanje
sdk.hasMore            // Ali obstajajo še strani
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Paginacija podrejenih komentarjev

Gnezdeni odgovori se nalagajo po potrebi. Ko uporabnik razširi nit, se naloži prvih 5 podrejenih odgovorov. Če obstajajo dodatni odgovori, se prikaže kontrola "load more replies". To upravlja uporabniški vmesnik samodejno.

Tako FastCommentsSDK kot FastCommentsFeedSDK sta razreda ObservableObject z lastnostmi @Published. V svojih SwiftUI pogledih jih lahko opazujete za reaktivne posodobitve uporabniškega vmesnika.

Objavljene lastnosti FastCommentsSDK

Objavljene lastnosti FastCommentsFeedSDK

Drevo komentarjev

Drevo komentarjev je dostopno preko sdk.commentsTree:

// Seznam vidnih vozlišč za prikaz
sdk.commentsTree.visibleNodes

// Poiščite komentar po ID-ju
sdk.commentsTree.commentsById["comment-id"]

Za uporabo podatkovnega centra v EU nastavite polje region v svoji konfiguraciji:

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

S tem se vse API zahteve in WebSocket povezave preusmerijo na eu.fastcomments.com.

Ko končate z instanco SDK (npr. ko se pogled zapira), pokličite cleanup(), da zaprete WebSocket povezavo in prekličete ozadna opravila:

sdk.cleanup()

Za poglede, ki jih upravlja @StateObject v SwiftUI, se to običajno kliče v .onDisappear ali ko se pogled dealocira.

Komentarji

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

Vrne niz URL-ja naložene slike.

Objave vira

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

// Naloži več slik hkrati
let mediaItems = try await feedSDK.uploadImages(images: [
    (jpegData1, "photo1.jpg"),
    (jpegData2, "photo2.jpg")
])

Iskanje uporabnikov za podporo samodokončanju omemb (@mention):

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

Vgrajeni CommentInputBar samodejno obravnava samodokončanje omemb (@mention).

Uredi

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

Strežnik ponovno upodobi HTML. Lokalni komentar se samodejno posodobi.

Izbriši

try await sdk.deleteComment(commentId: commentId)

Brisanje komentarja prav tako odstrani njegove potomce iz lokalnega drevesa.

Obe dejanji sta na voljo prek kontekstnega menija komentarja v vmesniku, kadar je trenutni uporabnik avtor komentarja (ali skrbnik strani).

Metode SDK vržejo FastCommentsError, ki je skladna z LocalizedError:

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

FastCommentsError lastnosti:

• code -- koda napake iz API-ja
• reason -- angleški opis napake
• translatedError -- strežniško posredovano lokalizirano sporočilo o napaki

Blocking errors are also surfaced automatically via sdk.blockingErrorMessage, which the built-in views display to the user.

Pošljite kodo lokalizacije v konfiguraciji, da lokalizirate nize, ki jih zagotavlja strežnik:

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

Nizi uporabniškega vmesnika na odjemalski strani uporabljajo lokalizacijo, ki temelji na iOS bundle-ih.

Skladišče vsebuje celoten primer aplikacije v ExampleApp/ z demonstracijami:

• Razvejani komentarji z SSO in prilagojenimi temami
• Družbeni vir z ustvarjanjem objav in filtriranjem po oznakah
• Klepet v živo
• Enostavni in varni SSO poteki
• Prilagojeni gumbi na orodni vrstici (komentarji in vir)