Next.js sohbet botu: next/script ile yapay zekâ sohbet botu ekleyin (App Router ve Pages Router)

• Bir Nexoply hesabı. Ücretsiz kaydolun: Ücretsiz plan ayda 50 konuşma içerir, kart gerekmez.
• Nexoply'de işletmenin bilgileri: hizmetler ve fiyatlar, SSS'ler, politikalar, çalışma saatleri ve hizmet bölgeleri. En hızlı yol, web sitesi adresini girip Nexoply'nin herkese açık sayfaları (JavaScript ile oluşturulan sayfalar dahil) içe aktarmasına izin vermektir; önerileri siz incelersiniz ve onaylamadan hiçbir şey eklenmez.
• Sohbet botu anahtarınız. Panelde Sohbet botu sayfasını açın (henüz yapmadıysanız Sohbet botu oluştur düğmesine tıklayın). Oradaki kurulum kodu, anahtarı data-chatbot özniteliğinde içerir.

Düz bir HTML sitesinde kurulum kodu doğrudan </body> öncesine yapıştırılırdı:

<script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>

Next.js'te HTML'i doğrudan düzenlemezsiniz; bu yüzden aynı betiği yerleşik next/script bileşeniyle eklersiniz. Anahtar herkese açıktır: yalnızca widget'a hangi işletmeye ait olduğunu söyler.

Kök düzen (root layout) her sayfayı sarar; betiği oraya eklemek sohbeti sitenin tamamına yerleştirir. Script'i next/script'ten içe aktarın ve <body> içine, {children} sonrasına koyun:

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Nexoply sohbet widget'ı: hydration sonrasında tarayıcıda yüklenir */}
        <Script
          src="https://nexoply.com/widget.js"
          data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Ardından anahtarı bir ortam değişkenine yazın. NEXT_PUBLIC_ öneki, Next.js'in değeri tarayıcı paketine dahil etmesini sağlar; anahtar gizli olmadığı için burada sakıncası yoktur:

# .env.local (git'e eklenmez)
NEXT_PUBLIC_NEXOPLY_KEY=YOUR-KEY

Pages Router'da pages/_app.tsx her sayfayı sarar; bu yüzden aynı <Script> oraya, <Component {...pageProps} /> yanına gelir. Aynı .env.local değişkenini kullanın:

// pages/_app.tsx
import type { AppProps } from "next/app";
import Script from "next/script";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://nexoply.com/widget.js"
        data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
        strategy="afterInteractive"
      />
    </>
  );
}

Projeniz iki yönlendiriciyi birlikte kullanıyorsa betiği hem app/layout.tsx hem de pages/_app.tsx dosyasına ekleyin. İki kez yüklenmesi zararsızdır: widget her sohbet botu anahtarı için yalnızca bir kez yerleşir.

React sohbet botu bileşeni rehberindeki gibi bir <Chatbot /> bileşeni mi tercih edersiniz? Script'i kendi dosyasına taşıyın. onLoad gibi olay işleyicileri aktarmadığınız sürece next/script Server Components içinde çalışır; bu yüzden bu dosyada "use client" gerekmez:

// components/Chatbot.tsx
import Script from "next/script";

export function Chatbot() {
  return (
    <Script
      src="https://nexoply.com/widget.js"
      data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
      strategy="afterInteractive"
    />
  );
}

Ardından <Chatbot /> bileşenini app/layout.tsx içinde <body> içine, {children} sonrasına ya da pages/_app.tsx içinde <Component {...pageProps} /> yanına yerleştirin. Her rotada yüklenmesi için onu tek bir sayfada değil, düzende (layout) çizin.

strategy="afterInteractive", widget'ı sayfa etkileşimli hâle geldikten hemen sonra yükler; böylece sohbet düğmesi hızla görünür. strategy="lazyOnload" ise tarayıcı boşta kalana ve diğer her şey yüklenene kadar bekler; ilk yüklemeyi olabildiğince hafif tutmak istiyorsanız ve düğmenin biraz sonra görünmesi sizin için sorun değilse bunu seçin. İkisi de betiği kritik çizim yolunun dışında tutar. Ayrıntılar için next/script belgelerine bakın.

• İstemci tarafı gezinme. Ziyaretçiler <Link> veya yönlendirici ile sayfalar arasında gezinirken widget konuşmayı açık tutar ve URL değiştiğinde sayfa kurallarınızı ek kod gerektirmeden yeniden kontrol eder.
• SSR ve hydration açısından güvenli. Yalnızca tarayıcıda çalışır ve React'in hydrate ettiği işaretlemenin dışında, document.body üzerine yerleşir; bu yüzden asla hydration uyuşmazlığına yol açmaz.
• Shadow DOM. Tailwind veya genel CSS'iniz sohbete sızmaz, onun stilleri de uygulamanıza sızmaz. Yeniden çizimler onu asla kaldırmaz.
• StrictMode ve Fast Refresh. Geliştirme ortamında iki kez çalışan efektler veya sıcak yeniden yüklemeler ikinci bir sohbet oluşturamaz: widget her anahtar için bir kez yerleşir.
• Depolama. Çerez kullanmaz; anonim bir ziyaretçi kimliği için localStorage'ı, geçerli konuşma için sessionStorage'ı kullanır.

Next.js kendi sohbet botunuzu kurmayı kolaylaştırır ve bazen doğru tercih budur. İki yaklaşım farklı işlere uyar:

• Bir sohbet arayüzü kütüphanesi veya kendi bileşenlerinizle, buna ek olarak kendi API anahtarınızla bir yapay zekâ modelini çağıran bir route handler veya API route ile kendiniz kurun. Yanıtların dayandığı içerik, konuşmaların saklanması ve kötüye kullanıma karşı koruma da size aittir. Sohbet ürününüzün bir parçasıysa uygundur; örneğin kullanıcılarınızın kendi verileriyle çalışan bir asistan.
• Nexoply gibi barındırılan bir yapay zekâ sohbet botu arayüzü, yapay zekâyı ve arka ucu bir arada sunar. Ziyaretçilerin sorularını yalnızca eklediğiniz veya içe aktardığınız işletme bilgilerinden (hizmetler ve fiyatlar, SSS'ler, politikalar, çalışma saatleri) yanıtlar ve bilmediğinde bunu söyler. Yapay zekâ anahtarı yoktur ve sunucunuzda hiçbir şey çalışmaz; konuşmalar, yanıtlanamayan sorular ve spam koruması panelde yönetilir. İşletmeyle ilgili soruları yanıtlaması gereken, müşterilere açık bir web sitesi için uygundur.

Arayüz ve model üzerinde tam kontrol istiyorsanız kendiniz kurun. Amaç, bir arka uç işletmeden ziyaretçilerin sorularını yanıtlamaksa barındırılan widget daha az iş çıkarır. Nexoply'nin işletme bilgilerinizden nasıl yanıt verdiğine bakın.

Hero veya fiyatlandırma bölümünüzde "Bize yazın" düğmesi mi istiyorsunuz? window üzerinde nexoply:open-chat olayını tetikleyin. onClick kullandığı için bir istemci bileşeni (client component) olmalıdır:

"use client";
// components/ChatButton.tsx

export function ChatButton() {
  return (
    <button
      type="button"
      // Nexoply sohbet penceresini açar
      onClick={() => window.dispatchEvent(new Event("nexoply:open-chat"))}
    >
      Bize yazın
    </button>
  );
}

<ChatButton /> bileşenini herhangi bir sayfada veya sunucu bileşeninde kullanın. Widget yüklendikten sonra onu kaldıracak bir API yoktur: mesaj düğmesini bazı sayfalarda (örneğin /checkout) gizlemek için Sohbet botu → Özelleştir → Mesaj düğmesi → Bazı sayfalarda farklı altında "Düğme yok" seçenekli bir sayfa kuralı ekleyin.

next dev'i çalıştırın, http://localhost:3000 adresini açın; köşede bir sohbet düğmesi görünür. "Hafta sonları çalışıyor musunuz?" gibi gerçek bir soru sorun; birkaç saniye içinde konuşma panelinizdeki Konuşmalar bölümünde görünür. Panelde yaptığınız değişiklikler yeniden yayınlamaya gerek kalmadan yaklaşık bir dakika içinde siteye yansır.

Uygulamanız bir Content-Security-Policy başlığı gönderiyorsa (örneğin middleware'den veya next.config'den), Nexoply'ye şuralarda izin verin:

• script-src https://nexoply.com: widget.js dosyasını yüklemek için.
• connect-src https://nexoply.com: sohbetin istekleri için.
• img-src https://nexoply.com: logo ve düğme simgesi gibi görseller için.

• Düğme yok ve sayfa kaynağında data-chatbot boş. Ortam değişkeni okunmamış: NEXT_PUBLIC_ önekini kontrol edin, next dev'i yeniden başlatın ve barındırma ortamınızda değişkeni ekleyip yeniden yayınlayın.
• Betik düzen yerine tek bir sayfada. Her rotada yüklenmesi için onu app/layout.tsx veya pages/_app.tsx dosyasına koyun.
• Etiket değiştirilmiş. data-chatbot özniteliğini ve widget.js içeren bir src değerini korumalıdır.
• CSP veya izin verilen web siteleri tarafından engellenmiş. Tarayıcı konsolunda hatalara bakın ve yukarıdaki iki bölümü kontrol edin.
• Sohbet botu kapalı. Sohbet botu etkin anahtarının açık olduğunu kontrol edin.
• Reklam engelleyiciler. Nadiren bir eklenti sohbet widget'larını engeller. Eklentilerin olmadığı gizli bir pencerede deneyin.

Çalıştıktan sonra Sohbet botu → Özelleştir altında siteye uyumlu hâle getirin: düğme simgesi, etiket, renkler ve konum ya da ekranın kenarında bir yan sekme (örneğin "Yardım"); telefonlarda farklı bir görünüm; seçtiğiniz sayfalar için sayfa kuralları (örneğin yalnızca /pricing sayfasında bir yan sekme). Tüm özelleştirme seçeneklerine ve asistanın işletmenizi nasıl öğrendiğine bakın, planları ve konuşma limitlerini karşılaştırın ya da React sohbet botu bileşeni rehberini ve Vue ve Nuxt sohbet botu rehberini okuyun.