Add Comments to Your iOS App

• עצי תגובות מסודרים עם תגובות מקוננות וחלוקה לדפים
• פיד חברתי עם יצירת פוסטים, תגובות והצמדים של מדיה
• מצב צ'אט חי עם גלילה אוטומטית ומפרידי תאריכים
• עדכונים בזמן אמת באמצעות WebSocket (תגובות חדשות, הצבעות, נוכחות)
• כניסה חד-פעמית (SSO פשוט לבדיקות, SSO מאובטח לסביבת ייצור)
• עריכת טקסט עשיר עם הדגשה, נטוי, קוד ו-@mentions
• הצבעה עם סגנונות ניתנים להתאמה (חיצים למעלה/למטה או לבבות)
• פעולות מודרציה: דיווח, נעיצה, נעילה, חסימה
• עיצוב מקיף עם תבניות והתאמה אישית מלאה
• כפתורים מותאמים בסרגל הכלים ליצירת תגובות ופוסטים בפיד
• העלאות תמונות
• תמיכה באזור האיחוד האירופי
• נוכחות משתמש (סימוני מקוון/לא מקוון)
• סינון פיד מבוסס תגיות
• תמיכה בלוקליזציה

• iOS 16+ או macOS 14+
• Swift 5.9+
• SwiftUI

הוסף את FastCommentsUI לפרויקט שלך באמצעות Swift Package Manager.

ב‑Xcode: File > Add Package Dependencies, ואז הזן את כתובת המאגר.

או הוסף אותו ל־Package.swift:

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

לאחר מכן הוסף את המוצר ל־target שלך:

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

ייבא את שני המודולים היכן שנדרש:

import FastCommentsUI
import FastCommentsSwift

ההגדרה המינימלית להצגת ווידג'ט תגובות:

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

החלף את "demo" ב־tenant ID של FastComments שלך. ה־urlId מזהה את העמוד או השרשור שבו מאוחסנות התגובות.

FastComments תומך בשלושה מצבי אימות:

1. Anonymous -- ללא אסימון SSO; למשתמשים ניתנות זהויות מבוססות סשן
2. Simple SSO -- אסימון בצד הלקוח עבור הדגמות ובדיקות (לא מאובטח)
3. Secure SSO -- אסימון החתום על ידי השרת לשימוש בייצור

Simple SSO

שימושי להדגמות ובדיקות מקומיות. כל אחד יכול להתחפש לכל משתמש עם Simple SSO, לכן אל תשתמשו בו בפרודקשן.

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 תומך גם בשדות אופציונליים:

• id -- מזהה משתמש (ברירת מחדל: דואר אלקטרוני אם לא מוגדר)
• displayName -- שם תצוגה נפרד
• displayLabel -- תווית מותאמת שמוצגת לצד השם (למשל "VIP")
• websiteUrl -- קישור על שם המשתמש
• locale -- קוד שפה/אזור
• isProfileActivityPrivate -- הסתרת פעילות הפרופיל (ברירת מחדל: true)

Secure SSO

בפרודקשן, ה-backend שלכם מייצר אסימון SSO חתום באמצעות סוד ה-API שלכם. אפליקציית iOS מקבלת את האסימון מהשרת שלכם ומעבירה אותו לקונפיגורציה.

בצד השרת שלכם (באמצעות ה-FastComments Swift SDK או בכל שפה):

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

ביישום ה-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 {
            // 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 תומך בשדות נוספים:

• optedInNotifications -- הסכמה לקבלת התראות בדואר אלקטרוני
• displayLabel -- תווית מותאמת
• displayName -- שם תצוגה
• websiteUrl -- כתובת האתר
• groupIds -- שייכות לקבוצות
• isAdmin -- הרשאות מנהל
• isModerator -- הרשאות מודרטור
• isProfileActivityPrivate -- פרטיות פעילות הפרופיל

שימוש בסיסי

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

סגנונות הצבעה

הסגנון ברירת המחדל מציג חצים למעלה/למטה. העבר את ._1 כדי לקבל הצבעות בסגנון לב:

FastCommentsView(sdk: sdk, voteStyle: ._1)

קריאות חזרה של אירועים

השתמש בקריאות חזרה בסגנון modifier כדי לטפל באינטראקציות משתמש:

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
        // המקור הוא .name או .avatar
        print("Tapped \(userInfo.displayName)")
    }

החלת ערכת נושא

העבר ערכת נושא דרך סביבת SwiftUI:

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

או קבע אותה ישירות ב-SDK:

sdk.theme = FastCommentsTheme.modern

כיוון המיון

sdk.defaultSortDirection = .nf  // החדשים ביותר תחילה (ברירת מחדל)
sdk.defaultSortDirection = .of  // הישנים ביותר תחילה
sdk.defaultSortDirection = .mr  // הרלוונטיים ביותר

LiveChatView מספק חוויית צ'אט בזמן אמת עם גלילה אוטומטית, מפרידי תאריכים וממשק קומפקטי. הוא מגדיר אוטומטית את ה-SDK למיון מהעתיק לחדש ותצוגה חיה מיידית.

struct ChatView: View {
    @StateObject private var sdk: FastCommentsSDK = {
        let config = FastCommentsWidgetConfig(
            tenantId: "YOUR_TENANT_ID",
            urlId: "chat-room-1",
            sso: ssoToken  // מומלץ להשתמש ב-SSO כדי שלמשתמשים יהיו שמות
        )
        return FastCommentsSDK(config: config)
    }()

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

LiveChatView תומך בקריאות חזרה אלה:

• .onCommentPosted -- נקרא כאשר המשתמש שולח הודעה
• .onCommentDeleted -- נקרא כאשר הודעה נמחקת
• .onUserClick -- נקרא כאשר נלחץ שם המשתמש או תמונת הפרופיל שלו

The feed system is a separate SDK (FastCommentsFeedSDK) with its own view.

טעינה והצגת הפיד

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
                // Present share sheet
            }
            .onUserClick { context, userInfo, source in
                // Navigate to user profile
            }
            .onMediaClick { mediaItem, index in
                // Present full-screen image viewer
            }
            .task {
                try? await sdk.load()
            }
    }
}

תצוגת הפיד כוללת משיכה לרענון וגלילה אינסופית באופן אוטומטי.

יצירת פוסטים

Use FeedPostCreateView to present a post creation form:

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

תגובות לפוסטים

The SDK handles reactions with optimistic 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)

פתיחת תגובות לפוסט

Use CommentsSheet to display comments for a feed post. It creates a FastCommentsSDK instance internally using the feed SDK's config:

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

הערה: FeedPost חייב להתאים לפרוטוקול Identifiable עבור .sheet(item:). הוסף את ההרחבה הזו:

extension FeedPost: @retroactive Identifiable {}

סינון פיד מבוסס תגיות

Implement the TagSupplier protocol to filter feed posts by tags:

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

sdk.tagSupplier = TeamTagSupplier()

החזר nil כדי לקבל פיד גלובלי ללא סינון.

שמירה ושחזור מצב הפיד

Preserve pagination state across view lifecycle events:

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

מחיקת פוסטים

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

תבניות נושא

ארבע תבניות מובנות זמינות:

// ברירות מחדל של המערכת
sdk.theme = FastCommentsTheme.default

// קלפים עם צללים ופינות מעוגלות גדולות
sdk.theme = FastCommentsTheme.modern

// שטוח, ללא צללים, רדיוס פינות קטן, ללא קווי שרשור
sdk.theme = FastCommentsTheme.minimal

// קבע את כל צבעי הפעולות לצבע מותג יחיד
sdk.theme = FastCommentsTheme.allPrimary(.indigo)

סגנונות תצוגת תגובות

var theme = FastCommentsTheme()
theme.commentStyle = .flat    // רשימה שטוחה עם מפרידים (ברירת מחדל)
theme.commentStyle = .card    // קלפים מעוגלים עם צללים
theme.commentStyle = .bubble  // סגנון בועת שיחה

צבעים

כל מאפייני הצבע אופציונליים. ערכים שלא הוגדרו יחזרו לברירות המחדל הסבירות של המערכת.

var theme = FastCommentsTheme()

// צבעי מותג
theme.primaryColor = .indigo
theme.primaryLightColor = .indigo.opacity(0.6)
theme.primaryDarkColor = Color(red: 0.2, green: 0.1, blue: 0.5)

// רקעים
theme.commentBackgroundColor = Color(.secondarySystemGroupedBackground)
theme.containerBackgroundColor = Color(.systemGroupedBackground)

// כפתורי פעולה
theme.actionButtonColor = .indigo
theme.replyButtonColor = .indigo
theme.toggleRepliesButtonColor = .indigo.opacity(0.8)
theme.loadMoreButtonTextColor = .indigo

// הצבעות
theme.voteActiveColor = .red
theme.voteCountColor = .primary
theme.voteCountZeroColor = .secondary
theme.voteDividerColor = Color(.separator)

// קישורים
theme.linkColor = .indigo
theme.linkColorPressed = .indigo.opacity(0.5)

// תיבות דו-שיח
theme.dialogHeaderBackgroundColor = .indigo
theme.dialogHeaderTextColor = .white

// סרגל קלט
theme.inputBarBackgroundColor = Color(.systemBackground)
theme.inputBarBorderColor = Color(.separator)

// אחרים
theme.onlineIndicatorColor = .green
theme.separatorColor = Color(.separator)
theme.badgeBackgroundColor = .gray.opacity(0.2)
theme.threadLineColor = .indigo.opacity(0.15)

טיפוגרפיה

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

פריסה וריווח

theme.cornerRadius = .large       // אפשרויות: .none, .small, .medium, .large
theme.commentSpacing = 4          // נקודות בין שורות תגובות
theme.nestingIndent = 20          // נקודות הזחה לכל רמת שרשור
theme.avatarSize = 36             // קוטר האוואטר לתגובות שורש
theme.replyAvatarSize = 28        // קוטר האוואטר לתגובות מקוננות

אפקטים ויזואליים

theme.showShadows = true          // צללים עדינים על קלפים
theme.showThreadLine = true       // קו אנכי המחבר תגובות מקוננות
theme.animateVotes = true         // אנימציית קפיץ בעת שינויי הצבעה

החלת ערכות נושא

שתי גישות:

// Via SwiftUI environment (recommended for view hierarchy)
FastCommentsView(sdk: sdk)
    .fastCommentsTheme(theme)

// Directly on the SDK
sdk.theme = theme

כפתורי סרגל הכלים של תגובות

ממש את הפרוטוקול CustomToolbarButton כדי להוסיף כפתורים לסרגל הכלים של שדה התגובה:

struct EmojiButton: CustomToolbarButton {
    let id = "emoji"
    let iconSystemName = "face.smiling"       // שם ה-SF Symbol
    let contentDescription = "Add Emoji"
    let badgeText: String? = nil              // ספירת תג אופציונלית

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

    // אפשרויות ברירת מחדל שניתנות להחלפה (ברירת מחדל true)
    func isEnabled() -> Bool { true }
    func isVisible() -> Bool { true }
}

העבר כפתורים מותאמים בעת יצירת התצוגה:

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

או הוסף אותם באופן גלובלי ב-SDK (חל על כל המופעים):

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

כפתורי סרגל הכלים של הפיד

ממש את FeedCustomToolbarButton עבור טופס יצירת הפוסט:

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

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

העבר אותם לתצוגת היצירה:

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

או הגדר אותם גלובלית ב-SDK של הפיד:

sdk.globalFeedToolbarButtons = [HashtagButton()]

פעולות זמינות לכל המשתמשים

• סמן/בטל סימון -- לדווח על תגובה לבחינה

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

• חסום/בטל חסימה -- להסתיר את כל התגובות של משתמש (לצופה ספציפי)

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

פעולות למנהלים בלבד

• הצמד/בטל הצמדה -- להצמיד תגובה לראש השרשור

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

• נעל/בטל נעילה -- למנוע תגובות חדשות על תגובה

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

כל פעולות המודרציה זמינות גם דרך תפריט ההקשר של תגובה בממשק המשתמש. פעולות מנהל מופיעות רק כאשר המשתמש הנוכחי הוא מנהל האתר (נקבע באמצעות דגל SSO isAdmin או בהגדרות לוח הבקרה).

לאחר קריאה ל-sdk.load(), ה-SDK נרשם אוטומטית לאירועי WebSocket עבור urlId המוגדר. האירועים הבאים מטופלים:

• תגובות חדשות, עריכות ומחיקות
• הצבעות (הוספה והסרה)
• שינויים במצב נעיצה, נעילה, דגל וחסימה
• נוכחות משתמש (הצטרפות/עזיבה)
• פתיחה/סגירה של שרשור
• הענקת תגים
• עדכוני תצורת השרת

שליטה בתצוגה החיה

כברירת מחדל, תגובות חדשות ממשתמשים אחרים מופיעות מיד:

sdk.showLiveRightAway = true   // כברירת מחדל: הצג מיד

הגדר זאת ל-false כדי לאגר תגובות חדשות מאחורי כפתור "N תגובות חדשות", מה שמאפשר למשתמש לבחור מתי לחשוף אותן:

sdk.showLiveRightAway = false

נוכחות משתמש

מחווני מקוון/לא מקוון מופיעים אוטומטית על האווטרים של המשתמשים כאשר השרת מאפשר מעקב נוכחות. אין צורך בקונפיגורציה נוספת בצד הלקוח.

גודל עמוד

// תגובות: ברירת מחדל 30
sdk.pageSize = 50

// פיד: ברירת מחדל 10
feedSDK.pageSize = 20

טעינת תגובות נוספות

ממשק המשתמש מציג אוטומטית בקרי עימוד. ניתן גם להפעיל עימוד באופן תכנותי:

// טען את העמוד הבא
try await sdk.loadMore()

// טען את כל הנותרים (מושבת אם >2000 תגובות מטעמי ביצועים)
try await sdk.loadAll()

// בדוק מצב
sdk.hasMore            // האם קיימים עמודים נוספים
sdk.shouldShowLoadAll()
sdk.getCountRemainingToShow()

עימוד תגובות משנה

תשובות מקוננות נטענות באופן עצלני. כאשר משתמש מרחיב שרשור, חמש ה"ילדים" הראשונים נטענים. כפתור "טען עוד תגובות" יופיע אם קיימות תגובות נוספות. זה מנוהל אוטומטית על ידי ממשק המשתמש.

שני FastCommentsSDK ו־FastCommentsFeedSDK הם מחלקות מסוג ObservableObject עם תכונות @Published. ניתן לצפות בהן בתוך תצוגות SwiftUI שלך לקבלת עדכוני ממשק משתמש ריאקטיביים.

תכונות Published של FastCommentsSDK

תכונות Published של FastCommentsFeedSDK

עץ התגובות

ניתן לגשת לעץ התגובות דרך sdk.commentsTree:

// רשימה שטוחה של צמתים גלויים להצגה
sdk.commentsTree.visibleNodes

// חיפוש תגובה לפי מזהה
sdk.commentsTree.commentsById["comment-id"]

כדי להשתמש במרכז הנתונים של האיחוד האירופי, הגדר את השדה region בקונפיגורציה שלך:

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

זה מנתב את כל בקשות ה-API והחיבורים של WebSocket אל eu.fastcomments.com.

כשתסיימו עם מופע של ה-SDK (למשל, כאשר התצוגה מתבטלת), קראו ל-cleanup() כדי לסגור את חיבור ה-WebSocket ולבטל משימות ברקע:

sdk.cleanup()

עבור תצוגות הנוהלות על ידי @StateObject של SwiftUI, בדרך כלל נקרא לזה ב-.onDisappear או כאשר התצוגה משוחררת מהזיכרון.

תגובות

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

מחזיר את מחרוזת ה-URL של התמונה שהועלתה.

פוסטים בפיד

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

// העלאת מספר תמונות במקביל
let mediaItems = try await feedSDK.uploadImages(images: [
    (jpegData1, "photo1.jpg"),
    (jpegData2, "photo2.jpg")
])

Search for users to support @mention autocomplete:

let results = try await sdk.searchUsers(query: "jan")
// מחזיר [UserSearchResult] עם userId, username, avatar וכו'.

The built-in CommentInputBar מטפל בהשלמה האוטומטית של @mention.

עריכה

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

השרת מייצר מחדש את ה-HTML. התגובה המקומית מתעדכנת אוטומטית.

מחיקה

try await sdk.deleteComment(commentId: commentId)

מחיקת תגובה מסירה גם את הצאצאים שלה מהעץ המקומי.

שתי הפעולות זמינות דרך תפריט ההקשר של התגובה בממשק המשתמש כאשר המשתמש הנוכחי הוא מחבר התגובה (או מנהל האתר).

שיטות SDK זורקות FastCommentsError, שמעומדת ל-LocalizedError:

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

FastCommentsError מאפיינים:

• code -- קוד שגיאה מה-API
• reason -- תיאור השגיאה באנגלית
• translatedError -- הודעת שגיאה מתורגמת המסופקת על ידי השרת

שגיאות החוסמות גם מוצגות אוטומטית באמצעות sdk.blockingErrorMessage, שהתצוגות המובנות מציגות למשתמש.

העבר קוד locale בקונפיגורציה כדי לבצע לוקליזציה של מחרוזות שמסופקות על ידי השרת:

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

מחרוזות ממשק המשתמש בצד הלקוח משתמשות בלוקליזציה מבוססת bundle של iOS.

המאגר כולל אפליקציית דוגמה מלאה ב־ExampleApp/ עם הדגמות של:

• תגובות מקוננות עם SSO ונושאים מותאמים
• פיד חברתי עם יצירת פוסטים וסינון לפי תגיות
• צ'אט חי
• זרימות SSO פשוטות ומאובטחות
• כפתורי סרגל כלים מותאמים (לתגובות ולפיד)