Add Comments to Your iOS App

• Arbres de commentaires en fil avec réponses imbriquées et pagination
• Fil social avec création de publications, réactions et pièces jointes média
• Mode chat en direct avec défilement automatique et séparateurs de date
• Mises à jour en temps réel via WebSocket (nouveaux commentaires, votes, présence)
• Authentification unique (SSO simple pour les tests, SSO sécurisé pour la production)
• Édition de texte enrichi avec gras, italique, code et mentions @
• Vote avec styles configurables (flèches haut/bas ou cœurs)
• Actions de modération : signaler, épingler, verrouiller, bloquer
• Thématisation complète avec préréglages et personnalisation totale
• Boutons de barre d'outils personnalisés pour les commentaires et la création de publications dans le fil
• Téléversements d'images
• Prise en charge de la région UE
• Présence des utilisateurs (indicateurs en ligne/hors ligne)
• Filtrage du fil par tags
• Prise en charge de la localisation

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

Ajoutez FastCommentsUI à votre projet en utilisant Swift Package Manager.

Dans Xcode : File > Add Package Dependencies, puis saisissez l'URL du dépôt.

Ou ajoutez-le à votre Package.swift:

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

Then add the product to your target:

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

Importez les deux modules là où nécessaire :

import FastCommentsUI
import FastCommentsSwift

La configuration minimale pour afficher un widget de commentaires :

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

Remplacez "demo" par l'ID de votre tenant FastComments. Le urlId identifie la page ou le fil de discussion où les commentaires sont stockés.

FastComments prend en charge trois modes d'authentification :

1. Anonymous -- pas de jeton SSO ; les utilisateurs obtiennent des identités basées sur la session
2. Simple SSO -- jeton côté client pour démos et tests (non sécurisé)
3. Secure SSO -- jeton signé côté serveur pour la production

Simple SSO

Utile pour des démonstrations et des tests locaux. N'importe qui peut usurper l'identité de n'importe quel utilisateur avec Simple SSO, ne l'utilisez donc pas en production.

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 prend également en charge les champs optionnels :

• id -- ID utilisateur (par défaut l'email si non défini)
• displayName -- nom d'affichage distinct
• displayLabel -- étiquette personnalisée affichée à côté du nom (par ex. "VIP")
• websiteUrl -- lien sur le nom de l'utilisateur
• locale -- code de locale
• isProfileActivityPrivate -- masquer l'activité du profil (true par défaut)

Secure SSO

En production, votre backend génère un jeton SSO signé en utilisant votre secret API. L'application iOS récupère ce jeton depuis votre serveur et le transmet à la configuration.

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 {
            // Récupérer le jeton depuis votre backend
            let token = try? await fetchSSOTokenFromYourBackend()
            // Créer une nouvelle configuration avec le jeton, ou le définir avant le chargement
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData prend en charge des champs supplémentaires :

• optedInNotifications -- inscription aux notifications par e-mail
• displayLabel -- étiquette personnalisée
• displayName -- nom d'affichage
• websiteUrl -- URL du site web
• groupIds -- appartenances à des groupes
• isAdmin -- privilèges d'administrateur
• isModerator -- privilèges de modérateur
• isProfileActivityPrivate -- confidentialité du profil

Utilisation de base

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

Styles de vote

Le style de vote par défaut affiche des flèches haut/bas. Passez ._1 pour des votes en forme de cœur :

FastCommentsView(sdk: sdk, voteStyle: ._1)

Callbacks d'événements

Utilisez des callbacks de type modificateur pour gérer les interactions utilisateur :

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

Appliquer un thème

Passez un thème via l'environnement SwiftUI :

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

Ou définissez-le directement sur le SDK :

sdk.theme = FastCommentsTheme.modern

Direction de tri

sdk.defaultSortDirection = .nf  // Le plus récent d'abord (par défaut)
sdk.defaultSortDirection = .of  // Le plus ancien d'abord
sdk.defaultSortDirection = .mr  // Le plus pertinent

LiveChatView fournit une expérience de chat en temps réel avec défilement automatique, séparateurs de date et une mise en page compacte. Il configure automatiquement le SDK pour un tri du plus ancien au plus récent et un affichage live immédiat.

struct ChatView: View {
    @StateObject private var sdk: FastCommentsSDK = {
        let config = FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "chat-room-1",
            sso: ssoToken  // SSO recommandé afin que les utilisateurs aient des noms
        )
        return FastCommentsSDK(config: config)
    }()

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

LiveChatView prend en charge ces callbacks :

• .onCommentPosted -- déclenché lorsque l'utilisateur envoie un message
• .onCommentDeleted -- déclenché lorsqu'un message est supprimé
• .onUserClick -- déclenché lorsque le nom ou l'avatar d'un utilisateur est touché

Le système de flux est un SDK séparé (FastCommentsFeedSDK) avec sa propre vue.

Chargement et affichage du flux

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
                // Présenter la feuille de partage
            }
            .onUserClick { context, userInfo, source in
                // Naviguer vers le profil utilisateur
            }
            .onMediaClick { mediaItem, index in
                // Présenter le visualiseur d'images en plein écran
            }
            .task {
                try? await sdk.load()
            }
    }
}

La vue du flux inclut automatiquement le pull-to-refresh et le défilement infini.

Création de publications

Utilisez FeedPostCreateView pour afficher un formulaire de création de publication :

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

Réagir aux publications

Le SDK gère les réactions avec des mises à jour optimistes :

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)

Ouvrir les commentaires d'une publication

Utilisez CommentsSheet pour afficher les commentaires d'une publication du flux. Il crée une instance FastCommentsSDK en interne en utilisant la configuration du SDK de flux :

.sheet(item: $commentsPost) { post in
    CommentsSheet(post: post, feedSDK: sdk, onUserClick: { context, userInfo, source in
        // Gérer le clic sur l'utilisateur
    })
}

Note : FeedPost doit conformer à Identifiable pour .sheet(item:). Ajoutez cette extension :

extension FeedPost: @retroactive Identifiable {}

Filtrage du flux par étiquette

Implémentez le protocole TagSupplier pour filtrer les publications du flux par étiquettes :

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

sdk.tagSupplier = TeamTagSupplier()

Retournez nil pour un flux global sans filtre.

Enregistrer et restaurer l'état du flux

Préservez l'état de la pagination lors des événements du cycle de vie de la vue :

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

Suppression de publications

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

Préréglages de thème

Quatre préréglages intégrés sont disponibles :

// Paramètres système par défaut
sdk.theme = FastCommentsTheme.default

// Cartes avec ombres et grands coins arrondis
sdk.theme = FastCommentsTheme.modern

// Plat, sans ombres, petit rayon de coins, pas de lignes de discussion
sdk.theme = FastCommentsTheme.minimal

// Définir toutes les couleurs d'action sur une seule couleur de marque
sdk.theme = FastCommentsTheme.allPrimary(.indigo)

Styles d'affichage des commentaires

var theme = FastCommentsTheme()
theme.commentStyle = .flat    // Liste plate avec séparateurs (par défaut)
theme.commentStyle = .card    // Cartes arrondies avec ombres
theme.commentStyle = .bubble  // Style bulle de chat

Couleurs

Toutes les propriétés de couleur sont optionnelles. Les valeurs non définies reviennent aux paramètres par défaut du système.

var theme = FastCommentsTheme()

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

// Arrière-plans
theme.commentBackgroundColor = Color(.secondarySystemGroupedBackground)
theme.containerBackgroundColor = Color(.systemGroupedBackground)

// Boutons d'action
theme.actionButtonColor = .indigo
theme.replyButtonColor = .indigo
theme.toggleRepliesButtonColor = .indigo.opacity(0.8)
theme.loadMoreButtonTextColor = .indigo

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

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

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

// Barre de saisie
theme.inputBarBackgroundColor = Color(.systemBackground)
theme.inputBarBorderColor = Color(.separator)

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

Typographie

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

Mise en page et espacement

theme.cornerRadius = .large       // .none, .small, .medium, .large
theme.commentSpacing = 4          // points entre les lignes de commentaires
theme.nestingIndent = 20          // points d'indentation par niveau d'imbrication
theme.avatarSize = 36             // diamètre de l'avatar pour les commentaires racines
theme.replyAvatarSize = 28        // diamètre de l'avatar pour les réponses imbriquées

Effets visuels

theme.showShadows = true          // Ombres subtiles sur les cartes
theme.showThreadLine = true       // Ligne verticale reliant les réponses imbriquées
theme.animateVotes = true         // Animation à ressort lors des changements de vote

Application des thèmes

Deux approches :

// Via l'environnement SwiftUI (recommandé pour la hiérarchie des vues)
FastCommentsView(sdk: sdk)
    .fastCommentsTheme(theme)

// Directement sur le SDK
sdk.theme = theme

Boutons de la barre d'outils des commentaires

Implémentez le protocole CustomToolbarButton pour ajouter des boutons à la barre d'outils de saisie des commentaires :

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // Nom du SF Symbol
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // Nombre de badge optionnel

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

    // Remplacements optionnels (par défaut true)
    func isEnabled() -> Bool { true }
    func isVisible() -> Bool { true }
}

Passez des boutons personnalisés lors de la création de la vue :

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

Ou ajoutez-les globalement sur le SDK (s'applique à toutes les instances) :

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

Boutons de la barre d'outils du fil d'actualité

Implémentez FeedCustomToolbarButton pour le formulaire de création de publication :

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

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

Passez-les à la vue de création :

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

Ou configurez-les globalement sur le SDK du fil :

sdk.globalFeedToolbarButtons = [HashtagButton()]

Actions disponibles pour tous les utilisateurs

• Signaler/Annuler le signalement -- signaler un commentaire pour examen

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

• Bloquer/Débloquer -- masquer tous les commentaires d'un utilisateur (par visiteur)

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

Actions réservées aux administrateurs

• Épingler/Désépingler -- épingler un commentaire en haut du fil

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

• Verrouiller/Déverrouiller -- empêcher de nouvelles réponses à un commentaire

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

Toutes les actions de modération sont également disponibles via le menu contextuel du commentaire dans l'interface utilisateur. Les actions d'administration n'apparaissent que lorsque l'utilisateur courant est administrateur du site (défini via le flag SSO isAdmin ou la configuration du tableau de bord).

Après l'appel de sdk.load(), le SDK s'abonne automatiquement aux événements WebSocket pour le urlId configuré. Les événements suivants sont gérés :

• Nouveaux commentaires, modifications et suppressions
• Votes (ajoutés et retirés)
• Modifications des états d'épinglage, de verrouillage, de signalement et de blocage
• Présence des utilisateurs (connexion/déconnexion)
• Ouverture/fermeture de fil de discussion
• Attribution de badges
• Mises à jour de la configuration du serveur

Contrôle de l'affichage en direct

Par défaut, les nouveaux commentaires des autres utilisateurs apparaissent immédiatement :

sdk.showLiveRightAway = true   // Par défaut : afficher immédiatement

Réglez ceci sur false pour mettre en tampon les nouveaux commentaires derrière un bouton "N nouveaux commentaires", permettant à l'utilisateur de choisir quand les afficher :

sdk.showLiveRightAway = false

Présence des utilisateurs

Des indicateurs en ligne/hors ligne apparaissent automatiquement sur les avatars des utilisateurs lorsque le serveur active le suivi de présence. Aucune configuration supplémentaire n'est nécessaire côté client.

Taille de page

// Commentaires : 30 par défaut
sdk.pageSize = 50

// Flux : 10 par défaut
feedSDK.pageSize = 20

Chargement de commentaires supplémentaires

L'interface affiche automatiquement les contrôles de pagination. Vous pouvez également déclencher la pagination par programmation :

// Charger la page suivante
try await sdk.loadMore()

// Charger tous les restants (désactivé si >2000 commentaires pour des raisons de performances)
try await sdk.loadAll()

// Vérifier l'état
sdk.hasMore            // S'il existe d'autres pages
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Pagination des réponses imbriquées

Les réponses imbriquées sont chargées à la demande. Lorsqu'un utilisateur développe un fil, les 5 premières réponses sont chargées. Un contrôle « charger plus de réponses » apparaît s'il y en a d'autres. Ceci est géré automatiquement par l'interface.

Les deux FastCommentsSDK et FastCommentsFeedSDK sont des classes ObservableObject disposant de propriétés @Published. Vous pouvez les observer dans vos vues SwiftUI pour mettre à jour l'interface utilisateur de manière réactive.

FastCommentsSDK Published Properties

FastCommentsFeedSDK Published Properties

Comment Tree

L'arbre des commentaires est accessible via sdk.commentsTree:

// Liste plate des nœuds visibles pour le rendu
sdk.commentsTree.visibleNodes

// Rechercher un commentaire par ID
sdk.commentsTree.commentsById["comment-id"]

Pour utiliser le centre de données de l'UE, définissez le champ region dans votre configuration :

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

Cela achemine toutes les requêtes API et les connexions WebSocket vers eu.fastcomments.com.

Quand vous avez terminé avec une instance du SDK (par exemple, lorsque la vue est en train d'être fermée), appelez cleanup() pour fermer la connexion WebSocket et annuler les tâches en arrière-plan :

sdk.cleanup()

Pour les vues gérées par @StateObject de SwiftUI, ceci est généralement appelé dans .onDisappear ou lorsque la vue est désallouée.

Commentaires

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

Renvoie la chaîne URL de l'image téléversée.

Publications du flux

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

// Téléverser plusieurs images en parallèle
let mediaItems = try await feedSDK.uploadImages(images: [
    (jpegData1, "photo1.jpg"),
    (jpegData2, "photo2.jpg")
])

Rechercher des utilisateurs pour prendre en charge l'autocomplétion des @mentions :

let results = try await sdk.searchUsers(query: "jan")
// Renvoie [UserSearchResult] avec userId, username, avatar, etc.

La CommentInputBar intégrée gère automatiquement l'autocomplétion des @mentions.

Modifier

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

Le serveur régénère le HTML. Le commentaire local se met à jour automatiquement.

Supprimer

try await sdk.deleteComment(commentId: commentId)

La suppression d'un commentaire supprime également ses descendants dans l'arbre local.

Les deux actions sont disponibles via le menu contextuel du commentaire dans l'interface utilisateur lorsque l'utilisateur actuel est l'auteur du commentaire (ou un administrateur du site).

Les méthodes du SDK lèvent FastCommentsError, qui est conforme à LocalizedError:

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

FastCommentsError properties:

• code -- code d'erreur provenant de l'API
• reason -- description de l'erreur en anglais
• translatedError -- message d'erreur localisé fourni par le serveur

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

Indiquez un code de locale dans la configuration pour localiser les chaînes fournies par le serveur :

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

Les chaînes de l'interface utilisateur côté client utilisent la localisation basée sur les bundles iOS.

Le dépôt inclut une application d'exemple complète dans ExampleApp/ avec des démonstrations de :

• Commentaires en arborescence avec SSO et thèmes personnalisés
• Fil social avec création de publications et filtrage par tag
• Chat en direct
• Flux SSO simples et sécurisés
• Boutons de barre d'outils personnalisés (commentaires et fil)