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

Надайте вашому агенту коду контекст FastComments, який йому потрібен — віджети, конфігурація, Secure SSO, REST API та SDK:

npx skills add fastcomments/skills

Працює з Claude Code, Codex, Cursor, Copilot, Gemini та будь‑яким іншим агентом, який підтримує skills CLI.

• 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 %}

Увімкніть SSO та оберіть режим у settings.py. Безпечний SSO підписує користувача на стороні сервера за допомогою HMAC-SHA256 з використанням вашого API-секрету і є рекомендованим.

FASTCOMMENTS = {
    "TENANT_ID": os.environ["FASTCOMMENTS_TENANT_ID"],
    "API_KEY": os.environ["FASTCOMMENTS_API_KEY"],   # ваш API-секрет; підписує Secure SSO
    "SSO": {
        "ENABLED": True,
        "MODE": "secure",                            # "secure" | "simple"
        # Зіставте поля FastComments з вашою моделлю користувача. Значенням може бути
        # ім'я атрибута, шлях через крапку ("profile.avatar_url"), callable(user) або 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, або шлях через крапку
        "IS_MODERATOR": None,
        "GROUP_IDS": None,                           # callable(user) -> list, або шлях через крапку
    },
}

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

SSO автоматично впроваджується у {% fastcomments %}, {% fastcomments_live_chat %}, {% fastcomments_collab_chat %}, {% fastcomments_image_chat %} та {% fastcomments_user_activity %} для поточного користувача.

URL-адреси входу/виходу, що показуються відвідувачам, які не увійшли, за замовчуванням — reverse("login") / reverse("logout"); перевизначте їх через SSO["LOGIN_URL"] / SSO["LOGOUT_URL"].

Користувацьке зіставлення

Два параметри з вищим пріоритетом мають перевагу над 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"}}

Пріоритет: 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.

Запусковий приклад знаходиться в example/: застосунок з лівою панеллю навігації та основною сценою, зі сторінкою для кожного віджета та сторінкою входу зі списком попередньо створених демо-користувачів. Увійдіть як будь-хто з них, і віджети коментарів та живого чату автентифікують цю особу через Secure SSO. З цього каталогу:

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

Без API-секрету відбувається повернення до публічного орендаря demo (анонімний режим). example/browser_smoke.py — це Playwright e2e-тест, який завантажує сторінку в реальному браузері та публікує коментар від імені користувача Secure SSO.