Add Comments to Your iOS App

• Geneste reactiestructuren met geneste antwoorden en paginering
• Sociale feed met berichtcreatie, reacties en mediabijlagen
• Live chat-modus met automatisch scrollen en datumscheiders
• Realtime-updates via WebSocket (nieuwe reacties, stemmen, aanwezigheid)
• Single Sign-On (Eenvoudige SSO voor testen, Veilige SSO voor productie)
• Rijke tekstbewerking met vet, cursief, code en @mentions
• Stemmen met configureerbare stijlen (pijlen omhoog/omlaag of harten)
• Moderatieacties: markeren, vastzetten, vergrendelen, blokkeren
• Uitgebreide theming met presets en volledige aanpassing
• Aangepaste knoppen in de werkbalk voor reacties en het aanmaken van feedberichten
• Afbeeldingsuploads
• Ondersteuning voor de EU-regio
• Gebruikersaanwezigheid (online/offline-indicatoren)
• Tag-gebaseerde feedfiltering
• Ondersteuning voor lokalisatie

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

Voeg FastCommentsUI toe aan je project met Swift Package Manager.

In Xcode: Bestand > Voeg pakketafhankelijkheden toe, voer vervolgens de repository-URL in.

Of voeg het toe aan je Package.swift:

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

Voeg vervolgens het product toe aan je target:

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

Importeer beide modules waar nodig:

import FastCommentsUI
import FastCommentsSwift

De minimale setup om een reactie-widget weer te geven:

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

Vervang "demo" door je FastComments tenant-ID. De urlId identificeert de pagina of discussiedraad waar de reacties worden opgeslagen.

FastComments ondersteunt drie authenticatiemodi:

1. Anonymous -- geen SSO-token; gebruikers krijgen op sessies gebaseerde identiteiten
2. Simple SSO -- token aan de clientzijde voor demo's en testen (niet veilig)
3. Secure SSO -- door de server ondertekend token voor productie

Simple SSO

Handig voor demo's en lokaal testen. Iedereen kan met Simple SSO zich voordoen als elke gebruiker, dus gebruik het niet in productie.

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 ondersteunt ook optionele velden:

• id -- gebruikers-ID (standaard het e-mailadres als dit niet is ingesteld)
• displayName -- aparte weergavenaam
• displayLabel -- aangepast label dat naast de naam wordt weergegeven (bijv. "VIP")
• websiteUrl -- link op de gebruikersnaam
• locale -- locale-code
• isProfileActivityPrivate -- verberg profielactiviteit (standaard: true)

Secure SSO

In productie genereert je backend een door de server ondertekend SSO-token met je API-secret. De iOS-app haalt dit token van je server en geeft het door aan de configuratie.

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 je 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 ondersteunt extra velden:

• optedInNotifications -- opt-in voor e-mailmeldingen
• displayLabel -- aangepast label
• displayName -- weergavenaam
• websiteUrl -- website-URL
• groupIds -- groepslidmaatschappen
• isAdmin -- adminrechten
• isModerator -- moderatorrechten
• isProfileActivityPrivate -- profielprivacy

Basisgebruik

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

Stemstijlen

De standaard stemstijl toont pijlen omhoog/omlaag. Geef ._1 op voor hart-stijl stemmen:

FastCommentsView(sdk: sdk, voteStyle: ._1)

Evenement-callbacks

Gebruik modifier-stijl callbacks om gebruikersinteracties af te handelen:

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
        // bron is .name of .avatar
        print("Tapped \(userInfo.displayName)")
    }

Een thema toepassen

Geef een thema door via de SwiftUI-omgeving:

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

Of stel het rechtstreeks in op de SDK:

sdk.theme = FastCommentsTheme.modern

Sorteerrichting

sdk.defaultSortDirection = .nf  // Nieuwste eerst (standaard)
sdk.defaultSortDirection = .of  // Oudste eerst
sdk.defaultSortDirection = .mr  // Meest relevant

LiveChatView biedt een realtime chatervaring met automatisch scrollen, datum-scheidingen en een compacte lay-out. Het configureert de SDK automatisch voor oudste-eerst sortering en directe live-weergave.

struct ChatView: View {
    @StateObject private var sdk: FastCommentsSDK = {
        let config = FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "chat-room-1",
            sso: ssoToken  // SSO aanbevolen zodat gebruikers namen hebben
        )
        return FastCommentsSDK(config: config)
    }()

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

LiveChatView ondersteunt deze callbacks:

• .onCommentPosted -- wordt aangeroepen wanneer de gebruiker een bericht verstuurt
• .onCommentDeleted -- wordt aangeroepen wanneer een bericht wordt verwijderd
• .onUserClick -- wordt aangeroepen wanneer op de naam of avatar van een gebruiker wordt getikt

Het feed-systeem is een aparte SDK (FastCommentsFeedSDK) met zijn eigen weergave.

Laden en weergeven van de feed

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
                // Toon deelvenster
            }
            .onUserClick { context, userInfo, source in
                // Navigeer naar gebruikersprofiel
            }
            .onMediaClick { mediaItem, index in
                // Toon afbeeldingsviewer op volledig scherm
            }
            .task {
                try? await sdk.load()
            }
    }
}

De feed-weergave bevat automatisch pull-to-refresh en infinite scroll.

Berichten maken

Gebruik FeedPostCreateView om een formulier voor het aanmaken van een bericht weer te geven:

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

Reageren op berichten

De SDK verwerkt reacties met optimistische updates:

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)

Reacties openen bij een bericht

Gebruik CommentsSheet om reacties voor een feed-bericht weer te geven. Het maakt intern een FastCommentsSDK-instantie aan met de configuratie van de feed SDK:

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

Opmerking: FeedPost moet voldoen aan Identifiable voor .sheet(item:). Voeg deze extensie toe:

extension FeedPost: @retroactive Identifiable {}

Filteren van de feed op basis van tags

Implementeer het TagSupplier-protocol om feed-berichten op tags te filteren:

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

sdk.tagSupplier = TeamTagSupplier()

Geef nil terug voor een niet-gefilterde globale feed.

Feedstatus opslaan en herstellen

Behoud de pagineringstoestand tijdens levenscyclusgebeurtenissen van de view:

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

Berichten verwijderen

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

Thema-voorinstellingen

Er zijn vier ingebouwde voorinstellingen beschikbaar:

// Standaardinstellingen van het systeem
sdk.theme = FastCommentsTheme.default

// Kaarten met schaduwen en grote, afgeronde hoeken
sdk.theme = FastCommentsTheme.modern

// Vlak, geen schaduwen, kleine hoekradius, geen verticale lijn tussen geneste reacties
sdk.theme = FastCommentsTheme.minimal

// Stel alle actiekleuren in op één merkkleur
sdk.theme = FastCommentsTheme.allPrimary(.indigo)

Weergavestijlen voor reacties

var theme = FastCommentsTheme()
theme.commentStyle = .flat    // Vlakke lijst met scheidingslijnen (standaard)
theme.commentStyle = .card    // Afgeronde kaarten met schaduwen
theme.commentStyle = .bubble  // Chat-bubbelstijl

Kleuren

Alle kleur-eigenschappen zijn optioneel. Niet ingestelde waarden vallen terug op zinvolle systeemstandaarden.

var theme = FastCommentsTheme()

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

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

// Actieknoppen
theme.actionButtonColor = .indigo
theme.replyButtonColor = .indigo
theme.toggleRepliesButtonColor = .indigo.opacity(0.8)
theme.loadMoreButtonTextColor = .indigo

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

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

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

// Invoerbalk
theme.inputBarBackgroundColor = Color(.systemBackground)
theme.inputBarBorderColor = Color(.separator)

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

Typografie

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

Lay-out en ruimte

theme.cornerRadius = .large       // Opties: .none, .small, .medium, .large
theme.commentSpacing = 4          // Punten tussen reactierijen
theme.nestingIndent = 20          // Punten inspringing per genest niveau
theme.avatarSize = 36             // Diameter avatar voor hoofdreacties
theme.replyAvatarSize = 28        // Diameter avatar voor geneste reacties

Visuele effecten

theme.showShadows = true          // Subtiele schaduwen op kaarten
theme.showThreadLine = true       // Verticale lijn die geneste reacties verbindt
theme.animateVotes = true         // Veeranimatie bij stemwijzigingen

Thema's toepassen

Twee benaderingen:

// Via SwiftUI-omgeving (aanbevolen voor de weergave-hiërarchie)
FastCommentsView(sdk: sdk)
    .fastCommentsTheme(theme)

// Direct op de SDK
sdk.theme = theme

Werkbalkknoppen voor opmerkingen

Implementeer het CustomToolbarButton-protocol om knoppen toe te voegen aan de invoerwerkbalk voor opmerkingen:

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // SF-symboolnaam
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // Optioneel badge-aantal

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

    // Optionele overschrijvingen (standaard true)
    func isEnabled() -> Bool { true }
    func isVisible() -> Bool { true }
}

Geef aangepaste knoppen door bij het aanmaken van de view:

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

Of voeg ze globaal toe aan de SDK (geldt voor alle instanties):

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

Werkbalkknoppen voor de feed

Implementeer FeedCustomToolbarButton voor het formulier om een bericht te maken:

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

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

Geef ze door aan de aanmaakweergave:

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

Of stel ze globaal in op de feed SDK:

sdk.globalFeedToolbarButtons = [HashtagButton()]

Acties beschikbaar voor alle gebruikers

• Melden/Ontmelden -- rapporteer een reactie ter beoordeling

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

• Blokkeren/Deblokkeren -- verberg alle reacties van een gebruiker (per kijker)

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

Alleen voor beheerders

• Vastpinnen/Lospinnen -- zet een reactie vast bovenaan de draad

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

• Vergrendelen/Ontgrendelen -- voorkom nieuwe antwoorden op een reactie

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

Alle moderatieacties zijn ook beschikbaar via het contextmenu van de reactie in de UI. Beheerderacties verschijnen alleen wanneer de huidige gebruiker een sitebeheerder is (ingesteld via de SSO isAdmin vlag of de dashboardconfiguratie).

Na het aanroepen van sdk.load(), abonneert de SDK zich automatisch op WebSocket-gebeurtenissen voor de geconfigureerde urlId. De volgende gebeurtenissen worden afgehandeld:

• Nieuwe reacties, bewerkingen en verwijderingen
• Stemmen (nieuw en verwijderd)
• Wijzigingen in vastzetten, vergrendelen, markeren en blokkeren
• Gebruikersaanwezigheid (aankomst/vertrek)
• Discussiedraad openen/sluiten
• Toekenningen van badges
• Updates van serverconfiguratie

Liveweergave regelen

Standaard verschijnen nieuwe reacties van andere gebruikers direct:

sdk.showLiveRightAway = true   // Standaard: direct tonen

Stel dit in op false om nieuwe reacties achter een knop 'N nieuwe reacties' te bufferen, zodat de gebruiker kan kiezen wanneer ze worden weergegeven:

sdk.showLiveRightAway = false

Gebruikersaanwezigheid

Online-/offline-indicatoren verschijnen automatisch op gebruikersavatars wanneer de server aanwezigheidstracking inschakelt. Geen extra configuratie is nodig aan de clientzijde.

Paginagrootte

// Opmerkingen: standaard 30
sdk.pageSize = 50

// Feed: standaard 10
feedSDK.pageSize = 20

Meer opmerkingen laden

De UI toont pagineringsbedieningselementen automatisch. U kunt paginering ook programmatisch activeren:

// Volgende pagina laden
try await sdk.loadMore()

// Alle resterende laden (uitgeschakeld als >2000 opmerkingen omwille van prestaties)
try await sdk.loadAll()

// Controleer status
sdk.hasMore            // Of er meer pagina's bestaan
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Paginering van kindreacties

Geneste reacties worden lui geladen. Wanneer een gebruiker een thread uitklapt, worden de eerste 5 onderliggende reacties geladen. Er verschijnt een bediening "laad meer reacties" als er meer zijn. Dit wordt automatisch door de UI afgehandeld.

Beide FastCommentsSDK en FastCommentsFeedSDK zijn ObservableObject-klassen met @Published-eigenschappen. Je kunt deze observeren in je SwiftUI-weergaven voor reactieve UI-updates.

Gepubliceerde eigenschappen van FastCommentsSDK

Gepubliceerde eigenschappen van FastCommentsFeedSDK

Reactieboom

De reactieboom is toegankelijk via sdk.commentsTree:

// Platte lijst van zichtbare knooppunten voor weergave
sdk.commentsTree.visibleNodes

// Zoek een reactie op aan de hand van ID
sdk.commentsTree.commentsById["comment-id"]

Om het EU-datacenter te gebruiken, stel het region-veld in uw config in:

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

Dit leidt alle API-verzoeken en WebSocket-verbindingen naar eu.fastcomments.com.

Wanneer u klaar bent met een SDK-instantie (bijv. wanneer de view wordt gesloten), roept u cleanup() aan om de WebSocket-verbinding te sluiten en achtergrondtaken te annuleren:

sdk.cleanup()

Voor views die worden beheerd door SwiftUI's @StateObject wordt dit meestal aangeroepen in .onDisappear of wanneer de view wordt gedealloceerd.

Reacties

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

Geeft de URL-string van de geüploade afbeelding terug.

Feed-berichten

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

// Upload meerdere afbeeldingen gelijktijdig
let mediaItems = try await feedSDK.uploadImages(images: [
    (jpegData1, "photo1.jpg"),
    (jpegData2, "photo2.jpg")
])

Zoek naar gebruikers ter ondersteuning van @mention-autocompletie:

let results = try await sdk.searchUsers(query: "jan")
// Geeft [UserSearchResult] terug met userId, username, avatar, enz.

De ingebouwde CommentInputBar verzorgt automatisch de @mention-autocompletie.

Bewerken

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

De server rendeert de HTML opnieuw. De lokale opmerking wordt automatisch bijgewerkt.

Verwijderen

try await sdk.deleteComment(commentId: commentId)

Het verwijderen van een opmerking verwijdert ook de onderliggende reacties uit de lokale boom.

Beide acties zijn beschikbaar via het contextmenu van de opmerking in de UI wanneer de huidige gebruiker de auteur van de opmerking is (of een sitebeheerder).

SDK-methoden gooien FastCommentsError, die voldoet aan LocalizedError:

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

Eigenschappen van FastCommentsError:

• code -- foutcode van de API
• reason -- Engelse foutbeschrijving
• translatedError -- door de server geleverde gelokaliseerde foutmelding

Blokkerende fouten worden ook automatisch zichtbaar gemaakt via sdk.blockingErrorMessage, die door de ingebouwde weergaven aan de gebruiker wordt weergegeven.

Geef in de config een locale-code op om door de server geleverde tekst te lokaliseren:

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

De client-side UI-teksten gebruiken iOS bundle-gebaseerde lokalisatie.

De repository bevat een volledige voorbeeld-app in ExampleApp/ met demonstraties van:

• Geneste reacties met SSO en aangepaste thema's
• Sociale feed met berichten aanmaken en filteren op tags
• Livechat
• Eenvoudige en veilige SSO-flows
• Aangepaste werkbalkknoppen (reacties en feed)