Laporan Deteksi Liveness: Skor, Metode & Pencocokan

Gambaran Umum

Laporan deteksi liveness mencakup semua hal yang diamati Didit saat memverifikasi bahwa orang yang nyata dan hidup berada di depan kamera — bukan foto cetakan, pemutaran ulang layar, atau deepfake. Laporan ini mencakup metode liveness, skor keyakinan 0–100, swafoto referensi dan video pengambilan gambar, estimasi usia opsional, metrik kualitas liveness pasif, serta pencocokan wajah lintas sesi terhadap riwayat dan daftar blokir aplikasi Anda. Laporan dibuat setelah pengguna menyelesaikan langkah deteksi liveness dalam alur kerja (atau memanggil endpoint wajah mandiri). Didit menjalankan salah satu dari tiga metode liveness (3D aktif, kedipan cahaya, atau pasif), menilai hasil pengambilan gambar, menyaring pola spoofing yang telah diketahui, dan membandingkan wajah secara biometrik terhadap setiap wajah lain yang pernah terlihat di aplikasi Anda. Setiap laporan memiliki status tersendiri — terpisah dari status sesi secara keseluruhan — yang mencerminkan hasil penyelesaian langkah deteksi liveness itu sendiri:

Disetujui — wajah terdeteksi, skor liveness di atas ambang batas peninjauan, tidak ada peringatan penolakan otomatis yang terpicu.
Dalam Peninjauan — satu atau beberapa peringatan yang diarahkan ke peninjauan terpicu, atau skor berada pada atau di bawah ambang batas peninjauan namun di atas ambang batas penolakan.
Ditolak — kondisi penolakan otomatis terpicu (NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, FACE_IN_BLOCKLIST, atau risiko usia pada alur estimasi usia), peringatan yang dapat dikonfigurasi diarahkan ke penolakan, atau skor berada pada atau di bawah ambang batas penolakan.
Belum Selesai — pengguna tidak pernah menyelesaikan langkah deteksi liveness.

Di mana laporan ini muncul dalam respons API

Laporan deteksi liveness muncul sebagai liveness_checks[] pada GET /v3/session/{sessionId}/decision/ — selalu berupa array JSON, tidak pernah berupa objek liveness tunggal. Beberapa entri akan muncul jika alur kerja menjalankan deteksi liveness lebih dari satu kali (misalnya pemeriksaan utama ditambah pengambilan gambar ulang).

API keputusan sesi — GET /v3/session/{sessionId}/decision/ mengembalikan liveness_checks[] di tingkat teratas. Lihat Ambil keputusan sesi.
Webhook — payload session.status.updated menyertakan array liveness_checks[] yang sama setelah langkah tersebut menghasilkan data. Lihat Webhook.
API Liveness Mandiri — lihat API Liveness Mandiri.

Baca response.liveness_checks[0] dan lakukan iterasi pada array tersebut — bentuk liveness tunggal yang dirujuk oleh beberapa tutorial lama tidak ada pada endpoint keputusan v3.

Skema

Skema per kolom kanonik terdapat di halaman referensi Model data. Kolom-kolom di bawah ini mencerminkan skema kanonik tersebut.

Kolom	Tipe	Deskripsi
`status`	`"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"`	Status langkah liveness (lihat di bawah).
`node_id`	string \| null	Node graf alur kerja yang menghasilkan laporan ini.
`method`	`"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"`	Metode liveness yang menghasilkan pengambilan gambar ini.
`score`	number 0–100 \| null	Skor keyakinan liveness, dibulatkan ke 2 desimal.
`reference_image`	string (signed URL) \| null	Swafoto referensi yang diekstrak dari hasil pengambilan. URL bertanda tangan dengan masa berlaku terbatas.
`video_url`	string (signed URL) \| null	Video pengambilan Deteksi Liveness lengkap (metode aktif). URL bertanda tangan dengan masa berlaku terbatas.
`age_estimation`	number \| null	Estimasi usia dalam tahun untuk wajah terbesar di gambar referensi.
`face_quality`	number 0–100 \| null	Kualitas wajah pada liveness pasif, dinormalisasi menjadi persentase. Terisi hanya jika `method = "PASSIVE"`.
`face_luminance`	number 0–100 \| null	Luminansi wajah pada liveness pasif, dinormalisasi dari 0–255 menjadi persentase. Terisi hanya jika `method = "PASSIVE"`.
`matches[]`	array	Pencocokan Wajah lintas sesi (lihat di bawah).
`warnings[]`	array	Peringatan tingkat modul — lihat Peringatan liveness. Setiap entri mengikuti bentuk Objek peringatan (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`).

Pencocokan Wajah lintas sesi

matches[] mencantumkan wajah dalam riwayat aplikasi Anda yang melampaui ambang batas kemiripan biometrik terhadap swafoto ini — hingga 5 entri, wajah dalam daftar blokir dan daftar izin terlebih dahulu, kemudian diurutkan berdasarkan kemiripan menurun. Kandidat yang memenuhi syarat adalah wajah dalam daftar blokir, wajah dalam daftar izin, wajah dari sesi Approved, dan wajah yang diimpor untuk pengguna vendor Anda. Wajah milik pengguna yang sama (vendor_data yang sama, atau pengguna vendor yang sama jika tersedia) dikecualikan dari seluruh pencarian — baik deteksi duplikat maupun skrining daftar blokir. Setiap entri meliputi:

Kolom	Tipe	Deskripsi
`session_id`	string (UUID) \| null	Sesi yang cocok. `null` jika `source` bernilai `imported` atau `list_entry`.
`session_number`	number \| null	Nomor sesi berurutan untuk sesi yang cocok. `null` untuk sumber non-sesi.
`similarity_percentage`	number 0–100	Skor kemiripan biometrik, dibatasi antara 0–100.
`vendor_data`	string \| null	Data referensi Anda dari sesi yang cocok (atau pengguna vendor, untuk wajah yang diimpor).
`verification_date`	string (ISO 8601) \| null	Waktu saat sesi yang cocok (atau wajah yang diimpor) dibuat.
`user_details`	object \| null	`{ full_name, document_type, document_number }` dari KYC sesi yang cocok. Wajah yang diimpor hanya mengisi `full_name` (dua kolom dokumen bernilai `null`); `null` jika tidak ada detail yang tersimpan.
`match_image_url`	string (signed URL) \| null	Wajah referensi dari sesi yang cocok, wajah yang diimpor, atau entri daftar.
`status`	string \| null	Status sesi yang cocok (misalnya `"Approved"`). `null` untuk sumber non-sesi.
`is_blocklisted`	boolean	`true` jika wajah yang cocok ada di daftar blokir wajah Anda.
`is_allowlisted`	boolean	`true` jika wajah yang cocok ada di daftar izin wajah Anda (tindakan wajah duplikat dilewati).
`api_service`	string \| null	Diatur ketika wajah yang cocok berasal dari panggilan API mandiri (misalnya `"PASSIVE_LIVENESS"`); `null` untuk sesi alur kerja dan sumber non-sesi.
`source`	`"session" \| "imported" \| "list_entry"`	Asal wajah yang cocok: sesi verifikasi lain, wajah yang diunggah untuk pengguna vendor, atau wajah daftar izin/blokir yang dikelola organisasi.

Nilai status

Status berasal dari enum status fitur bersama (FeatureStatusChoices).

Status	Arti	Efek lanjutan
`Approved`	Wajah terdeteksi, skor liveness di atas ambang batas peninjauan, tidak ada peringatan penolakan otomatis yang terpicu.	Dihitung sebagai pemeriksaan liveness yang berhasil.
`In Review`	Skor pada atau di bawah ambang batas peninjauan tetapi di atas ambang batas penolakan, atau peringatan yang diarahkan ke peninjauan terpicu.	Sesi juga beralih ke `In Review` hingga peninjau mengambil tindakan.
`Declined`	Risiko penolakan otomatis terpicu (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, atau risiko usia pada alur estimasi usia), peringatan yang dapat dikonfigurasi diarahkan ke penolakan, atau skor berada pada atau di bawah ambang batas penolakan.	Sesi ditolak kecuali ada cabang lain yang disetujui yang memenuhi alur kerja.
`Not Finished`	Pengguna meninggalkan langkah liveness (atau kegagalan pengambilan gambar yang dapat dicoba lagi sedang menunggu percobaan berikutnya).	Cabang liveness tidak menghasilkan hasil.
`Resub Requested`	Peninjau meminta pengiriman ulang langkah ini dari konsol.	Bersifat sementara — diganti setelah pengguna mengambil ulang gambar.

Contoh

Approved — pengambilan active-3D bersih

{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}

In Review — passive liveness, pengambilan berkualitas rendah, dan kemungkinan duplikat

{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}

Di sini kualitas wajah (12.4) berada di bawah ambang batas peninjauan default (15), luminansi (18.7) berada di bawah batas minimum default (20), dan tindakan wajah duplikat pada alur kerja diatur ke Peninjauan — sehingga ketiga peringatan membawa log_type: "warning" dan laporan berstatus In Review.

Catatan keamanan

Video liveness dan swafoto merupakan data biometrik — URL bertanda tangan bersifat sementara dan akan kedaluwarsa (setelah 4 jam secara default). Perlakukan video dan swafoto tersebut sebagai data berumur pendek: jangan simpan dalam cache atau tampilkan ke publik. Biasanya aplikasi Anda hanya membutuhkan status, score, dan peringatan — simpan seminimal mungkin untuk meminimalkan data biometrik di server Anda.

Terkait

Peringatan liveness — enum peringatan lengkap, penyebab, dan remediasi.
Webhook — dengarkan session.status.updated untuk menerima laporan.
Model data — Pemeriksaan liveness — skema kanonis beserta setiap kolomnya.
Laporan pencocokan wajah — pencocokan wajah 1:1 pendamping terhadap potret dokumen.

Autentikasi

Verifikasi

Pemantauan

Platform

Laporan Deteksi Liveness: Skor, Metode & Pencocokan

Gambaran Umum

Di mana laporan ini muncul dalam respons API

Skema

Pencocokan Wajah lintas sesi

Nilai status

Contoh

Approved — pengambilan active-3D bersih

In Review — passive liveness, pengambilan berkualitas rendah, dan kemungkinan duplikat

Catatan keamanan

Terkait

​Gambaran Umum

​Di mana laporan ini muncul dalam respons API

​Skema

​Pencocokan Wajah lintas sesi

​Nilai status

​Contoh

​Approved — pengambilan active-3D bersih

​In Review — passive liveness, pengambilan berkualitas rendah, dan kemungkinan duplikat

​Catatan keamanan

​Terkait

Gambaran Umum

Di mana laporan ini muncul dalam respons API

Skema

Pencocokan Wajah lintas sesi

Nilai status

Contoh

Approved — pengambilan active-3D bersih

In Review — passive liveness, pengambilan berkualitas rendah, dan kemungkinan duplikat

Catatan keamanan

Terkait