Akses Server
Proses Komunikasi Produk
Proses Normal
Ketika layanan verifikasi berjalan normal dan jaringan pengguna stabil, proses kode verifikasi berjalan seperti biasa. Server hanya perlu fokus pada tahap verifikasi sekunder.

Proses Pengecualian
Proses Offline pada Kode Verifikasi
Jika layanan verifikasi mengalami gangguan dan mode offline pada kode verifikasi digunakan, server tetap perlu fokus pada tahap verifikasi sekunder. Dalam situasi ini, permintaan server ke layanan kode verifikasi akan mengalami pengecualian. Disarankan untuk menangkap pengecualian tersebut dan menentukan apakah pengguna dapat melanjutkan berdasarkan kebutuhan bisnis.

Proses Downgrade Kustom (Hanya Referensi)
Jika layanan verifikasi bermasalah dan digunakan metode downgrade kustom seperti verifikasi karakter, disarankan agar server menambahkan antarmuka atau saklar untuk frontend guna menentukan metode verifikasi yang digunakan. Server dapat menggunakan antarmuka check_status dari kode verifikasi untuk mengecek status layanan.

Rencana Integrasi Kode Verifikasi di Server
Persiapan Pra-Integrasi
Silakan dapatkan resource yang diperlukan dari sisi klien integrasi. Informasi seperti alamat domain diperoleh dari kontak internal perusahaan setelah deployment selesai.
| Jenis Klien | Sumber Daya yang Diperlukan | Deskripsi Sumber Daya |
| Server | captchaId | ID skenario verifikasi, dibuat melalui konsol manajemen |
| captchaKey | KEY skenario verifikasi, dihasilkan saat membuat skenario baru di konsol, berpasangan satu-satu dengan captchaId |
Integrasi Server
Setelah pengguna menyelesaikan verifikasi di frontend, akan dihasilkan serangkaian parameter terkait kode verifikasi. Permintaan bisnis pengguna membawa parameter ini, dan backend mengirimkannya ke antarmuka verifikasi sekunder EngageLab untuk konfirmasi validitas verifikasi.
Contoh pada skenario login:
- Sebelum integrasi kode verifikasi, frontend mengirim username dan password ke antarmuka login bisnis. Sistem memeriksa kecocokan username dan password. Jika cocok, login berhasil; jika tidak, login gagal.
- Setelah integrasi kode verifikasi, frontend mengirim data bisnis dan parameter kode verifikasi ke antarmuka login bisnis. Backend membawa parameter kode verifikasi ke antarmuka verifikasi sekunder (validate) server kode verifikasi untuk mendapatkan hasil verifikasi. Berdasarkan hasil verifikasi dan kecocokan username/password, sistem menentukan apakah pengguna dapat melanjutkan proses berikutnya.
Deskripsi Antarmuka validate
| Informasi Antarmuka | Deskripsi |
|---|---|
| Alamat Antarmuka | https://captcha-api.engagelab.com/validate |
| Metode Permintaan | POST |
| Format Permintaan | application/json |
| Tipe Respons | json |
Parameter Permintaan
| Nama Parameter | Tipe | Deskripsi | Sumber |
|---|---|---|---|
| lot_number | string | Nomor seri verifikasi | Dikirim dari frontend |
| captcha_output | string | Output verifikasi | Dikirim dari frontend |
| pass_token | string | Token lolos verifikasi | Dikirim dari frontend |
| gen_time | string | Timestamp verifikasi | Dikirim dari frontend |
| captcha_id | string | ID skenario verifikasi | Konfigurasi bisnis, harus sama dengan frontend |
| sign_token | string | Tanda tangan verifikasi | Dihasilkan oleh backend bisnis |
sign_token dihasilkan dengan:
Gunakan lot_number pengguna sebagai pesan asli, captchaKey sebagai kunci, dan hash dengan algoritma hmac_sha256 untuk menghasilkan tanda tangan.
Contoh kode Java:
String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
Contoh Body Permintaan
{
"lot_number": "f26d13345c9980c7705b9111b9398a0f",
"captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
"sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
"pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
"gen_time": "1684826917",
"captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}
Parameter Respons
| Nama Parameter | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| status | String | Ya | success | Status respons, success = berhasil |
| data | Object | Ya | Lihat detail | Field yang dikembalikan jika sukses |
Deskripsi field data:
| Nama Parameter | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| result | String | Ya | success | Hasil verifikasi sekunder, success = lolos, selain itu gagal |
| reason | String | Ya | "" | Deskripsi hasil verifikasi |
| captcha_args | Object | Ya | {} | Info tambahan, berisi hasil strategi tertentu |
Penanda verifikasi lolos: field status = success dan field result = success
Parameter dalam captcha_args:
| Nama Parameter | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| model_cnn | int | Ya | 0 | Hasil model sliding track CNN, 0 = normal, 1 = abnormal |
| model_probability | int | Ya | 0 | 0 = pengguna normal, 1 = permintaan captcha (tangani khusus) |
| used_type | String | Ya | slide | Metode verifikasi yang digunakan |
| web_simulator | int | Ya | 0 | 0 = browser normal, 1 = simulator |
| user_ip | String | Ya | "127.0.0.1" | IP pengguna saat verifikasi |
| user_referer | String | Ya | "" | Referer pengguna saat verifikasi |
| cnn_records | int | Ya | 0 | Prediksi track abnormal selama proses |
| user_agent | String | Ya | "User-Agent" | User Agent pengguna saat verifikasi |
| lot_number | String | Ya | "9b57c5289e" | Nomor seri verifikasi pengguna |
Catatan: Jika model_probability = 1, maka permintaan diidentifikasi sebagai captcha abnormal. Disarankan untuk ditangani secara real-time.
Jika result = success, berarti verifikasi lolos.
Contoh Respons
{
"status": "success",
"data": {
"captcha_args": {
"cnn_records": 0,
"lot_number": "a989b864ad08cc08f270c22d9ab1fba0",
"model_cnn": 0,
"model_probability": 0,
"used_type": "slide",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, seperti Gecko) Chrome/135.0.0.0 Safari/537.36",
"user_ip": "59.174.224.96",
"user_referer": "http://127.0.0.1:5000/",
"web_simulator": 0
},
"reason": "validate success",
"result": "success"
}
}
Contoh Integrasi Kode Java
Berikut contoh kode Java pada sisi backend bisnis:
package com.engagelab.demo.controller;
import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
import org.json.JSONObject;
import org.springframework.http.*;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;
import java.util.HashMap;
import java.util.Map;
@RestController
public class MainController {
@RequestMapping(value = "/login", method = {RequestMethod.GET})
public String userLogin(@RequestParam Map<String, String> getParams) {
// 1. Inisialisasi parameter, harus sama dengan captchaId frontend atau dari file konfigurasi
String captchaId = "37830cbb24f5a2134d39c7cf3093bc14";
String captchaKey = "ab8aeb88a3c30e170ab04af8ada6e6ec";
String domain = "https://captcha-api.engagelab.com";
// 2. Ambil parameter dari frontend
String lotNumber = getParams.get("lot_number");
String captchaOutput = getParams.get("captcha_output");
String passToken = getParams.get("pass_token");
String genTime = getParams.get("gen_time");
// 3. Hasilkan sign_token
String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
// 4. Kirim parameter ke antarmuka verifikasi sekunder
Map<String, String> queryParams = new HashMap<>();
queryParams.put("captcha_id", captchaId);
queryParams.put("lot_number", lotNumber);
queryParams.put("captcha_output", captchaOutput);
queryParams.put("pass_token", passToken);
queryParams.put("gen_time", genTime);
queryParams.put("sign_token", signToken);
String url = String.format(domain + "/validate");
SimpleClientHttpRequestFactory clientHttpRequestFactory = new SimpleClientHttpRequestFactory();
clientHttpRequestFactory.setConnectTimeout(3000);
clientHttpRequestFactory.setReadTimeout(1500);
RestTemplate client = new RestTemplate();
client.setRequestFactory(clientHttpRequestFactory);
JSONObject responseJsonObject = new JSONObject();
try {
RequestEntity<Map<String, String>> requestEntity = RequestEntity.post(url).accept(MediaType.APPLICATION_JSON).body(queryParams);
ResponseEntity<String> response = client.exchange(requestEntity, String.class);
String resBody = response.getBody();
responseJsonObject = new JSONObject(resBody);
} catch (Exception e) {
responseJsonObject.put("status", "success");
responseJsonObject.put("data", new JSONObject("{\"result\": \"success\", \"reason\": \"request captcha api fail\"}"));
}
JSONObject res = new JSONObject();
String status = responseJsonObject.getString("status");
if (status.equals("success")) {
String data = responseJsonObject.getJSONObject("data").getString("result");
if (data.equals("success")) {
res.put("login", "success");
res.put("reason", responseJsonObject.getJSONObject("data").getString("reason"));
} else {
res.put("login", "fail");
res.put("reason", responseJsonObject.getJSONObject("data").getString("reason"));
}
JSONObject captchaArgs = responseJsonObject.getJSONObject("data").getJSONObject("captcha_args");
Integer model_probability = captchaArgs.getInt("model_probability");
System.out.println("Hasil pengenalan captcha: " + model_probability);
} else {
res.put("login", "fail");
res.put("reason", "captcha verify fail");
}
return res.toString();
}
}










