SafetyNet reCAPTCHA API

שירות SafetyNet כולל ממשק API של reCAPTCHA שאפשר להשתמש בו כדי להגן על האפליקציה מפני תנועה זדונית.

reCAPTCHA הוא שירות חינמי שמשתמש במנוע מתקדם לניתוח סיכונים כדי להגן על האפליקציה מפני ספאם ומפני פעולות פוגעניות אחרות. אם השירות חושד שהמשתמש שמקיים אינטראקציה עם האפליקציה הוא בוט ולא בן אדם, הוא מציג אתגר CAPTCHA שאדם צריך לפתור כדי שהאפליקציה תמשיך לפעול.

במסמך הזה נסביר איך לשלב את reCAPTCHA API מ-SafetyNet באפליקציה שלכם.

תנאים והגבלות נוספים

קבלת גישה אל reCAPTCHA API או שימוש בו מציינים את הסכמתך לתנאים ולהגבלות של Google APIs ולתנאים ולהגבלות הבאים של reCAPTCHA. כדי לקבל גישה אל ה-APIs, עליך לקרוא ולהבין את כל התנאים וההגבלות ותנאי המדיניות החלים.

התנאים וההגבלות של reCAPTCHA

את/ה מבין/ה ומסכים/ה לכך ש-reCAPTCHA API פועל על ידי איסוף מידע על חומרה ותוכנה, למשל נתונים לגבי מכשירים ואפליקציות ותוצאות של בדיקות תקינות, ושליחה של הנתונים האלה אל Google לצורך ניתוח. בהתאם לסעיף ‎3(d) של התנאים וההגבלות של Google APIs, את/ה מסכים/ה לכך שאם את/ה משתמש/ת בממשקי ה-API, באחריותך לספק את ההודעות הדרושות או לקבל את ההסכמות לאיסוף הנתונים האלה ולשיתוף שלהם עם Google.

רישום של צמד מפתחות reCAPTCHA

כדי לרשום זוג מפתחות לשימוש עם SafetyNet reCAPTCHA API, עוברים אל אתר ההרשמה של reCAPTCHA ל-Android ומבצעים את השלבים הבאים:

  1. בטופס שמופיע, מספקים את הפרטים הבאים:

    • תווית: תווית ייחודית למפתח. בדרך כלל משתמשים בשם החברה או הארגון.
    • סוג reCAPTCHA: בוחרים באפשרות reCAPTCHA v2 ואז באפשרות reCAPTCHA Android.
    • חבילות: יש לציין את שם החבילה של כל אפליקציה שמשתמשת במפתח ה-API הזה. כדי שאפליקציה תוכל להשתמש ב-API, שם החבילה שמזינים צריך להיות זהה לשם החבילה של האפליקציה. צריך להזין כל שם חבילה בשורה נפרדת.
    • בעלים: מוסיפים כתובת אימייל לכל אדם בארגון שמנטר את הערכות reCAPTCHA של האפליקציה.

  2. מסמנים את התיבה יש לאשר את התנאים וההגבלות של reCAPTCHA.

  3. שליחת התראות לבעלים: מסמנים את התיבה הזו אם רוצים לקבל אימיילים לגבי reCAPTCHA API, ואז לוחצים על שליחה.

  4. בדף שיופיע לאחר מכן, המפתחות הציבוריים והפרטיים יופיעו בקטע Site key (מפתח האתר) ו-Secret key (מפתח סודי), בהתאמה. משתמשים במפתח האתר כששולחים את בקשת האימות, ומשתמשים במפתח הסודי כשמאמתים את טוקן התשובה של המשתמש.

הוספת התלות ב-SafetyNet API

לפני שמשתמשים ב-API של reCAPTCHA, צריך להוסיף את SafetyNet API לפרויקט. אם משתמשים ב-Android Studio, צריך להוסיף את יחסי התלות האלה לקובץ Gradle ברמת האפליקציה. מידע נוסף זמין במאמר הגדרת SafetyNet API.

שימוש ב-reCAPTCHA API

בקטע הזה מוסבר איך לקרוא ל-API של reCAPTCHA כדי לשלוח בקשת אימות CAPTCHA ולקבל את אסימון התגובה של המשתמש.

שליחת בקשת האימות

כדי להפעיל את SafetyNet reCAPTCHA API, צריך להפעיל את ה-method‏ verifyWithRecaptcha(). בדרך כלל, השיטה הזו תואמת לבחירה של משתמש ברכיב בממשק המשתמש, כמו לחצן, בפעילות שלכם.

כשמשתמשים ב-method‏ verifyWithRecaptcha() באפליקציה, צריך לבצע את הפעולות הבאות:

  • מעבירים את מפתח האתר של ה-API כפרמטר.
  • משנים את השיטה onSuccess() ואת השיטה onFailure() כדי לטפל בשתי התוצאות האפשריות של המשימה 'בקשת אימות'. באופן ספציפי, אם ה-API מעביר מופע של ApiException אל onFailure(), צריך לטפל בכל קוד סטטוס אפשרי שאפשר לאחזר באמצעות getStatusCode().

קטע הקוד הבא מראה איך להפעיל את השיטה הזו:

KotlinJava
fun onClick(view: View) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
            .addOnSuccessListener(this as Executor, OnSuccessListener { response ->
                // Indicates communication with reCAPTCHA service was
                // successful.
                val userResponseToken = response.tokenResult
                if (response.tokenResult?.isNotEmpty() == true) {
                    // Validate the user response token using the
                    // reCAPTCHA siteverify API.
                }
            })
            .addOnFailureListener(this as Executor, OnFailureListener { e ->
                if (e is ApiException) {
                    // An error occurred when communicating with the
                    // reCAPTCHA service. Refer to the status code to
                    // handle the error appropriately.
                    Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")
                } else {
                    // A different, unknown type of error occurred.
                    Log.d(TAG, "Error: ${e.message}")
                }
            })
}
 
public void onClick(View v) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
        .addOnSuccessListener((Executor) this,
            new OnSuccessListener<SafetyNetApi.RecaptchaTokenResponse>() {
                @Override
                public void onSuccess(SafetyNetApi.RecaptchaTokenResponse response) {
                    // Indicates communication with reCAPTCHA service was
                    // successful.
                    String userResponseToken = response.getTokenResult();
                    if (!userResponseToken.isEmpty()) {
                        // Validate the user response token using the
                        // reCAPTCHA siteverify API.
                    }
                }
        })
        .addOnFailureListener((Executor) this, new OnFailureListener() {
                @Override
                public void onFailure(@NonNull Exception e) {
                    if (e instanceof ApiException) {
                        // An error occurred when communicating with the
                        // reCAPTCHA service. Refer to the status code to
                        // handle the error appropriately.
                        ApiException apiException = (ApiException) e;
                        int statusCode = apiException.getStatusCode();
                        Log.d(TAG, "Error: " + CommonStatusCodes
                                .getStatusCodeString(statusCode));
                    } else {
                        // A different, unknown type of error occurred.
                        Log.d(TAG, "Error: " + e.getMessage());
                    }
                }
        });
}

אימות של טוקן התשובה מהמשתמש

כש-reCAPTCHA API מפעיל את השיטה onSuccess(), סימן שהמשתמש השלים את האתגר של CAPTCHA. עם זאת, השיטה הזו מציינת רק שהמשתמש פתר את ה-CAPTCHA בצורה נכונה. עדיין צריך לאמת את אסימון התגובה של המשתמש משרת הקצה העורפי.

במאמר אימות התגובה של המשתמש מוסבר איך מאמתים את אסימון התגובה של המשתמש.