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 multimédia
• Mode de 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
• Système de 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 intégrale
• Boutons personnalisés dans la barre d'outils pour les commentaires et la création de publications du 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 étiquettes
• Prise en charge de la localisation

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

Ajoutez FastCommentsUI à votre projet en utilisant le Gestionnaire de paquets Swift.

Dans Xcode : Fichier > Ajouter des dépendances de paquet, puis entrez 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")
]

Ensuite, ajoutez le produit à votre cible:

.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'identifiant de votre locataire 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 SSO token; les utilisateurs obtiennent des identités basées sur la session
2. Simple SSO -- token côté client pour les démonstrations et les tests (non sécurisé)
3. Secure SSO -- token signé côté serveur pour la production

Simple SSO

Utile pour les démonstrations et les tests locaux. N'importe qui peut usurper l'identité de n'importe quel utilisateur avec Simple SSO, donc ne l'utilisez 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 also supports optional fields:

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

Secure SSO

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

Sur votre backend (en utilisant le FastComments Swift SDK ou n'importe quel langage):

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()
// Retournez ce jeton à votre application iOS via votre API

Dans votre application iOS :

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éez une nouvelle configuration avec le jeton, ou définissez-le avant le chargement
            isLoadingToken = false
            try? await sdk.load()
        }
    }
}

SecureSSOUserData prend en charge des champs supplémentaires :

• optedInNotifications -- inscription aux notifications par courriel
• displayLabel -- étiquette personnalisée
• displayName -- nom affiché
• 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 un style de vote en forme de cœur :

FastCommentsView(sdk: sdk, voteStyle: ._1)

Rappels d'événements

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

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

Application d'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  // Les plus récents d'abord (par défaut)
sdk.defaultSortDirection = .of  // Les plus anciens d'abord
sdk.defaultSortDirection = .mr  // Les plus pertinents

LiveChatView offre une expérience de clavardage en temps réel avec défilement automatique, séparateurs de date et mise en page compacte. Il configure automatiquement le SDK pour un tri du plus ancien au plus récent et un affichage en direct 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 appuyé

Le système de flux est un SDK distinct (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
                // Afficher la feuille de partage
            }
            .onUserClick { context, userInfo, source in
                // Naviguer vers le profil de l'utilisateur
            }
            .onMediaClick { mediaItem, index in
                // Afficher le visualiseur d'images en plein écran
            }
            .task {
                try? await sdk.load()
            }
    }
}

La vue du flux inclut automatiquement le balayage pour rafraîchir et le défilement infini.

Création de publications

Utilisez FeedPostCreateView pour présenter un formulaire de création de publication :

@State private var showCreatePost = false

// Dans le corps de votre vue :
.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")

// Vérifier l'état de la réaction
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 en interne une instance de FastCommentsSDK 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
    })
}

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

extension FeedPost: @retroactive Identifiable {}

Filtrage du flux par étiquettes

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 non filtré.

Sauvegarde et restauration de l'état du flux

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

let state = sdk.savePaginationState()
// Plus tard...
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 par défaut du système
sdk.theme = FastCommentsTheme.default

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

// Plat, sans omres, petit rayon de coin, pas de lignes de fil
sdk.theme = FastCommentsTheme.minimal

// Définit 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 bulles de chat

Couleurs

Toutes les propriétés de couleur sont optionnelles. Les valeurs non définies reviennent aux valeurs 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 de vues)
FastCommentsView(sdk: sdk)
    .fastCommentsTheme(theme)

// Directement sur le SDK
sdk.theme = theme

Boutons de la barre d'outils de commentaire

Implémentez le protocole CustomToolbarButton pour ajouter des boutons à la barre d'outils du champ de commentaire :

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

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

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

Passez les 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

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 définissez-les globalement sur le SDK du fil :

sdk.globalFeedToolbarButtons = [HashtagButton()]

Actions disponibles pour tous les utilisateurs

• Signaler/Retirer 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 spectateur)

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 de discussion

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 actuel est administrateur du site (défini via le drapeau SSO isAdmin ou la configuration du tableau de bord).

Après avoir appelé 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 (nouveaux et retirés)
• Changements d'état : épinglage, verrouillage, signalement et 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ôler l'affichage en direct

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

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

Définissez cette option sur false pour mettre en tampon les nouveaux commentaires derrière un bouton "N nouveaux commentaires", permettant à l'utilisateur de choisir quand les révéler :

sdk.showLiveRightAway = false

Présence des utilisateurs

Les 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 la page

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

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

Charger plus de commentaires

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

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

// Charger tout le reste (désactivé si >2000 commentaires pour des raisons de performance)
try await sdk.loadAll()

// Vérifier l'état
sdk.hasMore            // Indique s'il y a d'autres pages
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

Pagination des commentaires enfants

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

Les deux FastCommentsSDK et FastCommentsFeedSDK sont des classes ObservableObject avec des propriétés @Published. Vous pouvez les observer dans vos vues SwiftUI pour des mises à jour réactives de l'interface utilisateur.

Propriétés @Published de FastCommentsSDK

Propriétés @Published de FastCommentsFeedSDK

Arbre de commentaires

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

// Liste aplatie 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.

Lorsque vous avez terminé avec une instance du SDK (p. ex., la vue est sur le point d'être fermée), appelez cleanup() pour fermer la connexion WebSocket et annuler les tâches d'arrière-plan :

sdk.cleanup()

Pour les vues gérées par @StateObject de SwiftUI, cela 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échargée.

Publications du fil

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

// Télécharger 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")
// Retourne [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éexécute le rendu du HTML. Le commentaire local se met à jour automatiquement.

Supprimer

try await sdk.deleteComment(commentId: commentId)

La suppression d'un commentaire supprime également ses descendants de 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 lancent FastCommentsError, qui se 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 renvoyé par l'API
• reason -- description de l'erreur en anglais
• translatedError -- message d'erreur localisé fourni par le serveur

Les erreurs bloquantes sont également remontées automatiquement via sdk.blockingErrorMessage, que les vues intégrées affichent à l'utilisateur.

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 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 fils de discussion avec SSO et thèmes personnalisés
• Fil social avec création de publications et filtrage par étiquettes
• Chat en direct
• Flux SSO simples et sécurisés
• Boutons personnalisés de la barre d'outils (commentaires et fil)