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 photo
2
Express → POST /api/extract-embedding
Python ekstrak 512-dim embedding + liveness check
3
Express simpan embedding ke DB sendiri
Kolom JSONB atau vector(512) di PostgreSQL/Supabase

Alur Presensi (1:N Identification)

1
Mobile kirim foto ke Express.js
Sudah include liveness frame jika dibutuhkan
2
Express → POST /api/extract-embedding
Python return embedding + is_live + antispoof
3
Express query embedding semua karyawan dari DB
Loop → POST /api/compare-embeddings per user, atau pakai pgvector
4
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.

MethodEndpointDeskripsi
POST/api/extract-embeddingEkstrak embedding 512-dim dari foto. Return embedding + liveness + antispoof. Tidak simpan ke DB.
POST/api/compare-embeddingsBandingkan dua embedding. Input: JSON array float[512] × 2. Return similarity + is_match.
POST/api/registerDaftar + simpan ke SQLite Python (opsional, jika tidak mau urus DB sendiri)
POST/api/presensi/masukClock-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.