Kullanım

Temel Örnek

import 'package:flutter/material.dart';
import 'package:trustchex_flutter_sdk/trustchex_flutter_sdk.dart';

class VerificationScreen extends StatelessWidget {
  final String sessionId;
  final String baseUrl;

  const VerificationScreen({
    super.key,
    required this.sessionId,
    required this.baseUrl,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Doğrulama')),
      body: TrustchexView(
        sessionId: sessionId,
        baseUrl: baseUrl,
        onCompleted: () {
          Navigator.of(context).pop();
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(
              content: Text('Doğrulama başarıyla tamamlandı!'),
              backgroundColor: Colors.green,
            ),
          );
        },
        onError: (error) {
          Navigator.of(context).pop();
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text('Doğrulama hatası: $error'),
              backgroundColor: Colors.red,
            ),
          );
        },
      ),
    );
  }
}

Özellikler

Özellik	Tip	Zorunlu	Açıklama
baseUrl	String	✅	API temel URL'si
sessionId	String	❌	Oturum tanımlayıcısı
branding	TrustchexBranding	❌	Renkler ve logo
locale	TrustchexLocale	❌	Dil (en, tr)
onCompleted	VoidCallback	❌	Doğrulama süreci tamamlandığında çağrılır
onError	Function(String)	❌	Hata geri çağırma
onDocumentRead	Function(DocumentReadResult)	❌	Belge okunduğunda çağrılır (NFC veya OCR)
skipNfcResultScreen	bool	❌	Başarılı NFC okumasının ardından belge inceleme ekranını atlayarak otomatik olarak devam eder. Varsayılan: false
skipSuccessScreen	bool	❌	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 'package:trustchex_flutter_sdk/trustchex_flutter_sdk.dart';

TrustchexView(
  baseUrl: 'https://your-api.com',
  sessionId: 'session-123',
  onDocumentRead: (result) {
    final document = result.document;

    print(document.documentType.name);  // "passport" | "id"
    print(document.issuingCountry);     // "DEU"
    print(document.nationality);        // "DEU"
    print(document.documentNumber);     // "C01X00T478"
    print(document.personalNumber);     // "8512310074" | null
    print(document.lastName);           // "MÜLLER"
    print(document.firstName);          // "JÜRGEN KARL"
    print(document.sex.name);           // "male" | "female" | "unspecified" | "unknown"
    print(document.dateOfBirth);        // "1985-03-10" (ISO 8601)
    print(document.dateOfExpiry);       // "2030-11-05" (ISO 8601)
  },
  onCompleted: () => print('Done'),
  onError: (error) => print('Error: $error'),
)

DocumentReadResult

class DocumentReadResult {
  final DocumentData document;
  final DocumentName name;
  final DocumentFaceImage? face;
}

class DocumentData {
  final ScannedDocumentType documentType; // .passport | .idCard
  final String issuingCountry;            // 3-letter ICAO code, e.g. "TUR"
  final String nationality;
  final String documentNumber;
  final String? personalNumber;
  final String lastName;                  // En iyi ad bilgisi, örn. "MÜLLER"
  final String firstName;                 // En iyi ad bilgisi, örn. "JÜRGEN"
  final DocumentSex sex;                  // .male | .female | .unspecified
  final String? dateOfBirth;              // ISO 8601, e.g. "1990-05-15"
  final String? dateOfExpiry;             // ISO 8601, e.g. "2028-03-01"
}

class DocumentName {
  final String rawLast;       // MRZ ASCII surname
  final String rawFirst;      // MRZ ASCII given name
  final String displayLast;   // Best Unicode form
  final String displayFirst;  // Best Unicode form
  final DocumentNameSource source; // .dg11 | .reverseTable | .raw
}

class DocumentFaceImage {
  final String data;      // Base64-encoded image
  final String mimeType;  // 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.
reverseTable	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.

TrustchexView(
  baseUrl: 'https://your-api.com',
  sessionId: 'session-123',
  skipNfcResultScreen: true,
  onCompleted: () => print('Tamamlandı'),
  onError: (error) => print('Hata: $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.

TrustchexView(
  baseUrl: 'https://your-api.com',
  sessionId: 'session-123',
  skipSuccessScreen: true,
  onCompleted: () {
    // Doğrulama tamamlandığında anında çağrılır
    Navigator.of(context).pop();
  },
  onError: (error) => print('Hata: $error'),
)

Her iki prop birlikte kullanılabilir:

TrustchexView(
  baseUrl: 'https://your-api.com',
  sessionId: 'session-123',
  skipNfcResultScreen: true,
  skipSuccessScreen: true,
  onDocumentRead: (result) => print(result.name.displayFirst),
  onCompleted: () => Navigator.of(context).pop(),
  onError: (error) => print('Hata: $error'),
)

Markalaşma ile

TrustchexView(
  sessionId: sessionId,
  baseUrl: 'https://api.trustchex.com',
  locale: TrustchexLocale.tr,
  branding: const TrustchexBranding(
    logoUrl: 'https://trustchex.com/logo.png',
    primaryColor: Color(0xFF1E40AF),
    secondaryColor: Color(0xFFF8FAFC),
    tertiaryColor: Color(0xFFDC2626),
  ),
  onCompleted: () {
    Navigator.of(context).pop();
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(
        content: Text('Doğrulama başarıyla tamamlandı!'),
        backgroundColor: Colors.green,
      ),
    );
  },
  onError: (error) {
    Navigator.of(context).pop();
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text('Doğrulama hatası: $error'),
        backgroundColor: Colors.red,
      ),
    );
  },
)

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 kancaları 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. Uygulama açıkken gelen bir bağlantının mevcut aktiviteye iletilmesi için android:launchMode="singleTop" (Flutter varsayılanı) değerini koruyun:

<activity android:name=".MainActivity" android:launchMode="singleTop">
  <intent-filter>
    <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

app_links paketini ekleyin — hem soğuk hem sıcak başlangıç bağlantılarını iletir ve yerel işleyicileri (Android'de onNewIntent, iOS'ta sahne/URL geri çağrıları) kendisi kaydeder; bu yüzden MainActivity veya AppDelegate geçersiz kılması gerekmez:

dependencies:
  app_links: ^6.3.2

Bağlantılara abone olun ve ayrıştırılan sessionId / baseUrl değerlerini TrustchexView'a iletin. Backend'in ürettiği app-url/{host}/verification-session/{id} formatını (gömülü https:// host biçimi dahil) ayrıştıran DeeplinkUtils.parseQrCodeUrl fonksiyonunu kullanın:

import 'dart:async';

import 'package:app_links/app_links.dart';
import 'package:flutter/material.dart';
import 'package:trustchex_flutter_sdk/trustchex_flutter_sdk.dart';

class App extends StatefulWidget {
  const App({super.key});

  @override
  State<App> createState() => _AppState();
}

class _AppState extends State<App> {
  final AppLinks _appLinks = AppLinks();
  StreamSubscription<Uri>? _linkSubscription;
  String _baseUrl = 'https://app.trustchex.com';
  String _sessionId = '';
  String? _lastHandledUrl;

  @override
  void initState() {
    super.initState();
    _initDeepLinks();
  }

  Future<void> _initDeepLinks() async {
    // Soğuk başlangıç: uygulama derin bağlantı tarafından başlatıldı.
    final initialUri = await _appLinks.getInitialLink();
    if (initialUri != null) _processDeepLink(initialUri.toString());

    // Sıcak başlangıç: bağlantı uygulama çalışırken gelir.
    _linkSubscription = _appLinks.uriLinkStream.listen(
      (uri) => _processDeepLink(uri.toString()),
      onError: (_) {},
    );
  }

  void _processDeepLink(String url) {
    if (url == _lastHandledUrl) return; // öne gelişte tekrarları yok say
    final parsed = DeeplinkUtils.parseQrCodeUrl(url);
    final sessionId = parsed['sessionId'];
    final baseUrl = parsed['baseUrl'];
    if (sessionId != null &&
        sessionId.isNotEmpty &&
        baseUrl != null &&
        baseUrl.isNotEmpty) {
      setState(() {
        _lastHandledUrl = url;
        _baseUrl = baseUrl;
        _sessionId = sessionId;
      });
    }
  }

  @override
  void dispose() {
    _linkSubscription?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return TrustchexView(
      baseUrl: _baseUrl,
      sessionId: _sessionId.isEmpty ? null : _sessionId,
      onCompleted: () => print('Tamamlandı'),
      onError: (error) => print('Hata: $error'),
    );
  }
}

DeeplinkUtils.parseQrCodeUrl fonksiyonu şu formattaki URL'leri ayrıştırır:

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

Ve baseUrl ve sessionId anahtarları içeren bir map 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. Derin Bağlantı (Önerilen)

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

// Derin bağlantı formatı: yourapp://app-url/your-api.com/verification-session/session-123
TrustchexView(
  baseUrl: 'https://your-api.com',
  sessionId: 'session-123', // Derin bağlantıdan
  onCompleted: () => print('Tamamlandı'),
)

Avantajlar:

• Sorunsuz kullanıcı deneyimi - başlatmak için tek dokunuş
• Doğrulamaya doğrudan yönlendirme
• Manuel giriş gerekmez
• E-posta ve SMS kampanyaları için harika çalışır

2. QR Kod Tarama (Önerilen)

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

Avantajlar:

• Hızlı ve temassız
• Yazma gerekmez
• Yüz yüze doğrulama için ideal
• SDK'da yerleşik tarayıcı dahil

3. Oturum Kodu Girişi (Alternatif)

Kullanıcılar manuel olarak 8 karakterli alfasayısal bir kod girebilir:

TrustchexView(
  baseUrl: 'https://your-api.com',
  // sessionId özelliği gerekmez - kullanıcı kodu manuel olarak girer
  onCompleted: () => print('Tamamlandı'),
)

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

• 8 karakterli oturum kodunu girin
• QR kodunu tarayın

Kullanım Durumları:

• QR/derin bağlantı mevcut olmadığında yedek
• Telefon/sesli destek senaryoları
• QR yeteneği olmayan basılı medya

Oturum Oluşturma

REST API aracılığıyla bir oturum oluşturduğunuzda, yanıtta erişim yöntemlerini alacaksınız:

final response = await http.post(
  Uri.parse('https://your-api.com/api/v1/verification-sessions'),
  headers: {'x-api-key': 'YOUR_API_KEY'},
  body: jsonEncode({
    'workflowId': 'workflow-123',
    'email': 'user@example.com'
  }),
);

final data = jsonDecode(response.body);
final deepLink = data['deepLink'];
final qrCodeLink = data['qrCodeLink'];
final sessionCode = data['sessionCode'];

// Doğrudan uygulama navigasyonu için deepLink kullanın (önerilen)
// QR kodu oluşturmak için qrCodeLink kullanın (önerilen)
// Alternatif erişim yöntemi olarak sessionCode kullanın