Arsitektur Dokumentasi

Endpoint PUBLIK untuk merekam satu kunjungan pada posting yang diterbitkan dari halaman posting blog Anda.

Endpoint

• :id — (param path, wajib) UUID Posting.

Autentikasi

Ini adalah endpoint PUBLIK. Autentikasi dengan model kunci API, identik dengan endpoint publik lainnya:

• Authorization: Bearer *** atau X-API-Key: ***
• X-Workspace-ID: <workspace_id> atau workspace diidentifikasi melalui subdomain.

⚠️ Ini adalah SATU-SATUNYA endpoint analitik publik. Segala sesuatu yang lain dalam analitik (dashboard) hanya untuk admin.

Permintaan

Tidak diperlukan badan permintaan. Server memperoleh semua yang dibutuhkan dari metadata permintaan:

• Header Referer → sumber pengarah
• Header User-Agent → info perangkat/browser
• IP Klien → di-hash dengan sha256 + garam statis

Ini ramah privasi: tanpa cookie, tanpa sidik jari, dan IP tidak pernah disimpan mentah — hanya hash yang diberi garam.

Respons

{
  "status": 200,
  "message": "ok"
}

Contoh cURL

curl -X POST "https://YOUR_HOST/v1/analytics/view/9f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Referer: https://yourblog.com/my-post" \
  -H "User-Agent: Mozilla/5.0 (compatible; YourBot/1.0)"

Integrasi Klien

Panggil ini dari halaman posting blog Anda (mis. saat mount / pageview) untuk melacak tampilan.

🔐 Peringatan keamanan: kunci API harus tetap di sisi server. Jika Anda mengirim permintaan ini langsung dari browser, kunci akan terekspos di bundel klien. Pilih rute server kecil atau beacon sisi server yang memproksi panggilan sehingga kunci tidak pernah dikirim ke klien.

Direkomendasikan: Proksi sisi server (Node/TS)

Rute server kecil yang menjaga kunci tetap di luar klien:

// pages/api/view.ts  (atau rute server framework Anda)
import type { NextApiRequest, NextApiResponse } from "next";

const TULIS_API = "https://YOUR_HOST";
const API_KEY = process.env.TULIS_API_KEY!; // hanya server
const WORKSPACE_ID = process.env.TULIS_WORKSPACE_ID!;

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const postId = req.query.id as string;

  const r = await fetch(`${TULIS_API}/v1/analytics/view/${postId}`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "X-Workspace-ID": WORKSPACE_ID,
      "Referer": req.headers.referer || "",
      "User-Agent": req.headers["user-agent"] || "",
    },
  });

  res.status(r.status).json(await r.json());
}

Beacon klien (memanggil proksi Anda, bukan kunci)

// fire-and-forget saat posting dimuat
useEffect(() => {
  navigator.sendBeacon(`/api/view?id=${postId}`);
}, [postId]);

Jika Anda harus memanggil dari sisi klien (TIDAK direkomendasikan)

Memanggil endpoint publik langsung dari browser mengekspos YOUR_API_KEY kepada siapa pun yang memeriksa halaman. Hanya lakukan ini dengan kunci terbatas dan berscope dan jangan pernah dengan kunci berizin penuh.

// ⚠️ mengekspos YOUR_API_KEY di browser — hindari di produksi
fetch(`https://YOUR_HOST/v1/analytics/view/${postId}`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer YOUR_API_KEY`,
    "X-Workspace-ID": `YOUR_WORKSPACE_ID`,
  },
});