Adicionar Comentários ao Seu Aplicativo Django

Forneça ao seu agente de codificação o contexto do FastComments que ele precisa – widgets, configuração, SSO seguro, a API REST e os SDKs:

npx skills add fastcomments/skills

Funciona com Claude Code, Codex, Cursor, Copilot, Gemini e todos os outros agentes que o skills CLI suporta.

• Python 3.10+
• Django 4.2, 5.0, 5.1, or 5.2
• Um ID de locatário FastComments (use demo para experimentar sem uma conta)
• Um segredo de API é necessário apenas para SSO Seguro

Instale a partir de uma tag de lançamento (este projeto é distribuído via tags git, não PyPI):

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

Para acesso REST do lado do servidor (os auxiliares admin() / public_api()), adicione o api extra, que inclui o cliente gerado pelo SDK:

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

Adicione o aplicativo ao INSTALLED_APPS:

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

Configure seu tenant em settings.py:

import os

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

Insira o widget em qualquer template:

{% load fastcomments %}

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

Para passar o usuário conectado ao widget automaticamente, as tags leem o usuário atual a partir da requisição. Certifique‑se de que seu projeto possui ambos (eles estão ativados por padrão em um projeto Django padrão):

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

Sem uma requisição no contexto do template, os widgets são renderizados para um visitante anônimo. Você sempre pode passar um usuário explicitamente: {% fastcomments user=some_user %}.

Cada widget tem sua própria tag. Todas aceitam argumentos de palavra-chave **extra, que são mesclados na configuração do widget como estão (use chaves em camelCase) para qualquer coisa não coberta pelos argumentos nomeados abaixo.

Os argumentos nomeados mapeiam para as chaves de configuração camelCase do widget:

Exemplos:

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

{# O chat colaborativo se anexa a um elemento existente na página #}
<article id="post-body">...</article>
{% fastcomments_collab_chat target="#post-body" %}

{# Contagens em massa: coloque os marcadores, então um carregador em massa preenche todos #}
{% for post in posts %}
    <a href="\{{ post.url }}">\{{ post.title }}</a>
    {% fastcomments_count_marker url_id=post.url_id %}
{% endfor %}
{% fastcomments_comment_count_bulk %}

Ative o SSO e escolha um modo em settings.py. O SSO Secure assina o usuário no lado do servidor com HMAC-SHA256 usando seu API secret e é o recomendado.

FASTCOMMENTS = {
    "TENANT_ID": os.environ["FASTCOMMENTS_TENANT_ID"],
    "API_KEY": os.environ["FASTCOMMENTS_API_KEY"],   # seu API secret; assina o SSO Secure
    "SSO": {
        "ENABLED": True,
        "MODE": "secure",                            # "secure" | "simple"
        # Mapeie os campos do FastComments para o seu modelo de usuário. Os valores podem ser
        # um nome de atributo, um caminho com pontos ("profile.avatar_url"), um callable(user) ou 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, ou caminho com pontos
        "IS_MODERATOR": None,
        "GROUP_IDS": None,                           # callable(user) -> list, ou caminho com pontos
    },
}

Escolha o id do SSO deliberadamente. O id do FastComments é o identificador permanente do histórico de comentários de um usuário. O USER_MAP padrão o mapeia para a sua chave primária do Django por conveniência de configuração zero, mas chaves primárias inteiras sequenciais são enumeráveis e difíceis de alterar depois (mudar o id de um usuário divide o histórico dele em uma nova conta). Para qualquer coisa além de uma demo, mapeie id para um valor estável e opaco escolhido desde o início (um UUID ou um id público dedicado), e nunca coloque dados privados nele. O app de exemplo usa um id baseado no nome de usuário por esse motivo.

O SSO é injetado automaticamente em {% fastcomments %}, {% fastcomments_live_chat %}, {% fastcomments_collab_chat %}, {% fastcomments_image_chat %} e {% fastcomments_user_activity %} para o usuário atual.

As URLs de login/logout exibidas para visitantes desconectados assumem como padrão reverse("login") / reverse("logout"); sobrescreva-as com SSO["LOGIN_URL"] / SSO["LOGOUT_URL"].

Mapeamento personalizado

Duas opções de precedência mais alta têm prioridade sobre USER_MAP:

• Um método no seu modelo de usuário (o análogo Pythonico de uma interface):

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

• Um mapper global, um caminho com pontos para callable(user) -> dict:

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

A precedência é USER_MAPPER > to_fastcomments_user_data() > USER_MAP.

Com o extra [api] instalado, chame a API REST do FastComments através do SDK, pré-configurada com sua chave de API e região:

from fastcomments_django import admin, public_api, get_manager

admin().get_comments("YOUR_TENANT_ID", ...)     # autenticado (DefaultApi)
public_api().get_comments_public(...)            # público (PublicApi)

# Gere um token SSO para chamadas de API ou entrega ao cliente:
token = get_manager().sso().token_for(request.user)

Defina REGION para direcionar os widgets e a API para a UE:

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

Substitua fastcomments/widget.html colocando sua própria cópia mais cedo no
caminho de pesquisa de templates (um projeto templates/fastcomments/widget.html). Isto é
o análogo do Django ao vendor:publish --tag=fastcomments-views do Laravel.

Um showcase executável está em example/: um aplicativo de barra lateral esquerda + palco principal com uma página por widget e uma página de login listando usuários de demonstração pré-carregados. Faça login como qualquer um deles e os widgets de comentário e chat ao vivo autenticam essa identidade via Secure SSO. A partir desse diretório:

python manage.py migrate
# Use seu próprio tenant para ver o Secure SSO em ação (uma secret de API habilita isso):
FASTCOMMENTS_TENANT_ID=... FASTCOMMENTS_API_KEY=... python manage.py runserver

Sem um secret de API ele volta ao tenant público demo (anônimo). example/browser_smoke.py é um teste e2e do Playwright que carrega a página em um navegador real e publica um comentário como o usuário Secure-SSO.