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 테넌트 ID (demo를 사용해 계정 없이 체험 가능)
• Secure SSO에 대해서만 API 비밀키가 필요합니다

릴리스 태그에서 설치하기 (이 프로젝트는 PyPI가 아니라 git 태그를 통해 배포됩니다):

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

로그인한 사용자를 위젯에 자동으로 전달하려면, 태그가 요청(request)에서 현재 사용자를 읽어옵니다. 프로젝트에 아래 두 항목이 모두 포함되어 있는지 확인하세요(표준 Django 프로젝트에서는 기본적으로 활성화되어 있습니다):

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

템플릿 컨텍스트에 요청이 없으면, 위젯은 익명 방문자용으로 렌더링됩니다. 항상 명시적으로 사용자를 전달할 수 있습니다: {% fastcomments user=some_user %}.

Every widget has its own tag. All of them accept **extra keyword arguments, 이는 위젯 구성에 그대로 병합되며 (camelCase 키 사용) 아래에 명시된 명명된 인수로 다루어지지 않는 모든 경우에 적용됩니다.

명명된 인수는 위젯의 camelCase 구성 키에 매핑됩니다:

예시:

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

{# 협업 채팅이 페이지의 기존 요소에 연결됩니다 #}
<article id="post-body">...</article>
{% fastcomments_collab_chat target="#post-body" %}

{# 일괄 카운트: 마커를 배치한 뒤 일괄 로더가 모두 채웁니다 #}
{% for post in posts %}
    <a href="\{{ post.url }}">\{{ post.title }}</a>
    {% fastcomments_count_marker url_id=post.url_id %}
{% endfor %}
{% fastcomments_comment_count_bulk %}

settings.py에서 SSO를 활성화하고 모드를 선택하세요. Secure SSO는 API 시크릿을 사용하여 HMAC-SHA256으로 서버 측에서 사용자를 서명하며, 권장됩니다.

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는 현재 사용자를 위해 {% 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보다 높은 우선순위를 가지는 두 가지 옵션이 있습니다:

• 사용자 모델의 메서드 (인터페이스의 Python적 유사체):

  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] 추가 기능이 설치된 경우, SDK를 통해 FastComments REST API를 호출하십시오,
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를 EU로 라우팅합니다:

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

fastcomments/widget.html을 자신의 복사본을 더 먼저 배치하여 재정의합니다 템플릿 검색 경로 (프로젝트 templates/fastcomments/widget.html). 이것은 Laravel의 vendor:publish --tag=fastcomments-views에 해당하는 Django 유사 기능입니다.

실행 가능한 쇼케이스가 example/에 있습니다: 좌측 레일 + 메인 스테이지 구성의 앱으로, 위젯별 페이지와 사전 시드된 데모 사용자 목록을 보여주는 로그인 페이지가 있습니다. 이 사용자 중 누구로든 로그인하면 댓글 및 라이브 채팅 위젯이 Secure SSO를 통해 해당 신원을 인증합니다. 해당 디렉터리에서:

python manage.py migrate
# Secure SSO가 작동하는 모습을 보려면 자신의 테넌트를 사용하세요 (API 시크릿이 이를 활성화합니다):
FASTCOMMENTS_TENANT_ID=... FASTCOMMENTS_API_KEY=... python manage.py runserver

API 시크릿이 없으면 공개 demo 테넌트(익명)로 폴백합니다. example/browser_smoke.py는 실제 브라우저에서 페이지를 로드하고 Secure-SSO 사용자로 댓글을 게시하는 Playwright e2e입니다.