Προσθήκη ζωντανής σχολιασμού στις εφαρμογές Val Town

Val Town εκτελεί TypeScript στο Deno, έτσι ένα val είναι ένας πραγματικός διακομιστής. Αυτό το καθιστά κατάλληλο για το FastComments: το widget είναι μια ετικέτα script στη σελίδα, και οτιδήποτε χρειάζεται ένα μυστικό, όπως Secure SSO ή η επαλήθευση ενός webhook, μπορεί να εκτελεστεί στο διακομιστή στο ίδιο val.

Αυτός ο οδηγός καλύπτει την προσθήκη του widget σχολίων σε ένα HTTP val, την εμφάνιση του αριθμού σχολίων σε μια σελίδα ευρετηρίου, τη σύνδεση χρηστών με τον λογαριασμό Val Town που ήδη έχουν, και τη λήψη webhook σχολίων.

Δεν χρειάζεστε λογαριασμό για να το δοκιμάσετε. Τα παραδείγματα χρησιμοποιούν tenantId: "demo", ένα κοινόχρηστο sandbox, και το Βήμα 2 καλύπτει τη μετάβαση στο δικό σας.

Βήμα 1: Προσθήκη του widget

Το widget είναι μια ετικέτα script και ένα στοιχείο container, έτσι ενσωματώνεται σε ό,τι ήδη αποδίδει το val σας. Αυτό το παράδειγμα χρησιμοποιεί Hono JSX, το οποίο είναι αυτό που χρησιμοποιούν τα HTTP templates του Val Town.

Widget σχολίων σε ένα HTTP val

Copy

Run

/** @jsxImportSource npm:hono@4/jsx */
import { Hono } from "npm:hono@4";
const app = new Hono();
app.get("/:slug", (c) => {
  const slug = c.req.param("slug");
  const url = new URL(c.req.path, c.req.url).toString();
  const config = JSON.stringify({
    tenantId: "demo",
    urlId: slug,
    url,
  });
  return c.html(
    <html>
      <body>
        <h1>{slug}</h1>
        <div id="fastcomments-widget"></div>
        <script src="https://cdn.fastcomments.com/js/embed-v2.min.js"></script>
        <script
          dangerouslySetInnerHTML={{
            __html:
              `window.FastCommentsUI(document.getElementById("fastcomments-widget"), ${config});`,
          }}
        />
      </body>
    </html>,
  );
});
export default app.fetch;

Επιλέξτε ένα urlId πριν το εκδώσετε

urlId καθορίζει σε ποιο νήμα θα τοποθετηθεί ένα σχόλιο. Αν το αφήσετε ακαθορισμένο, προεπιλέγεται μια καθαρισμένη έκδοση του τρέχοντος URL της σελίδας, που είναι ακριβώς το στοιχείο που αλλάζει στο Val Town: ένα val έχει ένα μακρύ hostname *.web.val.run μέχρι να διεκδικήσετε ένα υποτομέα, τα κλαδιά παίρνουν τα δικά τους URL και η μετονομασία μιας σελίδας αλλάζει τη διαδρομή. Κάθε παραλλαγή γίνεται σιωπηρά ένα ξεχωριστό, κενό νήμα, και το σύμπτωμα εμφανίζεται ως «τα σχόλιά μου εξαφανίστηκαν».

Ορίστε το σε κάτι σταθερό που ελέγχετε, όπως το slug της ανάρτησης ή ένα αναγνωριστικό βάσης δεδομένων, όπως παραπάνω. Περνάτε επίσης το url, ώστε τα email ειδοποιήσεων και τα εργαλεία διαχείρισης να μπορούν να συνδέονται πίσω στη πραγματική σελίδα.

Διατήρηση σχολίων χωρίς JavaScript

Το FastComments αποδίδει ένα πλήρες νήμα διακομιστή, το οποίο ένα val μπορεί να ενσωματώσει σε ένα μπλοκ <noscript>:

Εναλλακτική λύση χωρίς JavaScript

Copy

Run

<noscript>
  <iframe src="https://fastcomments.com/ssr/comments?tenantId=demo&urlId=POST_SLUG&url=PAGE_URL"
          title="FastComments" width="100%" height="1500px" frameborder="0"
          style="width: 1px !important; min-width: 100% !important; border: none !important;"></iframe>
</noscript>

Κωδικοποιήστε τις παραμέτρους σε URL. Η έκδοση διακομιστή υποστηρίζει ανώνυμη και συνδεδεμένη σχολιασμό, SSO, και ένθετες απαντήσεις.

Βήμα 2: Χρησιμοποιήστε το δικό σας λογαριασμό

tenantId: "demo" είναι ένα κοινό δημόσιο sandbox. Λειτουργεί χωρίς εγγραφή, γι' αυτό τα παραδείγματα το χρησιμοποιούν, αλλά όλοι οι άλλοι που δοκιμάζουν το FastComments γράφουν στα ίδια νήματα και οποιοσδήποτε μπορεί να τα συντονίσει. Αλλάξτε το πριν δημοσιεύσετε οτιδήποτε σας ενδιαφέρει.

Το tenant ID σας βρίσκεται στη σελίδα μυστικού API.

Ένα tenant ID είναι δημόσιο και ανήκει στον κώδικα του προγράμματος περιήγησης. Ένα μυστικό API δεν είναι, και τίποτα σε αυτή τη σελίδα δεν χρειάζεται ένα.

Διαβάστε το από μεταβλητή περιβάλλοντος

Τα vals του Val Town είναι δημόσια στην δωρεάν έκδοση, έτσι η πηγή τους είναι αναγνώσιμη από όλους. Κρατήστε οτιδήποτε ευαίσθητο σε μεταβλητές περιβάλλοντος, διαβάζοντας με Deno.env.get:

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Μόνο λογαριασμοί που δημιουργήθηκαν στο eu.fastcomments.com ορίζουν αυτό σε "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

Αυτό έχει μεγαλύτερη σημασία από το συνηθισμένο στο Val Town για έναν δεύτερο λόγο: η επανασύνθεση ενός val αντιγράφει τα κλειδιά των μεταβλητών περιβάλλοντος, αλλά όχι τις τιμές τους. Ένα μυστικό που διατηρείται σε μεταβλητή περιβάλλοντος δεν ακολουθεί το val σας σε λογαριασμό κάποιου άλλου. Ένα μυστικό γραμμένο σε αρχείο το κάνει.

Η επιστροφή στην τιμή "demo" διατηρεί το val λειτουργικό για όποιον το επανασυνθέσει πριν ορίσει το δικό του tenant.

EU λογαριασμοί

Ένας λογαριασμός, τα δεδομένα του και τα κλειδιά του ζουν σε μία περιοχή. Αν ο δικός σας δημιουργήθηκε στο eu.fastcomments.com, κάθε ρύθμιση widget χρειάζεται επίσης region: "eu", και τα scripts φορτώνουν από cdn-eu.fastcomments.com. Διαφορετικά αφήστε και τα δύο όπως είναι.

Πλήθος σχολίων σε σελίδα ευρετηρίου

Σε μια σελίδα ευρετηρίου, μην αποδίδετε ένα widget καταμέτρησης σχολίων ανά γραμμή. Αυτό σημαίνει ένα αίτημα ανά ανάρτηση. Χρησιμοποιήστε τη μαζική μέτρηση, η οποία απαιτεί ένα μόνο αίτημα για ολόκληρη τη σελίδα.

Σημειώστε κάθε γραμμή με το urlId που χρησιμοποιεί το νήμα της, και στη συνέχεια φορτώστε το μαζικό widget μία φορά:

Μαζικές μετρήσεις σχολίων σε ευρετήριο

Copy

Run

<ul>
  {posts.map((post) => (
    <li>
      <a href={post.slug}>{post.title}</a>{" "}
      <span class="fast-comments-count" data-fast-comments-url-id={post.slug}></span>
    </li>
  ))}
</ul>
<script
  dangerouslySetInnerHTML={{
    __html: `window.FastCommentsBulkCountConfig = ${
      JSON.stringify({ tenantId: TENANT_ID })
    };`,
  }}
/>
<script src="https://cdn.fastcomments.com/js/embed-widget-comment-count-bulk.min.js"></script>

Το script εντοπίζει κάθε στοιχείο .fast-comments-count στη σελίδα και γεμίζει τη μέτρησή του.

data-fast-comments-url-id πρέπει να ταιριάζει με το urlId που χρησιμοποιεί το widget σχολίων της ανάρτησης. Εάν το widget χρησιμοποιεί το slug, ο δείκτης χρησιμοποιεί το slug. Μια ασυμφωνία εμφανίζει μηδέν σε ένα νήμα που έχει σχόλια.

Το script ελέγχει περιοδικά το window.FastCommentsBulkCountConfig, επομένως δεν έχει σημασία αν ορίσετε τη διαμόρφωση πριν ή μετά το στοιχείο script.

Ασφαλής SSO με std/oauth

Αν το val σας γνωρίζει ήδη ποιος είναι ο επισκέπτης, το Secure SSO μεταφέρει αυτή την ταυτότητα στο widget ώστε να μη δει ποτέ δεύτερη σύνδεση. Δεν υπάρχουν endpoints προς κατασκευή και τίποτα προς κλήση κατά την εκτέλεση: υπολογίζετε τρεις τιμές server-side και τις περνάτε στη διαμόρφωση του widget.

Το Val Town προσφέρει σύνδεση χωρίς διαμόρφωση με το std/oauth, ώστε ο επισκέπτης να συνδεθεί με τον λογαριασμό Val Town που ήδη έχει. Αντικαταστήστε το με ό,τι χρησιμοποιεί η εφαρμογή σας· το κομμάτι του FastComments δεν αλλάζει.

Κατασκευάστε το payload στον server

Το API secret υπογράφει το payload και δεν πρέπει ποτέ να φτάσει σε κώδικα browser. Εγκαταστήστε το SDK από το npm, που λειτουργεί ως έχει στο Deno runtime του Val Town:

sso.ts

Copy

Run

import { SecureSSOPayloadBuilder } from "npm:fastcomments-sdk/server";
export function buildSSOPayload(user) {
  // Το id πρέπει να είναι σταθερό για το ίδιο άτομο, αλλιώς παίρνει νέα ταυτότητα σχολίων σε κάθε σύνδεση.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // Το email είναι υποχρεωτικό και πρέπει να είναι μοναδικό.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // Το username είναι υποχρεωτικό και δεν μπορεί να είναι email.
    username: user.username ?? id,
    displayName: user.username ?? undefined,
    avatar: user.links.profileImageUrl ?? undefined,
  }).getPayload();
}

Το getPayload() επιστρέφει { userDataJSONBase64, verificationHash, timestamp }. Αυτές οι τρεις τιμές είναι το μόνο που φτάνει στον browser. Το secret τις υπογράφει και στη συνέχεια απορρίπτεται, ώστε τίποτα στη σελίδα να μην επιτρέπει σε έναν αναγνώστη να πλαστογραφήσει διαφορετικό χρήστη.

Widget config with SSO

Copy

Run

import { getOAuthUserData, oauthMiddleware } from "https://esm.town/v/std/oauth/middleware.ts";
app.get("/", async (c) => {
  const session = await getOAuthUserData(c.req.raw);
  const user = session?.user;
  const config = {
    tenantId: TENANT_ID,
    urlId: "my-thread",
    ...(user
      ? { sso: { ...buildSSOPayload(user), logoutURL: "/logout" } }
      : { sso: { loginURL: "/auth/login" } }),
  };
  // ...αποδώστε το widget με αυτή τη διαμόρφωση
});
export default oauthMiddleware(app.fetch);

Το oauthMiddleware προσθέτει για εσάς τα GET /auth/login, GET /auth/callback και POST /auth/logout. Σημειώστε ότι το logout είναι POST, ενώ το widget πλοηγείται στο logoutURL με GET, οπότε δείξτε το logoutURL σε ένα μικρό δικό σας route που υποβάλλει το POST.

Όταν ο επισκέπτης είναι αποσυνδεδεμένος, περάστε το sso με μόνο ένα loginURL. Το widget τότε εμφανίζει προτροπή σύνδεσης αντί για ανώνυμο πλαίσιο σχολίων.

Πράγματα που πηγαίνουν στραβά

Το timestamp είναι σε epoch milliseconds, δεν πρέπει να είναι στο μέλλον και δεν πρέπει να είναι παλαιότερο από δύο ημέρες. Δημιουργήστε το στον server στο ίδιο request που υπολογίζει το hash. Η δημιουργία του στον browser είναι η κλασική αποτυχία: η τιμή διαφέρει από αυτή που υπογράφηκε και κάθε σχόλιο απορρίπτεται.

Ποτέ μην ορίζετε isAdmin ή isModerator από τον πάροχο ταυτότητας. Η σύνδεση με λογαριασμό Val Town δεν λέει τίποτα για το ποιος πρέπει να συντονίζει τον ιστότοπό σας.

Δείτε τον οδηγό SSO για την πλήρη λίστα πεδίων, τα threads με περιορισμό ομάδας και τα badges.

Λήψη webhooks

A val είναι ένας φυσικός δέκτης webhook: διαθέτει σταθερό URL, μπορεί να επαληθεύσει μια υπογραφή και έχει ενσωματωμένη αποθήκευση SQLite και blob.

FastComments υπογράφει ${timestamp}.${body} με το μυστικό API του λογαριασμού σας και στέλνει δύο κεφαλίδες:

Κεφαλίδες Webhook

Copy

Run

X-FastComments-Timestamp: 1789004710        unix seconds, not milliseconds
X-FastComments-Signature: sha256=<hex>

Η μέθοδος μεταφέρει το γεγονός: PUT για ένα δημιουργημένο ή ενημερωμένο σχόλιο, DELETE για ένα διαγραμμένο.

Επαλήθευση παράδοσης

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // The exact bytes that arrived. Do NOT use c.req.json() and re-serialize.
  const rawBody = await c.req.raw.text();
  const timestamp = c.req.raw.headers.get("X-FastComments-Timestamp");
  const signature = c.req.raw.headers.get("X-FastComments-Signature");
  if (!timestamp || !signature) return new Response("Missing headers", { status: 400 });
  // Reject stale deliveries so a captured request cannot be replayed later.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) {
    return new Response("Timestamp outside window", { status: 400 });
  }
  const expected = "sha256=" + createHmac("sha256", Deno.env.get("FASTCOMMENTS_API_SECRET"))
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const a = new TextEncoder().encode(signature);
  const b = new TextEncoder().encode(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return new Response("Signature mismatch", { status: 401 });
  }
  // ...handle JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Δύο πράγματα που προκαλούν προβλήματα

Επαληθεύστε τα ακατέργαστα byte. Η ανάλυση του JSON και η επανα-σειριοποίησή του αλλάζει τη σειρά των κλειδιών και τα κενά, έτσι το hash διαφέρει και κάθε παράδοση αποτυγχάνει χωρίς προφανή λόγο. Αυτό είναι ο συνηθισμένος λόγος που ένας δέκτης webhook «απλώς δεν λειτουργεί».

Συγκρίνετε σε σταθερό χρόνο. Ένα απλό === στην υπογραφή διαρρέει πόσα byte ταιριάζουν, κάτι που αρκεί για να παραχθεί ένα byte τη φορά.

Διαχείριση συμβάντων

Απαντήστε γρήγορα. Το FastComments κάνει επανεγγραφές σε μη-2xx απαντήσεις, και ένα endpoint που συνεχίζει να αποτυγχάνει απενεργοποιείται αυτόματα μετά από κάποιο χρόνο, επομένως εκτελέστε την πραγματική εργασία μετά την απάντηση αντί εντός της απάντησης.

Κάντε αυτή τη λειτουργία αμετάβλητη (idempotent) με βάση το αναγνωριστικό του σχολίου. Μια επανεγγραφή υπογράφεται ξανά με νέο χρονικό σήμα, και το ίδιο αναγνωριστικό σχολίου φτάνει ξανά σε επεξεργασία και διαγραφή, οπότε δεν υπάρχει κάτι σταθερό για απο-διπλοεγγραφή.

Παραδείγματα Vals

Τέσσερα δημόσια vals που μπορείτε να κάνετε remix, το καθένα καλύπτει ένα κομμάτι αυτού του οδηγού.

Blog with comments (live) είναι ένα blog σε Markdown με ένα νήμα σχολίων κάτω από κάθε ανάρτηση και μαζικά μετρητικά σχολίων στην ευρετήρια σελίδα. Λειτουργεί αμέσως μετά το remix, και μία μεταβλητή περιβάλλοντος το δείχνει στον δικό σας λογαριασμό.

SSO demo (live) συνδέει τον επισκέπτη με τον λογαριασμό Val Town του και μεταφέρει αυτήν την ταυτότητα στο widget, ώστε να μην χρειάζεται δεύτερη σύνδεση.

Webhook receiver (live) επαληθεύει την υπογραφή HMAC σε κάθε παράδοση και αποθηκεύει τα γεγονότα σε SQLite. Διαθέτει ένα κουμπί που υπογράφει ένα δοκιμαστικό payload και το παραδίδει στον εαυτό του, ώστε να δείτε την επαλήθευση να succeeds πριν ρυθμίσετε ένα πραγματικό webhook.

Agent skills (live) είναι μια βιβλιοθήκη δεξιοτήτων agent του FastComments που καλύπτουν το widget, το SSO, το REST API, τον συντονισμό (moderation) και τη μετάβαση από το Disqus. Κάντε το remix και ο agent του Val Town, Townie, τις ανακαλύπτει αυτόματα από το skills/, ώστε ο agent σας να ξέρει πώς να συνδέσει τα σχόλια χωρίς να επικολλάτε τεκμηρίωση στη συνομιλία.

Οι ίδιες δεξιότητες εγκαθίστανται οπουδήποτε αλλού με npx skills add fastcomments/skills.

Σφάλματα τομέα

Μόλις απενεργοποιήσετε τον ενοικιαστή demo, το widget ενδέχεται να αρνηθεί τη φόρτωση με σφάλμα εξουσιοδότησης. Αυτό συμβαίνει επειδή η FastComments δεν γνωρίζει ότι πρέπει να επιτρέπει τη χρήση του λογαριασμού σας σε αυτόν τον τομέα.

Μεταβείτε εδώ για να προσθέσετε τον ιστότοπό σας στον λογαριασμό σας.

Το Val Town αξίζει μια δεύτερη ματιά εδώ, επειδή ένα val μπορεί να είναι προσβάσιμο από περισσότερα από ένα ονόματα κεντρικού υπολογιστή:

Κάθε HTTP val έχει ένα μακρύ προεπιλεγμένο endpoint, <org>--<id>.web.val.run.
Η κατοχύρωση ενός προσαρμοσμένου υποτομέα προσθέτει <name>.val.run.
Ένας προσαρμοσμένος τομέας προσθέτει έναν τρίτο.
Τα κλαδιά λαμβάνουν τις δικές τους διευθύνσεις URL.

Προσθέστε τα ονόματα κεντρικού υπολογιστή από τα οποία εξυπηρετείτε πραγματικά το widget. Εάν καταχωρήσετε έναν υποτομέα μετά τη ρύθμιση, προσθέστε και αυτόν, διαφορετικά το widget θα λειτουργεί στη παλιά διεύθυνση URL και θα αποτυγχάνει στη νέα.

Προσθήκη δημοσκοπήσεων στην εφαρμογή Val Town

Μόλις το FastComments είναι στην εφαρμογή Val Town, μπορείτε επίσης να εκτελείτε ζωντανές δημοσκοπήσεις απευθείας στα σχόλια. Ενεργοποιήστε Enable Polls στις ρυθμίσεις προσαρμογής widget και ένα κουμπί δημοσκόπησης εμφανίζεται στη γραμμή εργαλείων σχολίων. Οι δημοσκοπήσεις δέχονται 2 έως 10 επιλογές, τα αποτελέσματα ενημερώνονται ζωντανά για όλους στη σελίδα, και εσείς επιλέγετε ποιος μπορεί να δημιουργεί δημοσκοπήσεις και αν η ψήφος απαιτεί σύνδεση. Δεν υπάρχει κάτι άλλο να εγκαταστήσετε στο Val Town.

Try the Live Polls demo ή διαβάστε την Polls documentation για να τις ρυθμίσετε.

Εγκατάσταση Val Town

Δημοσκοπήσεις

Προσθήκη ζωντανής σχολιασμού στις εφαρμογές Val Town

Βήμα 1: Προσθήκη του widget

Επιλέξτε ένα urlId πριν το εκδώσετε

Διατήρηση σχολίων χωρίς JavaScript

Βήμα 2: Χρησιμοποιήστε το δικό σας λογαριασμό

Διαβάστε το από μεταβλητή περιβάλλοντος

EU λογαριασμοί

Πλήθος σχολίων σε σελίδα ευρετηρίου

Ασφαλής SSO με std/oauth

Κατασκευάστε το payload στον server

Περάστε το στο widget

Πράγματα που πηγαίνουν στραβά

Λήψη webhooks

Δύο πράγματα που προκαλούν προβλήματα

Διαχείριση συμβάντων

Παραδείγματα Vals

Σφάλματα τομέα

Προσθήκη δημοσκοπήσεων στην εφαρμογή Val Town

Γλώσσα 🇬🇷 Ελληνικά

Εγκατάσταση Val Town

Δημοσκοπήσεις

Προσθήκη ζωντανής σχολιασμού στις εφαρμογές Val Town

Βήμα 1: Προσθήκη του widget

Επιλέξτε ένα urlId πριν το εκδώσετε

Διατήρηση σχολίων χωρίς JavaScript

Βήμα 2: Χρησιμοποιήστε το δικό σας λογαριασμό

Διαβάστε το από μεταβλητή περιβάλλοντος

EU λογαριασμοί

Πλήθος σχολίων σε σελίδα ευρετηρίου

Ασφαλής SSO με std/oauth

Κατασκευάστε το payload στον server

Περάστε το στο widget

Πράγματα που πηγαίνουν στραβά

Λήψη webhooks

Δύο πράγματα που προκαλούν προβλήματα

Διαχείριση συμβάντων

Παραδείγματα Vals

Σφάλματα τομέα

Προσθήκη δημοσκοπήσεων στην εφαρμογή Val Town

Επιλέξτε ένα urlId πριν το εκδώσετε