Dodaj komentarze do swojej aplikacji Django

• Python 3.10+
• Django 4.2, 5.0, 5.1, or 5.2
• Identyfikator najemcy FastComments (użyj demo, aby wypróbować bez konta)
• Tajny klucz API jest wymagany tylko dla Secure SSO

Zainstaluj z tagu wydania (ten projekt jest dystrybuowany za pośrednictwem tagów git, a nie PyPI):

pip install "git+https://github.com/fastcomments/fastcomments-django.git@v0.1.0"

Aby uzyskać dostęp do REST po stronie serwera (pomocnicze funkcje admin() / public_api()), dodaj api extra, który pobiera wygenerowanego klienta SDK:

pip install "fastcomments-django[api] @ git+https://github.com/fastcomments/fastcomments-django.git@v0.1.0"

Dodaj aplikację do INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "fastcomments_django",
]

Skonfiguruj swojego najemcę w settings.py:

import os

FASTCOMMENTS = {
    "TENANT_ID": os.environ.get("FASTCOMMENTS_TENANT_ID", "demo"),
}

Umieść widget w dowolnym szablonie:

{% load fastcomments %}

{% fastcomments url_id="my-page" %}

Aby automatycznie przekazać zalogowanego użytkownika do widgetu, tagi odczytują bieżącego użytkownika z żądania. Upewnij się, że Twój projekt ma oba te elementy (są domyślnie włączone w standardowym projekcie Django):

• django.template.context_processors.request w TEMPLATES["OPTIONS"]["context_processors"]
• django.contrib.auth.middleware.AuthenticationMiddleware w MIDDLEWARE

Bez żądania w kontekście szablonu, widgety renderują się dla anonimowego gościa. Zawsze możesz przekazać użytkownika wyraźnie: {% fastcomments user=some_user %}.

Every widget has its own tag. All of them accept **extra keyword arguments, which are merged into the widget config as‑is (use camelCase keys) for anything not covered by the named arguments below.

Named arguments map to the widget's camelCase config keys:

Przykłady:

{% load fastcomments %}

{% fastcomments url_id="my-page" locale="en_us" default_sort_direction="MR" %}

{% fastcomments_live_chat url_id="room-1" %}

Comments: {% fastcomments_comment_count url_id="my-page" number_only=True %}

{# Czat współpracy dołącza do istniejącego elementu na stronie #}
<article id="post-body">...</article>
{% fastcomments_collab_chat target="#post-body" %}

{# Zliczenia zbiorcze: umieść znaczniki, a następnie jeden loader zbiorczy wypełni je wszystkie #}
{% for post in posts %}
    <a href="\{{ post.url }}">\{{ post.title }}</a>
    {% fastcomments_count_marker url_id=post.url_id %}
{% endfor %}
{% fastcomments_comment_count_bulk %}

Enable SSO i wybierz tryb w settings.py. Secure SSO podpisuje użytkownika po stronie serwera przy użyciu HMAC‑SHA256 i Twojego sekretu API i jest zalecane.

FASTCOMMENTS = {
    "TENANT_ID": os.environ["FASTCOMMENTS_TENANT_ID"],
    "API_KEY": os.environ["FASTCOMMENTS_API_KEY"],   # Twój sekret API; podpisuje Secure SSO
    "SSO": {
        "ENABLED": True,
        "MODE": "secure",                            # "secure" | "simple"
        # Mapuj pola FastComments na swój model użytkownika. Wartości mogą być atrybutem
        # nazwą, ścieżką kropkową ("profile.avatar_url"), wywoływalnym(user) lub None.
        "USER_MAP": {
            "id": "id",
            "email": "email",
            "username": "username",
            "avatar": None,
            "display_name": None,
            "website_url": None,
        },
        "IS_ADMIN": lambda user: user.is_staff,      # callable(user) -> bool, lub ścieżka kropkowa
        "IS_MODERATOR": None,
        "GROUP_IDS": None,                           # callable(user) -> list, lub ścieżka kropkowa
    },
}

Wybierz identyfikator SSO id świadomie. Identyfikator FastComments id jest trwałym odnośnikiem do historii komentarzy użytkownika. Domyślne USER_MAP mapuje go na klucz główny Django dla wygody bez dodatkowej konfiguracji, ale kolejno przydzielane całkowite klucze PK są wyliczalne i trudne do późniejszej zmiany (zmiana id użytkownika dzieli ich historię na nowe konto). Dla wszystkiego poza demonstracją, mapuj id na stabilną, nieprzezroczystą wartość wybraną z góry (UUID lub dedykowany publiczny identyfikator) i nigdy nie umieszczaj w nim prywatnych danych. Przykładowa aplikacja używa identyfikatora opartego na nazwie użytkownika z tego powodu.

SSO jest wstrzykiwane automatycznie do {% fastcomments %}, {% fastcomments_live_chat %}, {% fastcomments_collab_chat %}, {% fastcomments_image_chat %} i {% fastcomments_user_activity %} dla bieżącego użytkownika.

Login/logout URLs wyświetlane niezalogowanym gościom domyślnie to reverse("login") / reverse("logout"); można je zastąpić za pomocą SSO["LOGIN_URL"] / SSO["LOGOUT_URL"].

Niestandardowe mapowanie

Dwie opcje o wyższym priorytecie mają pierwszeństwo przed USER_MAP:

• Metoda w Twoim modelu użytkownika (pythoniczny odpowiednik interfejsu):

  class User(AbstractUser):
      def to_fastcomments_user_data(self):
          return {"id": self.pk, "email": self.email, "username": self.get_username()}

• Globalny mapper, ścieżka kropkowa do callable(user) -> dict:

  FASTCOMMENTS = {"SSO": {"USER_MAPPER": "myapp.sso.map_user"}}

Priorytet jest następujący: USER_MAPPER > to_fastcomments_user_data() > USER_MAP.

Po zainstalowaniu dodatku [api] wywołaj REST API FastComments poprzez SDK, wstępnie skonfigurowane z Twoim kluczem API i regionem:

from fastcomments_django import admin, public_api, get_manager

admin().get_comments("YOUR_TENANT_ID", ...)     # authenticated (DefaultApi)
public_api().get_comments_public(...)            # public (PublicApi)

# Generate an SSO token for API calls or client hand-off:
token = get_manager().sso().token_for(request.user)

Ustaw REGION, aby kierować widżety i API do UE:

FASTCOMMENTS = {"TENANT_ID": "...", "REGION": "eu"}

Zastąp fastcomments/widget.html umieszczając własną kopię wcześniej w ścieżce wyszukiwania szablonów (w projekcie templates/fastcomments/widget.html). To jest analog Django polecenia Laravel vendor:publish --tag=fastcomments-views.

A runnable showcase lives in example/: a left-rail + main-stage
app with a page per widget and a sign-in page listing pre-seeded demo users.
Sign in as any of them and the comment and live-chat widgets authenticate that
identity via Secure SSO. From that directory:

python manage.py migrate
# Use your own tenant to see Secure SSO in action (an API secret enables it):
FASTCOMMENTS_TENANT_ID=... FASTCOMMENTS_API_KEY=... python manage.py runserver

Without an API secret it falls back to the public demo tenant (anonymous).
example/browser_smoke.py is a Playwright e2e
that loads the page in a real browser and posts a comment as the Secure‑SSO
user.