Kirim pendaftaran dari formulir newsletter Anda sendiri ke beehiiv

Kirim formulir Anda sendiri ke Ikiform dan arahkan webhook ke relay yang memanggil endpoint create subscription beehiiv. Kirim double_opt_override: "on" agar beehiiv mengirim email konfirmasi, teruskan penempatan formulir sebagai utm_source dan halaman sebagai referring_site, dan biarkan reactivate_existing bernilai false agar pendaftaran tidak pernah diam-diam membatalkan unsubscribe. Satu panggilan API per pendaftaran, dengan key disimpan di relay.

Apa yang berbeda dengan beehiiv

API beehiiv disusun di sekitar publikasi. Subscription adalah alamat email yang berlangganan ke satu publikasi, dan Anda membuatnya dengan satu POST ke /v2/publications/{publicationId}/subscriptions. Semua hal tentang pendaftaran dibawa dalam satu request itu: apakah perlu konfirmasi, apakah mengirim email sambutan, dari mana pembaca berasal, dan custom field. Tidak ada langkah tag atau formulir terpisah seperti di Kit.

beehiiv juga melaporkan akuisisi dalam istilah UTM. Record subscription-nya membawa utm_source, utm_medium, utm_campaign, dan referring_site. Petakan field formulir Anda ke sana, dan setiap subscriber di beehiiv menampilkan penempatan dan artikel mana yang membawanya:

Siapkan beehiiv

1. Di beehiiv, buka Settings, lalu API di bawah Workspace Settings, dan pilih Create New API Key. Salin segera; beehiiv tidak akan menampilkannya lagi.
2. Di paket berbayar, batasi key ke satu publikasi yang diisi formulir. Key yang dibatasi ke publikasi mendapat 404 untuk publikasi lain, yang membatasi kerusakan jika bocor.
3. Temukan ID publikasi, ID berawalan yang dipakai API beehiiv di path. Endpoint list publications di API mengembalikannya.
4. Buat custom field bernama First Name jika Anda ingin menyimpan nama depan. beehiiv membuang custom field yang belum ada.
5. Siapkan email double opt-in dan email sambutan di pengaturan publikasi. Relay mengaktifkannya per request; isinya ada di beehiiv.

Relay

Ini adalah Netlify Function, yang cocok untuk situs yang sudah di Netlify: berjalan di domain Anda sendiri, di samping situs statis, tanpa layanan terpisah. Instal @netlify/functions untuk tipenya, dan atur ketiga variabel di pengaturan environment situs.

import type { Config } from "@netlify/functions";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export default async (request: Request) => {
  const payload = await request.text();
  let event;
  try {
    event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: Netlify.env.get("IKIFORM_WEBHOOK_SECRET")!,
    });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  if (event.type !== "submission.created") return new Response(null, { status: 204 });

  const { email, first_name, consent, source } = event.data.fields;
  if (consent !== true || typeof email !== "string") return new Response("Skipped", { status: 200 });

  const publication = Netlify.env.get("BEEHIIV_PUBLICATION_ID");
  const answer = await fetch(`https://api.beehiiv.com/v2/publications/${publication}/subscriptions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${Netlify.env.get("BEEHIIV_API_KEY")}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email,
      double_opt_override: "on",
      send_welcome_email: true,
      reactivate_existing: false,
      utm_source: typeof source === "string" ? source : "website",
      utm_medium: "signup_form",
      referring_site: event.data.meta.referrer ?? undefined,
      custom_fields: typeof first_name === "string" && first_name ? [{ name: "First Name", value: first_name }] : [],
    }),
  });

  if (answer.status === 429) {
    const reset = Number(answer.headers.get("ratelimit-reset"));
    const wait = reset ? Math.max(1, reset - Math.floor(Date.now() / 1000)) : 60;
    return new Response("beehiiv rate limit", { status: 503, headers: { "retry-after": String(wait) } });
  }
  if (!answer.ok) return new Response(`beehiiv answered ${answer.status}: ${await answer.text()}`, { status: 502 });
  return new Response(null, { status: 204 });
};

export const config: Config = {
  path: "/hooks/beehiiv",
};

• double_opt_override: "on" mengirim email konfirmasi apa pun default publikasinya. Gunakan "not_set" untuk mengikuti pengaturan publikasi, dan jangan pernah "off" untuk formulir publik.
• send_welcome_email default-nya false di API. Atur ke true jika Anda ingin pendaftaran API mendapat email sambutan yang didapat pendaftaran dari embed.
• reactivate_existing: false juga merupakan default. Tuliskan secara eksplisit agar tidak ada yang mengubahnya nanti tanpa berpikir; nilai itu mengaktifkan kembali orang yang sudah unsubscribe.
• beehiiv menjawab 200 dengan subscription-nya, dan status-nya dimulai sebagai validating selama beehiiv memeriksa alamat, lalu pending sampai pembaca mengonfirmasi.
• Pada 429, relay membaca RateLimit-Reset dari beehiiv, berupa waktu Unix, dan mengubahnya menjadi jeda Retry-After untuk Ikiform.

URL function-nya adalah https://your-site.com/hooks/beehiiv. Tambahkan di Webhooks di Ikiform dan salin secret whsec_ ke IKIFORM_WEBHOOK_SECRET. Dokumentasi webhook mendaftar aturan URL, dan server Anda sendiri menunjukkan cara melewati pengiriman yang sudah Anda tangani.

Memilih nilai UTM

Field UTM beehiiv berupa teks bebas, jadi tentukan nilainya sekali dan jaga konsistensinya, atau record terpecah menjadi hampir-duplikat seperti footer dan Footer. Input tersembunyi source milik formulir adalah utm_source yang alami. Jaga utm_medium tetap, agar setiap pendaftaran dari formulir Anda sendiri bisa dibedakan dari halaman hosted beehiiv dan dari impor:

Jika Anda menjalankan kampanye yang menautkan ke halaman berisi formulir, baca kampanye dari URL halaman di relay. meta.referrer berisi URL lengkap halaman, termasuk query string jika browser mengirimnya, jadi relay bisa menyalin parameter utm_campaign dari sana ke request.

Rate limit per paket

beehiiv mengukur batasnya per API key dalam jendela tetap 60 detik, dan batasnya bergantung pada paket. Setiap pendaftaran adalah satu request:

Tiga puluh per menit cukup untuk sebagian besar formulir footer, tetapi artikel peluncuran di publikasi gratis bisa melewatinya. 503 dari relay membuat Ikiform menunggu dan mencoba ulang alih-alih membuang pendaftaran. Nama paket dan batasnya bisa berubah, jadi periksa halaman rate limiting beehiiv jika paket Anda tidak tercantum.

Hal yang sering menjebak

• Nama custom field harus persis. beehiiv mencocokkan custom field berdasarkan nama dan membuang yang tidak dikenal dengan peringatan di respons, bukan error. Salah ketik berarti nama depan hilang tanpa suara.
• referring_site bisa kosong. meta.referrer bernilai null saat browser tidak mengirim referrer, dan relay tidak menyertakan field itu.
• Subscriber yang sudah ada. Dokumentasi beehiiv menyatakan panggilan ini membuat atau memperbarui subscription, tetapi tidak menyebutkan apa yang berubah untuk subscriber aktif. Uji dengan alamat terkonfirmasi milik Anda sebelum memasang formulir di setiap halaman.
• Key berlaku untuk seluruh workspace secara default. Key tanpa pembatasan publikasi bisa menjangkau setiap publikasi di workspace. Batasi cakupannya.
• Tier berbayar tetap di beehiiv. Jangan sertakan tier agar pendaftaran bergabung tanpa langganan berbayar. Upgrade terjadi di checkout beehiiv sendiri.

Pastikan berfungsi

1. Pilih Send test di endpoint di Ikiform. Pengiriman menampilkan 204 dan beehiiv tidak menerima request.
2. Berlangganan dari halaman Anda dengan alamat milik Anda. Pengiriman menampilkan 204.
3. Di beehiiv, subscriber muncul sebagai pending, dengan penempatan Anda sebagai UTM source dan artikelnya sebagai referring site.
4. Email double opt-in tiba. Konfirmasi, lalu email sambutan menyusul.
5. Unsubscribe alamat itu di beehiiv lalu daftar lagi. Subscriber tetap inactive, karena reactivate_existing bernilai false.

Pertanyaan