React İle Web Uygulamaları İçin Dinamik Bir Doküman İmzalama Aracı Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Dinamik bir imza aracı geliştirmek için Node.js ortamının kurulu olması ve temel düzeyde React Hooks (useState, useRef, useEffect) bilgisine sahip olmanız gerekmektedir. Projenize başlamadan önce aşağıdaki paketleri yükleyerek işe koyulabilirsiniz.

Öncelikle, React projenizi oluşturun ve gerekli bağımlılıkları ekleyin. İmza alanı için react-signature-canvas kütüphanesi, endüstri standardı olan Canvas API'sini React ile uyumlu hale getirir.

npx create-react-app imza-uygulamasi
cd imza-uygulamasi
npm install react-signature-canvas

Bu komutlar, projenizin temel iskeletini oluşturacak ve imza bileşenini yönetmemizi sağlayacak kütüphaneyi yükleyecektir. Projeyi başlattıktan sonra src klasörü altında components dizini oluşturarak düzenli bir yapı kurmanızı öneririm.

Adım 1: İmza Bileşenini Oluşturma

İlk adımda, kullanıcının imza atabileceği alanı temsil eden bir bileşen oluşturacağız. Bu bileşen, ref kullanarak Canvas öğesine erişecek ve çizim işlemlerini kontrol edecektir. useRef kancası, DOM öğelerine doğrudan erişim sağlamak için kullanılır.

import React, { useRef } from 'react';
import SignatureCanvas from 'react-signature-canvas';

const ImzaAlani = () => {
  const sigCanvas = useRef({});

  const temizle = () => sigCanvas.current.clear();

  return (
    

      
      İmzayı Temizle
    
  );
};

export default ImzaAlani;

Burada SignatureCanvas bileşeni, tarayıcıda bir HTML5 Canvas oluşturur. ref parametresi sayesinde, bileşenin içindeki clear() metoduna erişerek imza alanını sıfırlayabiliyoruz.

Adım 2: İmza Verisini Kaydetme ve İşleme

İmza alındıktan sonra bu veriyi bir görsel (Base64 formatında) olarak saklamanız gerekir. Base64, veriyi ASCII karakter dizisine dönüştürerek HTTP istekleri içerisinde kolayca taşınmasını sağlar. Aşağıdaki örnekte, imzanın nasıl bir veri URL'sine dönüştürüldüğünü görebilirsiniz.

const kaydet = () => {
  const imzaVerisi = sigCanvas.current.getTrimmedCanvas().toDataURL('image/png');
  console.log("İmza Verisi:", imzaVerisi);
  // Burada API isteği ile sunucuya gönderebilirsiniz
};

getTrimmedCanvas() metodu, imzanın etrafındaki boşlukları kırparak sadece çizilen alanı alır. Bu, verinin optimize edilmesi ve sunucuda gereksiz yer kaplamaması için kritik bir adımdır.

Adım 3: Güvenlik ve Doğrulama Stratejileri

İmza verileri hassas bilgilerdir. Bu verileri sunucuya gönderirken mutlaka HTTPS protokolü kullanmalı ve verinin bütünlüğünü kontrol etmelisiniz. Ayrıca, istemci tarafında yapılan kontrollerin tek başına yeterli olmadığını unutmayın.

Kritik Güvenlik Uyarısı: İstemci tarafında (React) yapılan imza kontrolleri yalnızca kullanıcı deneyimi içindir. Sunucu tarafında (Backend), gelen Base64 verisinin boyutunu ve içeriğini mutlaka doğrulayın. XSS (Cross-Site Scripting) saldırılarına karşı, sunucuya gönderilen verileri her zaman sanitize edin.

Aşağıdaki tablo, imza saklama yöntemlerinin karşılaştırmasını göstermektedir:

Adım 4: Dinamik Doküman Entegrasyonu

İmza aracını bir dokümanın altına yerleştirmek için CSS ile konumlandırma yapmanız gerekir. Kullanıcının belgeyi okuduğundan emin olmak için onScroll veya useEffect ile bir onay mekanizması ekleyebilirsiniz.

useEffect(() => {
  const handleScroll = (e) => {
    if (e.target.scrollHeight - e.target.scrollTop === e.target.clientHeight) {
      setOkundu(true);
    }
  };
  // Belge div'ine event listener ekleyin
}, []);

Bu kod bloğu, kullanıcının dokümanı sonuna kadar kaydırdığını tespit eder. Bu sayede, "Sözleşmeyi okudum ve onaylıyorum" kutucuğunu ancak kullanıcı metni inceledikten sonra aktif edebilirsiniz.

Adım 5: Hata Ayıklama ve Yaygın Sorunlar

React uygulamalarında en sık karşılaşılan sorun, Canvas'ın yeniden render edilmesi sırasında imzanın silinmesidir. Bunu önlemek için useMemo veya useCallback kullanarak bileşenlerin gereksiz güncellenmesini engelleyin. Ayrıca, mobil cihazlarda dokunmatik ekran hassasiyeti için touch-action: none CSS kuralını eklemeyi unutmayın.

.imza-canvas {
  touch-action: none;
  border: 1px solid #ccc;
  border-radius: 8px;
}

Bu CSS kuralı, mobil cihazlarda parmakla kaydırma hareketinin imza çizimiyle çakışmasını engeller ve daha akıcı bir deneyim sunar.

Sıkça Sorulan Sorular

İmza verisi veritabanında nasıl saklanmalı?

İmza verisini Base64 string olarak saklamak yerine, bu veriyi bir görsel dosyasına (PNG) dönüştürüp AWS S3 veya benzeri bir bulut depolama servisinde tutmanız, veritabanı performansınız için daha sağlıklıdır. Veritabanında sadece dosyanın URL'sini tutun.

İmza yasal olarak geçerli midir?

Elektronik imzaların yasal geçerliliği ülkelere göre değişir. Türkiye'de 5070 sayılı Elektronik İmza Kanunu kapsamında, güvenli elektronik imza ile ıslak imza aynı hukuki sonucu doğurur. Ancak web uygulamalarında alınan basit çizimler genellikle "Elektronik Onay" statüsündedir.

Mobil cihazlarda imza atarken sayfa kayıyor, ne yapmalıyım?

CSS içerisinde touch-action: none kullanarak tarayıcının varsayılan kaydırma davranışını imza alanı üzerinde devre dışı bırakmalısınız.

İmza boyutunu nasıl optimize ederim?

toDataURL('image/png', 0.5) metodundaki ikinci parametre, görselin kalitesini belirtir. 0.5 ile 0.8 arası değerler, görsel kalitesinden ödün vermeden dosya boyutunu ciddi oranda düşürür.

Birden fazla imza alanı ekleyebilir miyim?

Evet, her imza alanı için ayrı bir useRef tanımlayarak aynı sayfada birden fazla imza alanı yönetebilirsiniz.

Yasal Sorumluluk Reddi: Bu makalede paylaşılan kodlar eğitim amaçlıdır. Uygulamanızın hukuki gerekliliklere, KVKK (Kişisel Verilerin Korunması Kanunu) ve ilgili mevzuata uygunluğunu sağlamak için bir hukuk danışmanına başvurmanız önerilir.

İleri Seviye İpuçları: İmza Verisini PDF Üzerine Gömme

İmza verisini sadece bir görsel olarak kaydetmek yerine, dokümanın bir parçası haline getirmek için sunucu tarafında pdf-lib gibi kütüphaneler kullanabilirsiniz. Bu yöntem, imzanın dokümanla ayrılmaz bir bütün olmasını sağlar ve manipülasyon riskini azaltır.

Aşağıdaki örnek, React tarafında alınan Base64 formatındaki imza verisinin, sunucu tarafında bir PDF dosyasına nasıl işlenebileceğine dair temel mantığı gösterir:

// Node.js tarafında örnek imza gömme mantığı
const { PDFDocument } = require('pdf-lib');

async function embedSignature(pdfBytes, signatureData) {
  const pdfDoc = await PDFDocument.load(pdfBytes);
  const signatureImage = await pdfDoc.embedPng(signatureData);
  const pages = pdfDoc.getPages();
  const firstPage = pages[0];

  firstPage.drawImage(signatureImage, {
    x: 100,
    y: 100,
    width: 200,
    height: 100,
  });

  return await pdfDoc.save();
}

Performans Optimizasyonu ve Canvas Yönetimi

İmza bileşenleri, özellikle düşük donanımlı mobil cihazlarda tarayıcıyı yorabilir. Performansı artırmak için şu stratejileri uygulayabilirsiniz:

• Canvas Çözünürlüğü: İmza alanının width ve height değerlerini CSS ile değil, canvas elementinin width ve height nitelikleri ile belirleyin. Bu, pikselleşmeyi önler ve daha net sonuçlar verir.
• Debounce Kullanımı: İmza verisini her hareketten sonra değil, onEnd veya onMouseUp olaylarından sonra işleyin.
• Bellek Yönetimi: İmza bileşeni unmount olduğunda (sayfadan kaldırıldığında), canvas üzerindeki event listener'ları temizleyerek bellek sızıntılarını engelleyin.

// Bellek yönetimi için useEffect temizleme adımı
useEffect(() => {
  const canvas = canvasRef.current;
  const handleMouseUp = () => saveSignature();

  canvas.addEventListener('mouseup', handleMouseUp);

  return () => {
    // Bileşen kaldırıldığında listener'ı temizle
    canvas.removeEventListener('mouseup', handleMouseUp);
  };
}, []);

Alternatif Kütüphane Karşılaştırması

Projenizde react-signature-canvas dışında, farklı ihtiyaçlara yönelik şu alternatifleri de değerlendirebilirsiniz:

İpucu: Kütüphane seçerken projenizin "bundle size" üzerindeki etkisini bundlephobia.com üzerinden kontrol etmeyi unutmayın. Mobil öncelikli projelerde en hafif kütüphaneyi tercih etmek, sayfa açılış hızını doğrudan etkiler.

Sonuç

React ile dinamik bir doküman imzalama aracı geliştirmek, modern web mimarisinin gücünü gösteren etkileyici bir örnektir. Bu süreçte Canvas API kullanımı, state yönetimi ve veri güvenliği gibi temel yazılım prensiplerini uyguladık. Bir sonraki adımda, bu imza verisini PDF dokümanları üzerine otomatik olarak gömen bir sunucu tarafı (Node.js/Express) entegrasyonu yaparak projenizi tam bir doküman yönetim sistemine dönüştürebilirsiniz.