Django 앱에 댓글 추가

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

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"],   # 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를 신중하게 선택하십시오. 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 %}에 자동으로 주입됩니다.

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

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 유사 기능입니다.

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
# 자체 테넌트를 사용하여 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.