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

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

שימוש ב-reCAPTCHA API

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

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

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

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

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

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

Kotlin

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}")
                }
            })
}

Java

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 בצורה נכונה. עדיין צריך לאמת את אסימון התגובה של המשתמש משרת הקצה העורפי.

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