logoDokumen
Cari

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.

Diagram proses normal kode verifikasi

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.

Diagram proses offline kode verifikasi

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.

Diagram proses downgrade kustom

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:

  1. 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.
  2. 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);
              
              String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);

            
Tampilkan blok kode ini di jendela mengambang
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" }
              
              {
    "lot_number": "f26d13345c9980c7705b9111b9398a0f",
    "captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
    "sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
    "pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
    "gen_time": "1684826917",
    "captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}

            
Tampilkan blok kode ini di jendela mengambang
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" } }
              
              {
    "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"
    }
}

            
Tampilkan blok kode ini di jendela mengambang

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(); } }
              
              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();
    }
}

            
Tampilkan blok kode ini di jendela mengambang
icon
Hubungi Sales