คู่มือการผสานรวม 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' } }
              
              repositories {
    flatDir {
        dirs 'libs'
    }
}

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

เพิ่มการพึ่งพาแพ็กเกจ aar ด้วยตนเอง (AAR ไม่ได้รวมการพึ่งพา Third-party โดยอัตโนมัติ ดังนั้นคุณต้องเพิ่มด้วยตนเอง):

implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')
              
              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" }
              
              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" }
              
              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" />
              
              <!--จำเป็น - ใช้โดยค่าเริ่มต้น-->
<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_*",
              
              "R.string.gt4_*",
"R.style.gt4_*",

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

การตั้งค่าการเชื่อมต่ออินเทอร์เฟซ

ลอจิกการเรียก

  1. ตั้งค่าการเริ่มต้น
  2. เริ่มการยืนยัน
  3. รับ Callback การยืนยัน
  4. ทำลายทรัพยากร

อ้างอิง โครงสร้างกระบวนการผลิตภัณฑ์ สำหรับการยืนยันพฤติกรรม คุณต้องตั้งค่าอินเทอร์เฟซฝั่งเซิร์ฟเวอร์ที่สอดคล้องกันบนแบ็กเอนด์ของคุณและกำหนดค่า 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)
              
              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 verifyWithCaptcha();

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

ยกเลิกการยืนยัน

ยกเลิกกระบวนการยืนยันและปิดหน้าต่างการยืนยัน

คำอธิบายเมธอด

public void cancel();
              
              public void cancel();

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

เปิด/ปิดการตรวจสอบ Log

ตั้งค่าว่าจะเปิดหรือปิดการตรวจสอบ Log

คำอธิบายเมธอด

public void setLogEnable(boolean enable);
              
              public void setLogEnable(boolean enable);

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

รับ Callback การยืนยัน

public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener); public GTCaptcha4Client addOnFailureListener(OnFailureListener listener); public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);
              
              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() { } })
              
              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(); } }
              
              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 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(); }
              
              @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(); }
              
              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() }
              
              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()
    }

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

แนะนำอย่างยิ่งให้แสดงรหัสข้อผิดพลาดพร้อมเหตุผลข้อผิดพลาดให้ผู้ใช้เพื่อการแก้ปัญหาออนไลน์ที่ง่ายขึ้น

อ้างอิงรายการรหัสข้อผิดพลาดที่เป็นไปได้: รายการรหัสข้อผิดพลาด

icon
ติดต่อฝ่ายขาย