Android - Face Modülü¶

Face modülü, ön kamera üzerinden alınan görüntülerle kişinin gerçek bir birey olup olmadığını analiz eder. Gülümseme, göz kapama, başı sağa/sola çevirme ve yukarı bakma gibi yüz ifadelerini ve hareketlerini algılayabilir. Özellikle canlılık kontrolü gerektiren kimlik doğrulama süreçlerinde kullanılır.

⚠️ Ön Koşul: Face Modülünü kullanmadan önce Maven erişimi sağlanmış ve Core Modülü projeye eklenmiş olmalıdır.

Projeye Eklenmesi¶

1. libs.versions.toml dosyasına ekleyin:¶

wide760[versions] ... enqualify-plus = "x.x.x.x" [libraries] ... enqualify-plus-face = { group = "com.enqualify.plus", name = "face", version.ref = "enqualify-plus" }

2. build.gradle.kts dosyasına bağımlılığı ekleyin:¶

wide760implementation(libs.enqualify.plus.face)

3. Gradle Sync¶

"Sync Now" seçeneğine tıklayarak Gradle dosyalarını senkronize edin.

İmplementasyon¶

1. İzinler¶

Kamera izni SDK tarafından manifeste otomatik olarak eklenir ve gerekli noktalarda yine SDK tarafından istenir. Aşağıdaki satır yalnızca bilgi amaçlıdır:

wide760

Kamera izni verilmezse Face modülü çalışmaz.

2. Activity Layout — FrameLayout¶

Face işleminin yapılacağı Activity'nin layout'una tam ekran kaplayan bir FrameLayout eklenmelidir. SDK, kamera ekranlarını ve sayfa geçişlerini bu bileşen üzerinden yönetir:

wide760<FrameLayout android:id="@+id/fragmentContainer" android:layout_width="match_parent" android:layout_height="match_parent" />

3. FaceCallbacks Interface'inin Eklenmesi¶

FaceCallbacks interface'i Face işlemlerini yönetmek için gerekli callback metodlarını içerir ve mutlaka bir Activity ile çalışmalıdır.

Sınıfa eklenmesi:

wide760class EnQualifyPlusActivity : AppCompatActivity(), FaceCallbacks

Callback'lerin override edilmesi:

wide760class EnQualifyPlusActivity : AppCompatActivity(), FaceCallbacks { override fun initializeCompleted(modules: EnModules) { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") when (modules) { EnModules.FACE -> { // Face işlemleri başlatılabilir } } } override fun initializeFailed(failureCode: FailureCode, additionalMessage: String) { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } // Canlılık adımı callback'leri override fun faceDetected() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun smileDetected() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun eyeCloseDetected() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun eyeCloseIntervalDetected() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun faceRightDetected() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun faceLeftDetected() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun faceUpDetected() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } // Karşılaştırma callback'leri override fun faceCompareStarted() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun faceCompareCompleted() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun faceCompareFailed(errorMessage: String) { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } // Tamamlanma / hata callback'leri override fun faceSaveStarted() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun faceCompleted() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") enQualifyFace.faceCompare() // faceCompleted sonrası faceCompare başlatılır } override fun faceDetectFailed(failureCode: FaceFailureCode) { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun faceFailed(faceFailureCode: FaceFailureCode, additionalMessage: String?) { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") // LuminosityFailed iş kesici bir hata değildir; işlem durdurulmamalıdır. } override fun integrationAddCompleted() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun integrationAddFailed(errorMessage: String) { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } }

4. EnQualifyFace'nin Initialize Edilmesi¶

Face işlemlerine başlamadan önce EnQualifyFace.initialize() çağrılmalıdır. Initialize edilmeden başka bir işlem yapılmaya çalışılırsa SDK çalışmaz.

wide760val sessionModel = SessionModel( callType = "NewCustomer", reference = UUID.randomUUID().toString() ) val baseModel = BaseModel( baseURL = "https://deveqmapi.enqura.com", signallingCertificateList = listOf("enqura"), mapiCertificateList = listOf("enqura"), mobileUser = "mobile", countryCode = "TUR", locale = "TR", useEmbeddedLocalSound = false ) EnQualifyFace.initialize( context = this, fragmentManager = supportFragmentManager, containerID = R.id.fragmentContainer, sessionModel = sessionModel, baseModel = baseModel, stepCount = 3 )

Initialize Parametreleri¶

Initialize Sonrası Otomatik Akış¶

initialize() çağrıldıktan sonra SDK sırasıyla Token → Session → Settings adımlarını otomatik yürütür. Hata durumlarında ilgili callback'ler tetiklenir. Tüm adımlar başarıyla tamamlandığında initializeCompleted tetiklenir ve Face işlemleri başlatılabilir.

Face İşlemleri¶

Fonksiyonlar¶

Tipik Canlılık Akışı¶

Aşağıda önerilen tipik bir canlılık akışı örneği verilmiştir. stepCount değerine ve iş akışınıza göre adımlar özelleştirilebilir:

wide760// 1. Yüz tespiti enQualifyFace.faceDetect() override fun faceDetected() { // 2. Gülümseme enQualifyFace.smileDetect() } override fun smileDetected() { // 3. Göz kapama enQualifyFace.eyeCloseDetect() } override fun eyeCloseDetected() { // Tüm adımlar tamamlandı — akışı bitir enQualifyFace.faceComplete() } override fun faceCompleted() { // Veriler backoffice'e iletildi — karşılaştırmayı başlat enQualifyFace.faceCompare() } override fun faceCompareCompleted() { // Canlılık ve karşılaştırma başarılı — sonuç sayfasına geç enQualifyFace.replaceFragment(FaceResultFragment()) }

Yüz Karşılaştırma (faceCompare)¶

faceCompare(), canlılık adımında alınan görsel ile OCR ve NFC işlemlerinden elde edilen biyometrik fotoğrafı karşılaştırarak yüz tanıma işlemi gerçekleştirir.

wide760enQualifyFace.faceCompare()

Karşılaştırma başladığında faceCompareStarted tetiklenir. Bu aşamada kullanıcıya progress göstergesi sunulması önerilir:

wide760override fun faceCompareStarted() { // Progress göster } override fun faceCompareCompleted() { // Karşılaştırma başarılı; sonuç sayfasına yönlendir } override fun faceCompareFailed(errorMessage: String) { // Karşılaştırma başarısız; hata yönetimi }

Entegrasyon Verisi Ekleme¶

wide760val integrationModel = IntegrationModel( idRegistration = IDRegistration(), addressRegistration = AddressRegistration(), data = "" ) enQualifyFace.addIntegration(integrationModel) wide760override fun integrationAddCompleted() { Log.i(TAG, "integrationAddCompleted") } override fun integrationAddFailed(errorMessage: String) { Log.i(TAG, "integrationAddFailed: $errorMessage") }

Session Kapatma ve Temizleme¶

wide760enQualifyFace.closeSession(isFinished = true) override fun sessionCloseCompleted() { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") } override fun sessionCloseFailed(errorMessage: String) { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name} $errorMessage") } // SDK'yı temizle enQualifyFace.clear()

ℹ️ Session kapatıldıktan sonra SDK'yı tekrar kullanmak için initialize() yeniden çağrılmalıdır.

Hata Kodları¶

FaceFailureCode¶

wide760enum class FaceFailureCode(val errorMessage: String) { SmilingError("No smile detected during the capture session."), FaceDetectionError("No face detected during the capture session."), FaceUpError("No Face Up during the capture session."), FaceLeftError("No Face Left detected during the capture session."), FaceRightError("No Face Right during the capture session."), EyeCloseError("No Eye close during the capture session."), EyeOpenError("No Eye Open detected during the capture session."), FaceTimeout("FaceTimeout"), EyeCloseIntervalError("No Eye close during the capture session."), NoFaceFrameCountError("NoFaceFrameCountError"), LuminosityFailed("LuminosityFailed"), // İş kesici değildir Failed(""), FaceSaveFailed("") }

faceFailed callback'i aracılığıyla iletilir:

wide760override fun faceFailed(faceFailureCode: FaceFailureCode, additionalMessage: String?) { Log.i(tag, "${object {}.javaClass.enclosingMethod?.name}") }

⚠️ Önemli: LuminosityFailed bir uyarı niteliğindedir ve iş kesici değildir. Bu hata geldiğinde işlem durdurulmamalıdır.

Sonuç Verisine Erişim¶

Face işlemi tamamlandıktan sonra elde edilen verilere CustomerFace nesnesi üzerinden erişilir:

wide760CustomerFace.getInstance()

CustomerFace modeli ve tüm alanlarının açıklaması için Core Modülü — CustomerFace sayfasına bakınız.

Callback Referansı¶

Token / Session / Settings¶

Face — Canlılık Adımları¶

Face — Karşılaştırma¶