Kullanım

Temel Örnek

import Trustchex from '@trustchex/react-native-sdk';

<Trustchex
  baseUrl="https://your-api.com"
  sessionId="session-123"
  onCompleted={() => console.log('Tamamlandı')}
  onError={(error) => console.error(error)}
/>

Özellikler

Özellik	Tip	Zorunlu	Açıklama
baseUrl	string	✅	API temel URL'si
sessionId	string	❌	Oturum tanımlayıcısı
branding	object	❌	Renkler ve logo
locale	'en' | 'tr'	❌	Dil
onCompleted	() => void	❌	Doğrulama süreci tamamlandığında çağrılır
onError	(error) => void	❌	Hata geri çağırma
onDocumentRead	(result: DocumentReadResult) => void	❌	Belge okunduğunda çağrılır (NFC veya OCR)
skipNfcResultScreen	boolean	❌	Başarılı NFC okumasının ardından belge inceleme ekranını atlayarak otomatik olarak devam eder. Varsayılan: false
skipSuccessScreen	boolean	❌	Süreç tamamlandığında son başarı ekranını atlar ve onCompleted'ı anında çağırır. Varsayılan: false

Belge Okuma Olayı

onDocumentRead geri çağırması, belge verisi mevcut olur olmaz tetiklenir — başarılı bir NFC çip okumasından veya başarılı bir kamera OCR taramasından hemen sonra. Kaynaktan bağımsız olarak birleşik bir DocumentReadResult nesnesi alır.

import Trustchex, { type DocumentReadResult } from '@trustchex/react-native-sdk';

<Trustchex
  baseUrl="https://your-api.com"
  sessionId="session-123"
  onDocumentRead={(result: DocumentReadResult) => {
    const { document } = result;

    console.log(document.documentType);   // "P" (pasaport) | "I" (kimlik kartı)
    console.log(document.issuingCountry); // "DEU"
    console.log(document.nationality);    // "DEU"
    console.log(document.documentNumber); // "C01X00T478"
    console.log(document.personalNumber); // "8512310074" | null
    console.log(document.lastName);       // "MÜLLER"
    console.log(document.firstName);      // "JÜRGEN KARL"
    console.log(document.sex);            // "M" | "F" | "X" | "U"
    console.log(document.dateOfBirth);    // "1985-03-10" (ISO 8601)
    console.log(document.dateOfExpiry);   // "2030-11-05" (ISO 8601)
  }}
  onCompleted={() => console.log('Done')}
  onError={(error) => console.error(error)}
/>

DocumentReadResult

interface DocumentReadResult {
  document: {
    documentType: string;        // "P" (passport) | "I" (ID card)
    issuingCountry: string;      // 3-letter ICAO country code, e.g. "TUR"
    nationality: string;
    documentNumber: string;
    personalNumber: string | null;
    lastName: string;            // Best available name, e.g. "MÜLLER"
    firstName: string;           // Best available name, e.g. "JÜRGEN"
    sex: 'M' | 'F' | 'X' | 'U';
    dateOfBirth: string | null;  // ISO 8601, e.g. "1990-05-15"
    dateOfExpiry: string | null; // ISO 8601, e.g. "2028-03-01"
  };
  name: {
    rawLast: string;             // MRZ ASCII surname
    rawFirst: string;            // MRZ ASCII given name
    displayLast: string;         // Best Unicode form, e.g. "SAYGI"
    displayFirst: string;        // Best Unicode form, e.g. "SELİM"
    source: 'dg11' | 'reverse_table' | 'raw';
  };
  face?: {
    data: string;                // Base64-encoded image
    mimeType: string;            // e.g. "image/jpeg"
  };
}

İsim Kaynakları

Kaynak	Açıklama
dg11	NFC çipindeki DG11 dosyasından okunan tam basılı isim (UTF-8). En yüksek doğruluk.
reverse_table	ICAO 9303 ters transliterasyon tablosu ile yeniden oluşturuldu (ör. OE→Ö, UE→Ü). Bilinen ülkeler için uygulanır.
raw	Dönüşüm yapılmadı — görüntülenen isim ham MRZ ASCII değeriyle aynı.

Akış Kontrolü

NFC Sonuç Ekranını Atla

Varsayılan olarak, başarılı bir NFC çip okumasının ardından SDK, kullanıcının devam etmeden önce belge verilerini doğrulayabileceği bir inceleme ekranı gösterir. skipNfcResultScreen ile bu ekranı tamamen atlayabilirsiniz — NFC taraması tamamlanır tamamlanmaz SDK otomatik olarak ilerler.

<Trustchex
  baseUrl="https://your-api.com"
  sessionId="session-123"
  skipNfcResultScreen
  onCompleted={() => console.log('Tamamlandı')}
  onError={(error) => console.error(error)}
/>

İnceleme ekranını göstermeden taranan belge verilerine erişmek istiyorsanız bu prop ile birlikte onDocumentRead kullanabilirsiniz.

Başarı Ekranını Atla

Varsayılan olarak, doğrulama süreci tamamlandıktan sonra SDK onCompleted çağırmadan önce 3 saniye boyunca başarı animasyonu gösterir. skipSuccessScreen ile onCompleted animasyon veya bekleme olmadan anında çağrılır.

<Trustchex
  baseUrl="https://your-api.com"
  sessionId="session-123"
  skipSuccessScreen
  onCompleted={() => {
    // Doğrulama tamamlandığında anında çağrılır
    navigation.navigate('Home');
  }}
  onError={(error) => console.error(error)}
/>

Her iki prop birlikte kullanılabilir:

<Trustchex
  baseUrl="https://your-api.com"
  sessionId="session-123"
  skipNfcResultScreen
  skipSuccessScreen
  onDocumentRead={(result) => console.log(result.name.displayFirst)}
  onCompleted={() => navigation.navigate('Home')}
  onError={(error) => console.error(error)}
/>

Markalaşma ile

<Trustchex
  baseUrl="https://your-api.com"
  sessionId="session-123"
  branding={{
    logoUrl: 'https://your-logo.png',
    primaryColor: '#1E40AF',
    secondaryColor: '#F8FAFC',
    tertiaryColor: '#DC2626'
  }}
  locale="tr"
  onCompleted={() => console.log('Tamamlandı')}
/>

Derin Bağlantılar (İsteğe Bağlı)

Derin bağlantı işlevselliği, bağımsız bir uygulama yayınlamak istiyorsanız isteğe bağlı bir özelliktir. SDK ile derin bağlantıları işlemek için uygulamanızda derin bağlantıları yapılandırmanız ve gelen URL'leri işlemek için gerekli hook'ları kurmanız gerekir.

1. Derin Bağlantı Şemalarını Yapılandırın

iOS - Info.plist dosyasına ekleyin:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

Android - AndroidManifest.xml dosyasına ekleyin:

<activity android:name=".MainActivity">
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="yourapp" />
  </intent-filter>
</activity>

2. Derin Bağlantı İşlemeyi Kurun

Gelen URL'leri işlemek için handleDeepLink fonksiyonunu import edin ve kullanın:

import React from 'react';
import { AppState, Linking } from 'react-native';
import Trustchex, { handleDeepLink } from '@trustchex/react-native-sdk';

const App = () => {
  const [baseUrl, setBaseUrl] = React.useState<string | undefined>();
  const [sessionId, setSessionId] = React.useState<string>('');

  React.useEffect(() => {
    const handleInitialDeepLink = async () => {
      const url = await Linking.getInitialURL();
      if (url) {
        const [bUrl, sId] = handleDeepLink({ url });
        if (bUrl && sId) {
          setBaseUrl(bUrl);
          setSessionId(sId);
        }
      }
    };

    const handleIncomingLink = ({ url }: { url: string }) => {
      const [bUrl, sId] = handleDeepLink({ url });
      if (bUrl && sId) {
        setBaseUrl(bUrl);
        setSessionId(sId);
      }
    };

    Linking.addEventListener('url', handleIncomingLink);
    handleInitialDeepLink();

    const subscription = AppState.addEventListener('change', (nextAppState) => {
      handleInitialDeepLink();
    });

    return () => {
      Linking.removeAllListeners('url');
      subscription.remove();
    };
  }, []);

  return (
    <Trustchex
      baseUrl={baseUrl}
      sessionId={sessionId}
      onCompleted={() => console.log('Tamamlandı')}
      onError={(error) => console.error(error)}
    />
  );
};

handleDeepLink fonksiyonu şu formattaki URL'leri ayrıştırır:

scheme://app-url/your-api.com/verification-session/session-123

Ve Trustchex bileşeni ile kullanabileceğiniz [baseUrl, sessionId] döndürür.

Oturumlar

REST API kullanarak oturumlar oluşturun.

Oturum Erişim Yöntemleri

SDK, kullanıcıların doğrulama oturumlarına erişmeleri için birden fazla yol sağlar:

1. Oturum Kodu Girişi (Önerilir)

Kullanıcılar hoş geldiniz ekranında gösterilen 8 karakterlik alfanümerik bir kodu manuel olarak girebilirler:

<Trustchex
  baseUrl="https://your-api.com"
  // sessionId prop'una gerek yok - kullanıcı kodu manuel olarak girer
  onCompleted={() => console.log('Tamamlandı')}
/>

sessionId sağlanmadığında, SDK kullanıcıların şunları yapabileceği bir ekran görüntüler:

• Oturum kodunu girin (örn. AB12CD34)
• QR kodu tarayın

Avantajları:

• Tüm iletişim kanallarında çalışır (e-posta, SMS)
• Derin bağlantı kurulumu gerektirmez
• Kullanıcıların yazması basittir

2. Derin Bağlantı (Doğrudan Erişim)

Kullanıcılar, uygulamayı doğrudan oturumla açan bir bağlantıya tıklarlar:

// Derin bağlantı formatı: yourapp://app-url/your-api.com/verification-session/session-123
<Trustchex
  baseUrl="https://your-api.com"
  sessionId="session-123" // Derin bağlantıdan
  onCompleted={() => console.log('Tamamlandı')}
/>

3. QR Kod Tarama

Kullanıcılar oturum bilgilerini içeren bir QR kodunu tararlar. SDK, hoş geldiniz ekranından erişilebilen yerleşik bir QR tarayıcı içerir.

Oturum Kodları ile Oturum Oluşturma

REST API aracılığıyla bir oturum oluştururken, yanıtta bir sessionCode alırsınız:

const response = await fetch('https://your-api.com/api/v1/verification-sessions', {
  method: 'POST',
  headers: { 'x-api-key': 'API_ANAHTARINIZ' },
  body: JSON.stringify({
    workflowId: 'workflow-123',
    email: '[email protected]'
  })
});

const { sessionCode } = await response.json();
// sessionCode: "AB12CD34"

// Bu kodu kullanıcıya gösterin
console.log(`Doğrulama kodunuz: ${sessionCode}`);