Додайте коментарі до вашого Django‑додатку

• Python 3.10+
• Django 4.2, 5.0, 5.1, або 5.2
• Ідентифікатор орендаря FastComments (використайте demo, щоб спробувати без облікового запису)
• Секрет API потрібний лише для Secure SSO

Встановіть з тегу випуску (цей проєкт розповсюджується через git‑теги, а не через PyPI):

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

Для серверного доступу до REST (використовуючи допоміжні функції admin() / public_api()), додайте додатковий параметр api, який підключає згенерований клієнт SDK:

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

Додайте застосунок до INSTALLED_APPS:

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

Налаштуйте ваш тенант у settings.py:

import os

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

Вставте віджет у будь‑який шаблон:

{% load fastcomments %}

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

Щоб автоматично передати залогіненого користувача у віджет, теги читають поточного користувача з запиту. Переконайтеся, що ваш проект має обидва ці налаштування (вони увімкнені за замовчуванням у стандартному проекті Django):

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

Якщо в контексті шаблону немає запиту, віджети відображаються для анонімного відвідувача. Ви завжди можете передати користувача явно: {% fastcomments user=some_user %}.

Кожен віджет має свій власний тег. Усі вони приймають **extra аргументи‑ключові, які об’єднуються в конфігурацію віджета без змін (використовуйте camelCase ключі) для будь‑якого параметра, що не охоплений іменованими аргументами нижче.

Іменовані аргументи відповідають camelCase ключам конфігурації віджета:

Приклади:

{% load fastcomments %}

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

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

Коментарі: {% fastcomments_comment_count url_id="my-page" number_only=True %}

{# Collab chat приєднується до існуючого елемента на сторінці #}
<article id="post-body">...</article>
{% fastcomments_collab_chat target="#post-body" %}

{# Bulk counts: розмістіть маркери, потім один bulk loader заповнює їх усі #}
{% 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 and choose a mode in settings.py. Secure SSO signs the user server-side with HMAC-SHA256 using your API secret and is recommended.

FASTCOMMENTS = {
    "TENANT_ID": os.environ["FASTCOMMENTS_TENANT_ID"],
    "API_KEY": os.environ["FASTCOMMENTS_API_KEY"],   # your API secret; signs Secure SSO
    "SSO": {
        "ENABLED": True,
        "MODE": "secure",                            # "secure" | "simple"
        # Map FastComments fields to your user model. Values may be an attribute
        # name, a dotted path ("profile.avatar_url"), a callable(user), or 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, or dotted path
        "IS_MODERATOR": None,
        "GROUP_IDS": None,                           # callable(user) -> list, or dotted path
    },
}

Вибирайте SSO id свідомо. FastComments id — це постійний ідентифікатор історії коментарів користувача. За замовчуванням USER_MAP прив'язує його до вашого первинного ключа Django для зручності без налаштувань, але послідовні цілі числові PK є перелічуваними та їх важко пізніше змінити (зміна id користувача розділяє його історію на новий обліковий запис). Для будь‑якого використання понад демо, прив'яжіть id до стабільного, непрозорого значення, вибраного заздалегідь (UUID або присвячений публічний id), і ніколи не розміщуйте в ньому приватні дані. Приклад застосунку використовує id, оснований на імені користувача, з цієї причини.

SSO is injected automatically into {% fastcomments %}, {% fastcomments_live_chat %}, {% fastcomments_collab_chat %}, {% fastcomments_image_chat %}, and {% fastcomments_user_activity %} for the current user.

Login/logout URLs shown to signed-out visitors default to reverse("login") / reverse("logout"); override them with SSO["LOGIN_URL"] / SSO["LOGOUT_URL"].

Кастомне зіставлення

Two higher-precedence options beat USER_MAP:

• Метод у вашій моделі користувача (пайтонічний аналог інтерфейсу):

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

• Глобальний мапер, крапковий шлях до callable(user) -> dict:

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

Precedence is USER_MAPPER > to_fastcomments_user_data() > USER_MAP.

З встановленим додатком [api], викликайте REST API FastComments через SDK, попередньо налаштований з вашим API‑ключем і регіоном:

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)

Встановіть REGION, щоб маршрутизувати віджети та API до ЄС:

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

Перевизначте fastcomments/widget.html, розмістивши свою копію раніше у шляху пошуку шаблонів (проект templates/fastcomments/widget.html). Це аналог Django для 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
# Використайте свій власний tenant, щоб побачити Secure SSO в дії (API‑секрет його вмикає):
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.