Buat widget feedback mengambang untuk aplikasi React Anda

Render tombol fixed yang membuka panel berbasis Popover API browser, sehingga panel berada di atas setiap lapisan aplikasi Anda tanpa perang z-index dan tertutup saat Escape ditekan. Saat submit, tambahkan route saat ini, versi aplikasi, ID akun, dan viewport ke data formulir, lalu kirim dari browser dengan Ikiform SDK. Kirim email pengguna hanya jika mereka mencentang kotak yang meminta balasan.

Apa yang berbeda dari widget dalam aplikasi

Formulir di halaman menunggu orang menggulir ke sana. Widget ada di setiap layar, yang mengubah apa saja yang bisa salah. Widget harus berada di atas modal, menu, dan toast Anda sendiri. Widget tidak boleh kehilangan pesan yang setengah ditulis saat seseorang mengklik di luarnya. Dan karena pengguna sudah login, Anda sudah tahu siapa mereka dan di mana mereka berada, jadi widget sebaiknya mengirim informasi itu alih-alih menanyakannya.

Field untuk aplikasi

Komponennya

Komponen ini butuh @ikiform/sdk dan React 19, yang punya tipe untuk popover, popoverTarget, dan event toggle. popoverTarget pada tombol mengikatnya ke panel, sehingga browser menangani pembukaan, Escape, dan pengembalian fokus ke tombol.

import { submit } from "@ikiform/sdk";
import { type FormEvent, type ToggleEvent, useId, useRef, useState } from "react";
import "./feedback-widget.css";

const FORM_ID = "frm_xxxxxxxxxxxxxxxx";
const FACES = ["Awful", "Bad", "Okay", "Good", "Great"];

interface Props {
  accountId: string;
  email: string;
  appVersion: string;
}

export function FeedbackWidget({ accountId, email, appVersion }: Props) {
  const panelId = useId();
  const attempt = useRef("");
  const [status, setStatus] = useState<"idle" | "sending" | "sent">("idle");
  const [error, setError] = useState("");

  function onToggle(event: ToggleEvent<HTMLDivElement>) {
    if (event.newState !== "open") return;
    attempt.current = crypto.randomUUID();
    if (status === "sent") setStatus("idle");
  }

  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    if (data.get("may_reply") === "true") data.set("email", email);
    data.set("route", window.location.pathname);
    data.set("app_version", appVersion);
    data.set("account_id", accountId);
    data.set("viewport", `${window.innerWidth}x${window.innerHeight}`);
    setStatus("sending");
    setError("");
    const result = await submit(FORM_ID, data, { idempotencyKey: attempt.current });
    if (result.ok) {
      setStatus("sent");
      return;
    }
    setError(result.error.fields?.rating?.[0] ?? result.error.message);
    setStatus("idle");
  }

  return (
    <>
      <button type="button" className="feedback-trigger" popoverTarget={panelId}>
        Feedback
      </button>
      <div id={panelId} popover="auto" className="feedback-panel" onToggle={onToggle} aria-label="Send feedback">
        {status === "sent" ? (
          <p role="status">Thanks, that helps.</p>
        ) : (
          <form onSubmit={onSubmit}>
            <fieldset>
              <legend>How is it going?</legend>
              {FACES.map((face, index) => (
                <label key={face}>
                  <input type="radio" name="rating" value={index + 1} required /> {face}
                </label>
              ))}
            </fieldset>
            <label htmlFor={`${panelId}-message`}>Tell us more</label>
            <textarea id={`${panelId}-message`} name="message" rows={4} maxLength={4000} />
            <label>
              <input type="checkbox" name="may_reply" value="true" /> The team can reply to me by email
            </label>
            <input name="_gotcha" type="text" tabIndex={-1} autoComplete="off" hidden />
            {error ? <p role="alert">{error}</p> : null}
            <button disabled={status === "sending"}>{status === "sending" ? "Sending" : "Send"}</button>
          </form>
        )}
      </div>
    </>
  );
}

• popover="auto" menaruh panel di top layer saat terbuka. Panel tampil di atas dialog dan menu Anda tanpa z-index, dan tertutup saat pengguna mengklik di tempat lain.
• Child panel tetap ter-mount saat panel tersembunyi, sehingga draf selamat dari klik tak sengaja di luar. Setelah pengiriman berhasil, baris terima kasih menggantikan formulir, yang mengosongkannya, dan pembukaan berikutnya menampilkan formulir kosong.
• onToggle membuat key baru setiap kali panel dibuka. submit() mengirimnya sebagai header Idempotency-Key, jadi klik ganda hanya menyimpan satu jawaban. Lihat idempotensi.
• Email hanya diisi jika kotaknya dicentang. Jika tidak dicentang, jawaban membawa ID akun tetapi tanpa alamat.

Gaya default popover menaruhnya di tengah layar. Aturan ini menyematkannya di atas tombol:

.feedback-trigger {
  position: fixed;
  right: 16px;
  bottom: 16px;
}

.feedback-panel {
  inset: auto 16px 64px auto;
  margin: 0;
  width: min(360px, calc(100vw - 32px));
  max-height: calc(100dvh - 96px);
  overflow: auto;
}

Mount sekali saja

Render widget di layout yang membungkus layar untuk pengguna yang login, agar muncul di mana-mana dan tetap ada saat navigasi. Di App Router Next.js, layout adalah server component yang membaca sesi dan meneruskan props biasa ke widget klien:

import type { ReactNode } from "react";
import { FeedbackWidget } from "@/components/feedback-widget";
import { getSession } from "@/lib/session";

export default async function AppLayout({ children }: { children: ReactNode }) {
  const session = await getSession();
  return (
    <>
      {children}
      {session ? (
        <FeedbackWidget
          accountId={session.accountId}
          email={session.email}
          appVersion={process.env.NEXT_PUBLIC_APP_VERSION ?? "dev"}
        />
      ) : null}
    </>
  );
}

Tandai file widget dengan "use client" di App Router. Di aplikasi Vite atau React Router, render di samping router outlet Anda. Cara kerjanya sama.

Apa yang bisa dan tidak bisa dibuktikan browser

Widget ini mengirim langsung dari browser dengan ID publik formulir. Itu kompromi yang tepat untuk feedback: tidak ada server route yang perlu dirawat, dan meta.user_agent milik Ikiform adalah browser asli pengguna. Itu juga berarti siapa pun bisa mengirim account_id apa pun. Gunakan untuk mencari informasi, jangan pernah untuk memberikan akses apa pun.

Pastikan berfungsi

1. Di Allowed domains formulir, tambahkan domain situs Anda, ditambah localhost selama pengembangan. Biarkan kosong untuk menerima kiriman dari mana saja.
2. Buka panel, ketik catatan, klik di luar, lalu buka lagi. Catatannya masih ada.
3. Buka modal di aplikasi Anda, lalu widget. Panel tampil di atas modal.
4. Tekan Escape. Panel tertutup dan fokus kembali ke tombol Feedback.
5. Pilih wajah dan klik dua kali Kirim. Submissions menampilkan satu jawaban, dengan route, app_version, dan account_id terisi.
6. Kirim sekali dengan kotak balasan dicentang. Tombol Balas di email notifikasi menuju ke pengguna.

Hal yang sering menjebak

• Jauhkan tombol dari elemen mengambang Anda sendiri, seperti gelembung chat atau banner cookie. Pindahkan salah satunya, atau buka widget dari item menu sebagai gantinya.
• Jangan tampilkan tombol di setiap layar checkout atau editor tempat orang sedang berkonsentrasi. Sembunyikan di sana dengan prop.
• Popover API didukung di Chrome, Edge, Firefox, dan Safari versi terbaru. Jika Anda harus mendukung browser lama, periksa dulu sebelum mengandalkannya.
• Setiap field yang ditambahkan lewat kode harus ada di definisi formulir, atau Ikiform menolak kiriman dengan error Unknown field.
• Jangan kirim seluruh state aplikasi. Route, versi, akun, dan ukuran menjawab sebagian besar pertanyaan; selebihnya adalah soal privasi.

Pemecahan masalah

Pertanyaan