Adicionar Comentários ao seu aplicativo Django

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

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:

Examples:

{% load fastcomments %}

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

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

Comentários: {% fastcomments_comment_count url_id="my-page" number_only=True %}

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

{# Contagens em lote: coloque os marcadores, então um carregador em lote os 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 %}

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"],   # seu segredo da API; assina o 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
    },
}

Escolha o SSO id deliberadamente. O FastComments id é o identificador permanente
handle para o histórico de comentários de um usuário.
O USER_MAP padrão mapeia isso para o seu
chave primária do Django para conveniência zero-config, mas PKs inteiros sequenciais são
enumeráveis e difíceis de mudar depois (alterar o id de um usuário divide seu
histórico em uma nova conta). Para tudo além de uma demonstração, mapeie o id para um valor estável,
valor opaco escolhido previamente (um UUID ou um id público dedicado), e nunca coloque
dados privados nele. O aplicativo de exemplo usa um id baseado em nome de usuário por esse motivo.

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"].

Custom mapping

Two higher-precedence options beat USER_MAP:

• A method on your user model (the Pythonic analog of an interface):

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

• A global mapper, a dotted path to callable(user) -> dict:

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

Precedence is 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.