Panduan Integrasi
Integrasikan Face API ke Stack Anda
Python Face API ini berjalan sebagai AI microservice. Backend utama (Express.js) dan aplikasi mobile (Flutter / Android / iOS) tidak perlu tahu cara kerja AI-nya â cukup kirim foto, terima embedding atau hasil verifikasi.
đī¸ Arsitektur Microservice
Flutter / Android / iOS
â kirim foto (multipart)
âŧ
Express.js âââ Backend Utama (auth, JWT, bisnis)
â â
â ââââļ PostgreSQL / Supabase (simpan embedding, presensi)
â â
ââââââââââââļ Python Face API (AI saja: extract + compare)
port 8080 â internal only, tidak terekspos
Keuntungan: Python API tidak perlu dibuka ke internet. Mobile app hanya punya 1 backend URL. Embedding disimpan di database sendiri â bukan di SQLite Python.
Alur Daftar Wajah
1
Mobile kirim foto ke Express.js
multipart/form-data, field
photo2
Express â
POST /api/extract-embeddingPython ekstrak 512-dim embedding + liveness check
3
Express simpan embedding ke DB sendiri
Kolom
JSONB atau vector(512) di PostgreSQL/SupabaseAlur Presensi (1:N Identification)
1
Mobile kirim foto ke Express.js
Sudah include liveness frame jika dibutuhkan
2
Express â
POST /api/extract-embeddingPython return embedding +
is_live + antispoof3
Express query embedding semua karyawan dari DB
Loop â
POST /api/compare-embeddings per user, atau pakai pgvector4
Express catat presensi, balas mobile
Insert ke tabel
presensi, return nama + waktu + similarityđ Endpoint Headless (Khusus Integrasi)
Dua endpoint ini tidak menyimpan data ke database Python â semua kontrol ada di backend Anda.
| Method | Endpoint | Deskripsi |
|---|---|---|
| POST | /api/extract-embedding | Ekstrak embedding 512-dim dari foto. Return embedding + liveness + antispoof. Tidak simpan ke DB. |
| POST | /api/compare-embeddings | Bandingkan dua embedding. Input: JSON array float[512] Ã 2. Return similarity + is_match. |
| POST | /api/register | Daftar + simpan ke SQLite Python (opsional, jika tidak mau urus DB sendiri) |
| POST | /api/presensi/masuk | Clock-in otomatis dengan 1:N di database Python |
POST /api/extract-embedding
request
# Form fields (multipart/form-data):
image File # upload file â atau pakai image_base64
image_base64 string # base64 / data URL
check_liveness bool # default: true
response
{
"success": true,
"embedding": [0.021, -0.134, 0.072, ...], // float[512] â simpan di DB Anda
"face_info": {
"bbox": [120, 80, 380, 420],
"det_score": 0.98,
"num_faces": 1
},
"is_live": true,
"antispoof": { "score": 0.82, "passed": true }
}
POST /api/compare-embeddings
request
embedding1 string # JSON.stringify(float[512])
embedding2 string # JSON.stringify(float[512])
threshold float # default: 0.30
response
{
"success": true,
"similarity": 0.6821,
"similarity_pct": 68.2,
"is_match": true,
"confidence": "TINGGI", // TINGGI / SEDANG / RENDAH / TIDAK_COCOK
"threshold": 0.30
}
đĸ Express.js
bash
npm install express multer axios form-data pg dotenv
.env
FACE_API_URL=http://localhost:8080 # internal â tidak terekspos ke internet
DATABASE_URL=postgresql://user:pass@localhost:5432/presensi
PORT=3000
javascript
// services/faceService.js
const axios = require('axios');
const FormData = require('form-data');
const FACE_API = process.env.FACE_API_URL;
async function extractEmbedding(imageBuffer, mime = 'image/jpeg') {
const form = new FormData();
form.append('image', imageBuffer, { filename: 'face.jpg', contentType: mime });
form.append('check_liveness', 'true');
const { data } = await axios.post(`${FACE_API}/api/extract-embedding`,
form, { headers: form.getHeaders(), timeout: 15000 });
if (!data.success) throw new Error(data.error);
return data;
}
async function compareEmbeddings(emb1, emb2, threshold = 0.30) {
const form = new FormData();
form.append('embedding1', JSON.stringify(emb1));
form.append('embedding2', JSON.stringify(emb2));
form.append('threshold', String(threshold));
const { data } = await axios.post(`${FACE_API}/api/compare-embeddings`,
form, { headers: form.getHeaders(), timeout: 5000 });
if (!data.success) throw new Error(data.error);
return data;
}
module.exports = { extractEmbedding, compareEmbeddings };
javascript
// POST /karyawan/daftar
router.post('/daftar', upload.single('photo'), async (req, res) => {
const { user_id, name, email } = req.body;
try {
const ext = await face.extractEmbedding(req.file.buffer);
if (!ext.is_live)
return res.status(400).json({ ok: false, error: 'Gunakan wajah asli' });
await pool.query(
`INSERT INTO karyawan(user_id,name,email,embedding)
VALUES($1,$2,$3,$4)
ON CONFLICT(user_id) DO UPDATE SET embedding=$4, updated_at=NOW()`,
[user_id, name, email, JSON.stringify(ext.embedding)]
);
res.json({ ok: true, message: `Wajah ${name} berhasil didaftarkan` });
} catch (e) {
res.status(500).json({ ok: false, error: e.message });
}
});
javascript
// POST /presensi/:tipe (masuk | keluar)
router.post('/:tipe(masuk|keluar)', upload.single('photo'), async (req, res) => {
const { tipe } = req.params;
const ext = await face.extractEmbedding(req.file.buffer);
if (!ext.is_live)
return res.status(400).json({ ok: false, error: 'Liveness gagal' });
const { rows } = await pool.query(
'SELECT user_id, name, embedding FROM karyawan WHERE is_active=true'
);
let best = null, bestSim = 0;
for (const row of rows) {
const cmp = await face.compareEmbeddings(ext.embedding, JSON.parse(row.embedding));
if (cmp.similarity > bestSim) { bestSim = cmp.similarity; best = { ...row, ...cmp }; }
}
if (!best?.is_match)
return res.status(404).json({ ok: false, error: 'Wajah tidak dikenali' });
await pool.query(
'INSERT INTO presensi(user_id,tipe,similarity,waktu) VALUES($1,$2,$3,NOW())',
[best.user_id, tipe, best.similarity]
);
res.json({ ok: true, name: best.name, similarity_pct: best.similarity_pct });
});
đĻ Flutter
Flutter memanggil Express.js, bukan Python langsung. Paket kamera yang digunakan:
camera (live preview) + image_picker (galeri/kamera cepat).yaml
# pubspec.yaml
dependencies:
flutter:
sdk: flutter
http: ^1.2.1
camera: ^0.11.0
image_picker: ^1.1.2
permission_handler: ^11.3.1
path_provider: ^2.1.3
dio: ^5.6.0 # alternatif http â lebih mudah untuk multipart
flutter_secure_storage: ^9.2.2 # simpan JWT token
provider: ^6.1.2 # state management
dart
// lib/services/face_service.dart
import 'dart:io';
import 'package:dio/dio.dart';
class PresensiResult {
final bool ok;
final String? name;
final double? similarityPct;
final String? waktu;
final String? error;
PresensiResult({
required this.ok, this.name, this.similarityPct,
this.waktu, this.error,
});
factory PresensiResult.fromJson(Map<String, dynamic> j) => PresensiResult(
ok: j['ok'] ?? false,
name: j['name'],
similarityPct: (j['similarity_pct'] as num?)?.toDouble(),
waktu: j['waktu'],
error: j['error'],
);
}
class DaftarResult {
final bool ok;
final String? message;
final String? error;
DaftarResult({required this.ok, this.message, this.error});
factory DaftarResult.fromJson(Map j) =>
DaftarResult(ok: j['ok'] ?? false, message: j['message'], error: j['error']);
}
class FaceService {
static const _base = 'https://your-express-api.com'; // ganti URL Express.js
static final _dio = Dio(BaseOptions(
baseUrl: _base,
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 30),
));
// --- Daftar wajah baru ---
static Future<DaftarResult> daftarWajah({
required File photo,
required String userId,
required String name,
String? email,
}) async {
final form = FormData.fromMap({
'user_id': userId,
'name': name,
if (email != null) 'email': email,
'photo': await MultipartFile.fromFile(
photo.path, filename: 'face.jpg',
contentType: DioMediaType('image', 'jpeg'),
),
});
final res = await _dio.post('/karyawan/daftar', data: form);
return DaftarResult.fromJson(res.data);
}
// --- Presensi masuk / keluar ---
static Future<PresensiResult> presensi({
required File photo,
required String tipe, // 'masuk' | 'keluar'
String? deviceId,
String? location,
}) async {
final form = FormData.fromMap({
'photo': await MultipartFile.fromFile(
photo.path, filename: 'face.jpg',
contentType: DioMediaType('image', 'jpeg'),
),
if (deviceId != null) 'device_id': deviceId,
if (location != null) 'location': location,
});
final res = await _dio.post('/presensi/$tipe', data: form);
return PresensiResult.fromJson(res.data);
}
}
dart
// lib/screens/daftar_screen.dart
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:image_picker/image_picker.dart';
import '../services/face_service.dart';
class DaftarScreen extends StatefulWidget {
const DaftarScreen({super.key});
@override
State<DaftarScreen> createState() => _DaftarScreenState();
}
class _DaftarScreenState extends State<DaftarScreen> {
final _ctrlName = TextEditingController();
final _ctrlUserId = TextEditingController();
final _ctrlEmail = TextEditingController();
File? _photo;
bool _loading = false;
String? _msg;
Future<void> _ambilFoto() async {
final picked = await ImagePicker().pickImage(
source: ImageSource.camera,
preferredCameraDevice: CameraDevice.front,
imageQuality: 90,
);
if (picked != null) setState(() => _photo = File(picked.path));
}
Future<void> _daftar() async {
if (_photo == null) return;
setState(() { _loading = true; _msg = null; });
try {
final res = await FaceService.daftarWajah(
photo: _photo!,
userId: _ctrlUserId.text.trim(),
name: _ctrlName.text.trim(),
email: _ctrlEmail.text.trim(),
);
setState(() => _msg = res.ok ? 'â
${res.message}' : 'â ${res.error}');
} catch (e) {
setState(() => _msg = 'Error: $e');
} finally {
setState(() => _loading = false);
}
}
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Daftar Wajah')),
body: Padding(
padding: const EdgeInsets.all(20),
child: Column(children: [
TextField(controller: _ctrlUserId, decoration: const InputDecoration(labelText: 'User ID / NIP')),
const SizedBox(height: 12),
TextField(controller: _ctrlName, decoration: const InputDecoration(labelText: 'Nama Lengkap')),
const SizedBox(height: 12),
TextField(controller: _ctrlEmail, decoration: const InputDecoration(labelText: 'Email (opsional)')),
const SizedBox(height: 20),
GestureDetector(
onTap: _ambilFoto,
child: _photo != null
? ClipOval(child: Image.file(_photo!, width: 120, height: 120, fit: BoxFit.cover))
: Container(
width: 120, height: 120,
decoration: BoxDecoration(
shape: BoxShape.circle,
border: Border.all(color: Colors.grey),
),
child: const Icon(Icons.camera_alt, size: 40),
),
),
const SizedBox(height: 20),
SizedBox(width: double.infinity,
child: ElevatedButton(
onPressed: _loading ? null : _daftar,
child: _loading
? const CircularProgressIndicator()
: const Text('Daftarkan Wajah'),
),
),
if (_msg != null) ...[
const SizedBox(height: 16),
Text(_msg!, textAlign: TextAlign.center),
],
]),
),
);
}
dart
// lib/screens/presensi_screen.dart
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:image_picker/image_picker.dart';
import '../services/face_service.dart';
class PresensiScreen extends StatefulWidget {
const PresensiScreen({super.key});
@override
State<PresensiScreen> createState() => _PresensiScreenState();
}
class _PresensiScreenState extends State<PresensiScreen> {
bool _loading = false;
PresensiResult? _result;
String? _selectedTipe = 'masuk';
Future<void> _jalankanPresensi() async {
final picked = await ImagePicker().pickImage(
source: ImageSource.camera,
preferredCameraDevice: CameraDevice.front,
imageQuality: 90,
);
if (picked == null) return;
setState(() { _loading = true; _result = null; });
try {
final res = await FaceService.presensi(
photo: File(picked.path),
tipe: _selectedTipe!,
);
setState(() => _result = res);
} catch (e) {
setState(() => _result = PresensiResult(ok: false, error: e.toString()));
} finally {
setState(() => _loading = false);
}
}
@override
Widget build(BuildContext context) {
final res = _result;
return Scaffold(
appBar: AppBar(title: const Text('Presensi Wajah')),
body: Padding(
padding: const EdgeInsets.all(24),
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
// Pilih tipe masuk / keluar
SegmentedButton<String>(
segments: const [
ButtonSegment(value: 'masuk', label: Text('Masuk'), icon: Icon(Icons.login)),
ButtonSegment(value: 'keluar', label: Text('Keluar'), icon: Icon(Icons.logout)),
],
selected: {_selectedTipe!},
onSelectionChanged: (s) => setState(() => _selectedTipe = s.first),
),
const SizedBox(height: 32),
// Tombol ambil foto & proses
SizedBox(
width: 180, height: 180,
child: ElevatedButton(
onPressed: _loading ? null : _jalankanPresensi,
style: ElevatedButton.styleFrom(shape: const CircleBorder()),
child: _loading
? const CircularProgressIndicator(color: Colors.white)
: Column(mainAxisAlignment: MainAxisAlignment.center, children: [
const Icon(Icons.face, size: 56),
Text(_selectedTipe == 'masuk' ? 'Tap Masuk' : 'Tap Keluar'),
]),
),
),
const SizedBox(height: 32),
// Hasil
if (res != null)
Card(
color: res.ok ? Colors.green.shade900 : Colors.red.shade900,
shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)),
child: Padding(
padding: const EdgeInsets.all(20),
child: Column(children: [
Text(res.ok ? 'â
${res.name}' : 'â ${res.error}',
style: const TextStyle(fontSize: 18, fontWeight: FontWeight.bold, color: Colors.white)),
if (res.ok) ...[
const SizedBox(height: 8),
Text('Kecocokan: ${res.similarityPct?.toStringAsFixed(1)}%',
style: const TextStyle(color: Colors.white70)),
Text('Waktu: ${res.waktu}',
style: const TextStyle(color: Colors.white70)),
],
]),
),
),
],
),
),
);
}
}
xml â AndroidManifest.xml
<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-feature android:name="android.hardware.camera"/>
plist â Info.plist (iOS)
<!-- ios/Runner/Info.plist -->
<key>NSCameraUsageDescription</key>
<string>Kamera digunakan untuk presensi wajah</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Akses galeri untuk foto profil</string>
dart â request permission
import 'package:permission_handler/permission_handler.dart';
Future<bool> requestCamera() async {
final status = await Permission.camera.request();
return status.isGranted;
}
đ¤ Android Studio (Kotlin)
groovy
dependencies {
implementation 'com.squareup.retrofit2:retrofit:2.11.0'
implementation 'com.squareup.retrofit2:converter-gson:2.11.0'
implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
implementation 'androidx.camera:camera-camera2:1.3.4'
implementation 'androidx.camera:camera-lifecycle:1.3.4'
implementation 'androidx.camera:camera-view:1.3.4'
implementation 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.3'
}
kotlin
// data/ExpressApi.kt
interface ExpressApi {
@Multipart @POST("karyawan/daftar")
suspend fun daftar(
@Part("user_id") userId: RequestBody,
@Part("name") name: RequestBody,
@Part photo: MultipartBody.Part
): Response<ApiResult>
@Multipart @POST("presensi/{tipe}")
suspend fun presensi(
@Path("tipe") tipe: String,
@Part photo: MultipartBody.Part
): Response<PresensiResult>
}
data class PresensiResult(
val ok: Boolean,
val name: String?,
val similarity_pct: Double?,
val waktu: String?,
val error: String?
)
kotlin
class PresensiViewModel : ViewModel() {
val result = MutableLiveData<PresensiResult?>()
val loading = MutableLiveData(false)
fun presensi(bitmap: Bitmap, tipe: String) = viewModelScope.launch {
loading.postValue(true)
val stream = ByteArrayOutputStream()
bitmap.compress(Bitmap.CompressFormat.JPEG, 90, stream)
val body = stream.toByteArray()
.toRequestBody("image/jpeg".toMediaType())
val part = MultipartBody.Part
.createFormData("photo", "face.jpg", body)
val resp = api.presensi(tipe, part)
result.postValue(resp.body())
loading.postValue(false)
}
}
đ iOS Swift
swift
import Foundation; import UIKit
struct PresensiResult: Codable {
let ok: Bool; let name: String?
let similarity_pct: Double?; let waktu: String?; let error: String?
}
class FaceService {
static let shared = FaceService()
private let base = "https://your-express-api.com"
func presensi(image: UIImage, tipe: String,
completion: @escaping (Result<PresensiResult, Error>) -> Void) {
guard let jpeg = image.jpegData(compressionQuality: 0.9) else { return }
let url = URL(string: "\(base)/presensi/\(tipe)")!
var req = URLRequest(url: url); req.httpMethod = "POST"
let b = "Boundary-\(UUID().uuidString)"
req.setValue("multipart/form-data; boundary=\(b)", forHTTPHeaderField: "Content-Type")
var body = Data()
body += "--\(b)\r\nContent-Disposition: form-data; name=\"photo\"; filename=\"face.jpg\"\r\nContent-Type: image/jpeg\r\n\r\n".data(using: .utf8)!
body += jpeg
body += "\r\n--\(b)--\r\n".data(using: .utf8)!
req.httpBody = body
URLSession.shared.dataTask(with: req) { data, _, err in
if let e = err { completion(.failure(e)); return }
let r = try! JSONDecoder().decode(PresensiResult.self, from: data!)
completion(.success(r))
}.resume()
}
}
swift
@IBAction func btnMasukTapped(_ sender: Any) {
guard let photo = capturedImage else { return }
FaceService.shared.presensi(image: photo, tipe: "masuk") { result in
DispatchQueue.main.async {
switch result {
case .success(let r) where r.ok:
self.label.text = "â
\(r.name ?? "") â \(r.similarity_pct ?? 0)%"
case .success(let r):
self.label.text = "â \(r.error ?? "Gagal")"
case .failure(let e):
self.label.text = "Error: \(e.localizedDescription)"
}
}
}
}
đī¸ Schema PostgreSQL
sql
-- Karyawan â embedding disimpan sebagai JSONB
CREATE TABLE karyawan (
id SERIAL PRIMARY KEY,
user_id TEXT UNIQUE NOT NULL,
name TEXT NOT NULL,
email TEXT,
phone TEXT,
embedding JSONB NOT NULL, -- float[512] dari /api/extract-embedding
face_image TEXT,
is_active BOOLEAN DEFAULT true,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ
);
-- Presensi
CREATE TABLE presensi (
id SERIAL PRIMARY KEY,
user_id TEXT REFERENCES karyawan(user_id),
tipe TEXT CHECK(tipe IN ('masuk','keluar')),
similarity REAL,
antispoof_score REAL,
device_id TEXT,
location TEXT,
ip_address TEXT,
waktu TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_presensi_waktu ON presensi(waktu DESC);
CREATE INDEX idx_presensi_user ON presensi(user_id, waktu DESC);
⥠Supabase + pgvector
Supabase mendukung extension pgvector â bandingkan embedding langsung di SQL, jauh lebih cepat untuk 1:N dengan banyak karyawan.
sql â Supabase SQL Editor
CREATE EXTENSION IF NOT EXISTS vector;
ALTER TABLE karyawan
ADD COLUMN emb_vec vector(512);
-- Index HNSW untuk pencarian cepat
CREATE INDEX ON karyawan
USING hnsw (emb_vec vector_cosine_ops);
sql
-- Cari wajah paling mirip (1:N langsung di DB, sangat cepat)
SELECT
user_id, name,
1 - (emb_vec <=> '[0.021,-0.134,0.072,...]'::vector) AS similarity
FROM karyawan
WHERE is_active = true
AND 1 - (emb_vec <=> '[...]'::vector) > 0.30 -- threshold
ORDER BY emb_vec <=> '[...]'::vector
LIMIT 1;
javascript
const { createClient } = require('@supabase/supabase-js');
const sb = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_KEY);
// Daftar: simpan embedding sebagai array biasa (Supabase konversi ke vector)
await sb.from('karyawan').upsert({
user_id: userId,
name: name,
emb_vec: extracted.embedding, // float[] langsung
});
// Presensi 1:N â pakai RPC yang wraps query pgvector di atas
const { data } = await sb.rpc('cari_wajah', {
query_emb: extracted.embedding,
threshold: 0.30,
});
// data[0] = { user_id, name, similarity }
Tanpa pgvector: loop compare satu per satu di Node.js masih cukup untuk <200 karyawan. Untuk >500 karyawan, pgvector atau Redis cache embedding sangat disarankan.