คู่มือการผสานรวม CAPTCHA บน Android
บทนำผลิตภัณฑ์
| รายการ | คำอธิบาย |
|---|---|
| คุณสมบัติหลัก | CAPTCHA รุ่นใหม่ที่สามารถแก้ไขปัญหาการสูญเสียทางธุรกิจและความเสี่ยงด้านความปลอดภัยที่เกิดจากการโจมตีอัตโนมัติจากสคริปต์ของเครื่องจักร |
| นโยบายความเป็นส่วนตัวของ SDK | นโยบาย |
| คู่มือการปฏิบัติตามข้อกำหนดของ SDK | คู่มือ |
| ลิงก์ดาวน์โหลด SDK | ดาวน์โหลด |
ข้อกำหนดของสภาพแวดล้อม
| รายการ | ทรัพยากร |
|---|---|
| เป้าหมายการพัฒนา | Android 5.0+ (minSdk 21) |
| สภาพแวดล้อมการพัฒนา | Android Studio 2020.3.1 Arctic Fox+ |
| เครื่องมือ Build | Gradle (Android Gradle Plugin 7+) |
| การพึ่งพาระบบ | ไม่มี |
การพึ่งพา Third-party ของ SDK |
ไม่มี |
| ขนาดแพ็กเกจ | ยืนยันแล้ว SDK: 60K |
การผสานรวม SDK
การนำเข้า SDK
ลากไฟล์ .aar (รวมถึง engagelab_captcha_android_vx.y.z.aar) จากแพ็กเกจ zip ไปยังโฟลเดอร์ libs ของโปรเจกต์ของคุณ หลังจากลากไฟล์ .aar ไปยังโฟลเดอร์ libs ให้แน่ใจว่าไฟล์ .aar ถูกเพิ่มใน Library เพิ่มโค้ดต่อไปนี้ในไฟล์ build.gradle ของโปรเจกต์:
repositories {
flatDir {
dirs 'libs'
}
}
เพิ่มการพึ่งพาแพ็กเกจ aar ด้วยตนเอง (AAR ไม่ได้รวมการพึ่งพา Third-party โดยอัตโนมัติ ดังนั้นคุณต้องเพิ่มด้วยตนเอง):
implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')
การตั้งค่าสำหรับโปรเจกต์ที่ไม่ใช่ Kotlin
ในไฟล์การตั้งค่าราก build.gradle:
ext.kotlin_version = "1.6.22"
dependencies {
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
ในไฟล์การตั้งค่าโมดูล build.gradle:
apply plugin: 'kotlin-android'
dependencies {
implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}
หากมีความขัดแย้งกับเวอร์ชัน
kotlinให้ยกเว้นการพึ่งพาkotlinโดยใช้exclude(group: 'org.jetbrains.kotlin')
เพิ่มสิทธิ์
<!--จำเป็น - ใช้โดยค่าเริ่มต้น-->
<uses-permission android:name="android.permission.INTERNET" />
<!--ต้องระบุเพื่อความเข้ากันได้กับ API 23 (ไม่รวม) และต่ำกว่า (เช่น แอปพลิเคชันที่รันบน Android 4.x และ 5.x ต้องระบุสิ่งนี้) - ไม่ได้ใช้โดยค่าเริ่มต้น-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
กฎ ProGuard
แพ็กเกจ aar ของ SDK ได้ถูกทำการ obfuscate แล้ว การ obfuscate ซ้ำอาจนำไปสู่ข้อผิดพลาดที่ไม่คาดคิด โดยค่าเริ่มต้น แพ็กเกจ aar รวมการตั้งค่า obfuscate ของ SDK ปัจจุบันเพื่อให้แน่ใจว่า SDK จะไม่ถูก obfuscate ซ้ำ ไม่ว่าจะใช้การพึ่งพาระยะไกลหรือ aar ท้องถิ่น หากคุณต้องการแยกแพ็กเกจ aar และผสานรวมไฟล์ jar และทรัพยากรแยกต่างหาก ให้แน่ใจว่าคุณคัดลอกเนื้อหาของไฟล์ proguard.txt จากไดเรกทอรีที่แยกออกมาไปยังการตั้งค่า ProGuard ของแอปพลิเคชันของคุณเพื่อหลีกเลี่ยงการ obfuscate ซ้ำของ SDK
หากคุณใช้ andRes สำหรับการ obfuscate ทรัพยากร ให้ยกเว้นทรัพยากรที่รวมอยู่ใน SDK จากการ obfuscate เพื่อหลีกเลี่ยงข้อผิดพลาดที่เกิดจากการขาดทรัพยากร การตั้งค่ายกเว้นมีดังนี้:
"R.string.gt4_*",
"R.style.gt4_*",
การตั้งค่าการเชื่อมต่ออินเทอร์เฟซ
ลอจิกการเรียก
- ตั้งค่าการเริ่มต้น
- เริ่มการยืนยัน
- รับ Callback การยืนยัน
- ทำลายทรัพยากร
อ้างอิง โครงสร้างกระบวนการผลิตภัณฑ์ สำหรับการยืนยันพฤติกรรม คุณต้องตั้งค่าอินเทอร์เฟซฝั่งเซิร์ฟเวอร์ที่สอดคล้องกันบนแบ็กเอนด์ของคุณและกำหนดค่า
captchaIdและKeyที่ได้รับจาก EngageLab Management Console
การเริ่มต้น
การตั้งค่าเริ่มต้นของ SDK สามารถทำได้ในเมธอด onCreate หรือ onCreateView
คำอธิบายเมธอด
public static GTCaptcha4Client getClient(Context context);
public GTCaptcha4Client init(String captchaId);
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)
คำอธิบายพารามิเตอร์
| พารามิเตอร์ | ประเภท | คำอธิบาย |
|---|---|---|
context |
Context |
วัตถุ Context ต้องเป็นอินสแตนซ์ของ Activity |
appId |
String |
APP_ID พารามิเตอร์ที่จำเป็น |
config |
GTCaptcha4Config |
วัตถุการตั้งค่า, ไม่จำเป็น |
เมธอด
init()จะเริ่มการโหลดล่วงหน้า หากเริ่มต้นในเมธอดonCreateหรือonCreateViewกระบวนการยืนยันจะถูกโหลดล่วงหน้า ทำให้การยืนยันเร็วขึ้น หากเรียกinit()ในเวลาการยืนยัน ความเร็วในการโหลดจะช้ากว่าการโหลดล่วงหน้า ขอแนะนำให้เริ่มต้นในเมธอดonCreateหรือonCreateView
เริ่มการยืนยัน
เริ่มกระบวนการยืนยัน
คำอธิบายเมธอด
public void verifyWithCaptcha();
ยกเลิกการยืนยัน
ยกเลิกกระบวนการยืนยันและปิดหน้าต่างการยืนยัน
คำอธิบายเมธอด
public void cancel();
เปิด/ปิดการตรวจสอบ Log
ตั้งค่าว่าจะเปิดหรือปิดการตรวจสอบ Log
คำอธิบายเมธอด
public void setLogEnable(boolean enable);
รับ Callback การยืนยัน
public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);
public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);
ตัวอย่างโค้ด
gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
@Override
public void onSuccess(boolean status, String response) {
if(status){
// TODO เริ่มการยืนยันขั้นที่สอง
}else {
// TODO การยืนยันคำตอบของผู้ใช้ล้มเหลว
}
}
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
@Override
public void onFailure(String error) {
}
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
@Override
public void onWebViewShow() {
}
})
ทำลายทรัพยากร
ทำลายทรัพยากรในวงจรชีวิต onDestroy
public void onDestroy(){
super.onDestroy();
if(gtCaptcha4Client != null){
gtCaptcha4Client.destroy();
}
}
จัดการการเปลี่ยนแปลงการวางแนวหน้าจอ
@Override
public void onConfigurationChanged(Configuration newConfig) {
super.onConfigurationChanged(newConfig);
if(gtCaptcha4Client != null){
gtCaptcha4Client.configurationChanged(newConfig);
}
}
ตัวอย่างโค้ดการโหลดล่วงหน้า
@Override
public void onViewCreated(View view, Bundle savedInstanceState){
super.onViewCreated(view, savedInstanceState);
String[] apiServers = {"captcha-api.engagelab.com"};
String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
GTCaptcha4Config config = new GTCaptcha4Config.Builder()
// ตั้งค่าที่อยู่บริการ
.setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
.setApiServers(apiServers)
.setStaticServers(staticServers)
.setDebug(true) // TODO ปิดในโปรดักชัน
.setLanguage("zh")
.setTimeOut(10000)
.setCanceledOnTouchOutside(true)
.build();
gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
.init("your captcha_id", config);
}
private void click(){
gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {
@Override
public void onSuccess(boolean status, String response) {
if(status){
// TODO เริ่มการยืนยันขั้นที่สอง
}else {
// TODO การยืนยันคำตอบของผู้ใช้ล้มเหลว
}
}
})
.addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
@Override
public void onFailure(String error) {
}
})
.verifyWithCaptcha();
}
ตัวอย่างโค้ดการโหลดปกติ
private void click(){
String[] apiServers = {"captcha-api.engagelab.com"};
String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
GTCaptcha4Config config = new GTCaptcha4Config.Builder()
// ตั้งค่าที่อยู่บริการ
.setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
.setApiServers(apiServers)
.setStaticServers(staticServers)
.setDebug(true) // TODO ปิดในโปรดักชัน
.setLanguage("zh")
.setTimeOut(10000)
.setCanceledOnTouchOutside(true)
.build();
gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
.init("your captcha_id", config)
.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {
@Override
public void onSuccess(boolean status, String response) {
if(status){
// TODO เริ่มการยืนยันขั้นที่สอง
}else {
// TODO การยืนยันคำตอบของผู้ใช้ล้มเหลว
}
}
})
.addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
@Override
public void onFailure(String error) {
}
})
.verifyWithCaptcha();
}
อ้างอิงตัวอย่างโค้ดจาก Demo อย่างเป็นทางการสำหรับรายละเอียดเพิ่มเติม
การตั้งค่าพารามิเตอร์
ตั้งค่าพารามิเตอร์โดยใช้คลาส GTCaptcha4Config.Builder
| การกำหนด | คำอธิบาย |
|---|---|
setResourcePath |
ต้องตั้งค่าเป็น: https://captcha-stat.engagelab.com/www/gt4-index.html |
setApiServers |
ต้องตั้งค่าเป็น: captcha-api.engagelab.com |
setStaticServers |
ต้องตั้งค่าเป็น: captcha-stat.engagelab.com/www/js |
setParams |
พารามิเตอร์เพิ่มเติม, ส่งไปยัง js ฝั่งหน้าเพื่อใช้งาน |
setDebug |
อยู่ในโหมด debug หรือไม่, ค่าเริ่มต้นคือ false, ตั้งค่าเป็น false ในโปรดักชัน |
setLanguage |
ระบุภาษา, ค่าเริ่มต้นคือภาษาของแอปพลิเคชัน |
setCanceledOnTouchOutside |
ปิดเมื่อสัมผัสภายนอกหรือไม่, ค่าเริ่มต้นคือ true |
setTimeOut |
ตั้งค่า timeout, หน่วยคือ ms, ค่าเริ่มต้นคือ 10000 |
setBackgroundColor |
ตั้งค่าสีพื้นหลัง, ค่าเริ่มต้นคือโปร่งใส |
setDialogStyle |
ตั้งค่าธีมสไตล์ของ dialog, ค่าเริ่มต้นคือ gt4_captcha_dialog_style |
setDialogShowListener |
ตั้งค่าการเรียกกลับของการแสดง dialog |
build |
สร้างวัตถุ GTCaptcha4Config |
พารามิเตอร์สามารถตั้งค่าได้ผ่านอินเทอร์เฟซ setParams อ้างอิงเอกสารอินเทอร์เฟซสำหรับรายละเอียด
อินเทอร์เฟซ
setParamsยอมรับเฉพาะประเภทข้อมูลพื้นฐาน, สตริง, และประเภทข้อมูลJSONArray
การจัดการข้อผิดพลาด
ข้อผิดพลาดที่ไม่คาดคิดอาจเกิดขึ้นระหว่างการยืนยัน คุณสามารถจัดการได้โดยการใช้อินเทอร์เฟซ addOnFailureListener และใช้เมธอดการเรียกกลับด้านล่าง:
หมายเหตุ: การเรียกกลับข้อผิดพลาดรวมถึงการยกเลิกการยืนยันโดยผู้ใช้ ซึ่งสามารถกรองออกแยกต่างหากได้
gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
@Override
public void onFailure(String error){
// ตัวอย่างเนื้อหาข้อผิดพลาดที่ส่งกลับ
// {"code":"-14460","msg":"Verification session canceled","desc":{"description":"User cancelled 'Captcha'"}}
// คุณสามารถแปลงข้อผิดพลาดเป็น JSON, แทนที่คำอธิบายข้อผิดพลาด, และเก็บรหัสข้อผิดพลาดไว้
Toast.makeText(context, "Verification Error: $error", Toast.LENGTH_SHORT).show()
}
แนะนำอย่างยิ่งให้แสดงรหัสข้อผิดพลาดพร้อมเหตุผลข้อผิดพลาดให้ผู้ใช้เพื่อการแก้ปัญหาออนไลน์ที่ง่ายขึ้น
อ้างอิงรายการรหัสข้อผิดพลาดที่เป็นไปได้: รายการรหัสข้อผิดพลาด










