Dodajte komentarje v vašo iOS aplikacijo

Dajte vašemu programskemu agentu kontekst FastComments, ki ga potrebuje – gradnike, konfiguracijo, varno SSO, REST API in SDK-je:

npx skills add fastcomments/skills

Deluje s Claude Code, Codex, Cursor, Copilot, Gemini in vsakim drugim agentom, ki ga podpira skills CLI.

• 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

Add FastCommentsUI v svoj projekt z uporabo Swift Package Managerja.

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

Ali ga dodajte v svoj Package.swift:

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

Nato dodajte izdelek v svoj cilj:

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

Uvozite oba modula, kjer je potrebno:

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 overjanja:

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

Preprost SSO

Uporaben za predstavitve in lokalno testiranje. S preprostim SSO si lahko kdorkoli izda za katerega koli 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 podpira tudi neobvezna polja:

• id -- ID uporabnika (privzeto e-pošta, če ni nastavljen)
• displayName -- ločeno prikazano ime
• displayLabel -- oznaka po meri, prikazana poleg imena (npr. "VIP")
• websiteUrl -- povezava na imenu uporabnika
• locale -- koda jezikovne okolice
• isProfileActivityPrivate -- skrij aktivnost profila (privzeto true)

Varen SSO

V produkciji vaš zaledni sistem ustvari podpisan SSO žeton z vašo API skrivnostjo. iOS aplikacija pridobi ta žeton z vašega strežnika in ga posreduje v konfiguracijo.

Na vašem zalednem sistemu (z uporabo FastComments Swift SDK ali katerega koli jezika):

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()
// Vrnite ta žeton svoji iOS aplikaciji prek vašega API-ja

V vaši 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 {
            // Pridobite žeton z vašega zalednega sistema
            let token = try? await fetchSSOTokenFromYourBackend()
            // Ustvarite novo konfiguracijo z žetonom ali ga nastavite pred nalaganjem
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData podpira dodatna polja:

• optedInNotifications -- prijava na e-poštna obvestila
• displayLabel -- oznaka po meri
• displayName -- prikazano ime
• websiteUrl -- URL spletnega mesta
• groupIds -- članstva v skupinah
• isAdmin -- skrbniške pravice
• isModerator -- moderatorske pravice
• isProfileActivityPrivate -- zasebnost profila

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
                // Predstavi delitveni list
            }
            .onUserClick { context, userInfo, source in
                // Odpri profil uporabnika
            }
            .onMediaClick { mediaItem, index in
                // Prikaži slikovni pregledovalnik na celotnem zaslonu
            }
            .task {
                try? await sdk.loadIfNeeded()
            }
    }
}

Pogled feeda samodejno vključuje potegni-za-osvežitev in neskončno pomikanje. Uporabite loadIfNeeded() ob ponovnem vstopu v življenjski cikel zaslona, da obstoječ ali obnovljen feed ne bo ponastavljen nazaj na stran 1.

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)

Odprtje komentarjev pri objavi

Uporabite CommentsSheet za prikaz komentarjev pri feed objavi. Notranje ustvari primerek FastCommentsSDK z uporabo konfiguracije feed SDK:

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

Opomba: FeedPost se mora ujemati z Identifiable za .sheet(item:). Dodajte to razširitev:

extension FeedPost: @retroactive Identifiable {}

Filtriranje feeda po oznakah

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

Za nefiltriran globalni feed vrnite nil.

Shranjevanje in obnavljanje stanja feeda

Ohranjajte stanje paginacije med dogodki življenjskega cikla pogleda:

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

Če vaš zaslon začasno izgine, pogled feeda samodejno začasno ustavi posodobitve v živo in jih nadaljuje ob ponovnem prikazu brez brisanja naloženih objav. Pokličite sdk.cleanup() le, ko ste res končali s primestkom SDK.

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

Dejanje, ki je na voljo vsem uporabnikom

• Flag/Unflag – prijavi komentar v pregled

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

• Block/Unblock – skrij vse komentarje določenega uporabnika (za posameznega gledalca)

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

Dejanja, ki so na voljo samo skrbnikom

• Pin/Unpin – pripni komentar na vrh niza

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

• Lock/Unlock – prepreči nove odgovore na komentar in blokiraj urejanja ter brisanja, dokler ni odklenjeno (velja za vse, tudi za moderatorje)

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

Vsa moderacijska dejanja so prav tako na voljo preko kontekstnega menija komentarjev v uporabniškem vmesniku. Dejanja skrbnika se prikažejo le, ko je trenutni uporabnik spletiščni skrbnik (nastavljeno prek SSO isAdmin zastavice ali konfiguracije v nadzorni plošči).

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).

SDK metode vržejo FastCommentsError, ki sledi LocalizedError:

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

Lastnosti FastCommentsError:

• code -- koda napake iz API-ja
• reason -- opis napake v angleščini
• translatedError -- lokalizirano sporočilo o napaki, ki ga zagotovi strežnik

Napake pri blokiranju se prikažejo tudi samodejno prek sdk.blockingErrorMessage, ki jih vgrajeni pogledi prikažejo uporabniku.

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)