שילוב של Google Cloud Fraud Defense עם אפליקציות ל-Android

בדף הזה מוסבר איך לשלב את Google Cloud Fraud Defense באפליקציית Android.

ה-SDK משתמש ברפלקציה ובקוד דינמי כדי לאפשר שינוי ושיפור של מערכת הזיהוי באפליקציות או בערכות SDK קיימות שפרוסות. כדי למנוע הפרעה לאפליקציה, רשימת המחלקות שזמינות במערכת מוגבלת.

חשוב: חשוב לעיין במדיניות ההוצאה משימוש וההשבתה ולתכנן את השדרוג של ה-SDK באופן קבוע.

לפני שמתחילים

1. הכנת הסביבה ל-reCAPTCHA

2. יוצרים מפתח reCAPTCHA לפלטפורמת אפליקציות ל-Android.

   אפשרות נוספת היא להעתיק את המזהה של מפתח reCAPTCHA קיים ל-Android. כדי לעשות זאת, מבצעים אחת מהפעולות הבאות:

   • כדי להעתיק את המזהה של מפתח קיים ממסוףGoogle Cloud :

     1. עוברים לדף reCAPTCHA.

        מעבר אל reCAPTCHA

     2. ברשימת מפתחות reCAPTCHA, מעבירים את מצביע העכבר מעל המפתח שרוצים להעתיק ולוחצים על .
   • כדי להעתיק את המזהה של מפתח קיים באמצעות API בארכיטקטורת REST, משתמשים ב-method‏ projects.keys.list.
   • כדי להעתיק את המזהה של מפתח קיים באמצעות ה-CLI של gcloud, משתמשים בפקודה gcloud recaptcha keys list.

הכנת סביבת Android

אזהרה: אל תעברו אל Android SDK 18.2.0, כי יכול להיות שהאפליקציה שלכם לא תפעל בגלל שגיאות פנימיות. כדי למנוע את הבעיות האלה, צריך לעבור ישירות ל-Android SDK בגרסה 18.2.1 ואילך. פרטים נוספים זמינים בדוח הבעיה ב-GitHub.

Android מקורי

1. מורידים ומתקינים את הגרסה העדכנית של Android Studio כדי להכין את סביבת הפיתוח.

2. מוודאים שיש לכם אפליקציה עם ערך Android SDK מינימלי שמוגדר ל-API 23: Android 6.0 (Marshmallow).

3. אם אתם יוצרים אפליקציה חדשה לנייד, אתם צריכים ליצור אפליקציית בדיקה על ידי התחלת פרויקט חדש ב-Android Studio:

   1. לוחצים על ריקון הפעילות. אם רוצים להשתמש ב-Jetpack Compose באפליקציה, בוחרים באפשרות Empty Compose Activity.
   2. מגדירים את השפה ל-kotlin.
   3. מגדירים את ערך ה-SDK המינימלי ל-API 23: Android 6.0 (Marshmallow).

4. מוודאים שמאגר ה-Maven של Google‏ google() מופיע ברשימת המאגרים בקובץ build.gradle ברמת הפרויקט, כמו שמוצג בקטע הקוד הבא:

   allprojects {
       repositories {
           google()
       }
   }
   

   מידע נוסף זמין במאמר בנושא מאגר Maven של Google.

5. כדי להוסיף את התלות ב-reCAPTCHA API, מוסיפים את כלל ה-build הבא לקטע dependencies בקובץ build.gradle ברמת האפליקציה.

     implementation 'com.google.android.recaptcha:recaptcha:18.9.1'
   

   מידע נוסף על הוספת יחסי תלות באפליקציות ל-Android זמין במאמר הוספת יחסי תלות ב-build.

6. מוסיפים הרשאת גישה לאינטרנט בין התג הראשון <manifest> לבין התג הראשון <application> בקובץ המניפסט של האפליקציה (לדוגמה, AndroidManifest.xml). ההרשאה הזו נדרשת כי reCAPTCHA API כולל פעולות ברשת.

   <manifest ...>
   
       <uses-permission android:name="android.permission.INTERNET" />
   
       <application ...>
       ...
     </application>
   </manifest>
   

7. אם רוצים להשתמש בספריות AndroidX בפרויקט החדש, צריך לקמפל את ה-SDK ל-Android 9.0 ואילך ולהוסיף את קטע הקוד הבא ל-gradle.properties.

   android.useAndroidX=true
   android.enableJetifier=true
   

   מידע נוסף מופיע במאמר בנושא מעבר ל-AndroidX.

Flutter

הוראות מפורטות לשימוש ב-reCAPTCHA דרך Flutter זמינות במסמכי התיעוד של Flutter.

React Native

הוראות מפורטות לשימוש ב-reCAPTCHA דרך React Native מופיעות במסמכי העזרה של React Native.

הטמעה של reCAPTCHA באפליקציית Android

1. יוצרים מופע של לקוח באמצעות מפתח reCAPTCHA ‏ (KEY_ID) שיצרתם לאפליקציית Android.

   הערה: צריך להשתמש בלקוח reCAPTCHA רק פעם אחת במהלך חיי האפליקציה.

   ‫Kotlin עם fetchClient

   השיטה fetchClient מחזירה לקוח באופן מיידי ומתחילה לאתחל את ה-SDK ברקע. במקרה של כשלים ברשת, המערכת מנסה שוב לתקשר עם שרת reCAPTCHA.

   class CustomApplication : Application() {
   
       private lateinit var recaptchaClient: RecaptchaClient
       // we recommend initializing in a ViewModel
       private val recaptchaScope = CoroutineScope(Dispatchers.IO)
   
       override fun onCreate() {
         super.onCreate()
         initializeRecaptchaClient()
       }
   
       private fun initializeRecaptchaClient() {
         recaptchaScope.launch {
           try {
             recaptchaClient = Recaptcha.fetchClient(this@CustomApplication, "KEY_ID")
           } catch(e: RecaptchaException) {
             // Handle errors ...
             // See "Handle errors" section
           }
         }
       }
   }
   

   ‫Java עם fetchClient

   public final class CustomApplication extends Application {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     public void onCreate() {
       super.onCreate();
       initializeRecaptchaClient();
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .fetchTaskClient(this, "KEY_ID")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaTasksClient>() {
               @Override
               public void onSuccess(RecaptchaTasksClient client) {
                 MainActivity.this.recaptchaTasksClient = client;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 // Handle errors ...
                 // See "Handle errors" section
               }
             });
     }
   }
   

   האתחול של ה-SDK יכול להימשך כמה שניות. כדי לצמצם את זמן האחזור הזה, כדאי לאתחל את הלקוח מוקדם ככל האפשר, למשל במהלך הקריאה onCreate() של מחלקה מותאמת אישית Application. אל תגדירו רכיבי ממשק משתמש לחסימה ב-reCAPTCHA SDK.

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

2. לכל פעולה באפליקציה שמוגנת באמצעות reCAPTCHA, צריך להפעיל את השיטה execute ולהעביר RecaptchaAction. ספריית reCAPTCHA מספקת קבוצה מובנית של פעולות, ואם צריך, אפשר ליצור פעולות בהתאמה אישית.

   בקטע הקוד הבא מוצג איך להשתמש ב-execute כדי להגן על פעולה LOGIN.

   Kotlin

   private fun executeLoginAction() {
     recaptchaScope.launch {
       recaptchaClient
         .execute(RecaptchaAction.LOGIN)
         .onSuccess { token ->
           // Handle success ...
           // See "What's next" section for instructions
           // about handling tokens.
         }
         .onFailure { exception ->
           // Handle errors ...
         }
     }
   }
   

   Java

   private void executeLoginAction(View v) {
     assert recaptchaTasksClient != null;
     recaptchaTasksClient
       .executeTask(RecaptchaAction.LOGIN)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<String>() {
             @Override
             public void onSuccess(String token) {
               // Handle success ...
               // See "What's next" section for instructions
               // about handling tokens.
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               // Handle errors ...
             }
           });
   }
   

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

מעבר מהשיטה getClient לשיטה fetchClient

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

אם מתקשרים אל execute(timeout) והלקוח עדיין לא מוכן, המערכת מנסה לאתחל אותו לפני שהיא מחזירה טוקן או RecaptchaErrorCode.

בדוגמה הבאה אפשר לראות איך עוברים מ-getClient ל-fetchClient.

Kotlin

// Migrate from getClient
private fun initializeWithGetClient() {
  recaptchaScope.launch {
    Recaptcha.getClient(application, "KEY_ID")
      .onSuccess { client ->
        recaptchaClient = client
      }
      .onFailure { exception ->
        // Handle errors ...
      }
  }
}

 // Migrate to fetchClient
private fun initializeWithFetchClient() {
  recaptchaScope.launch {
    try {
      recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
    } catch(e: RecaptchaException){
      // Handle errors ...
    }
  }
}

Java

  // Migrate from getTasksClient
  private void initializeWithGetTasksClient() {
    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

  // Migrate to fetchTaskClient
  private void initializeWithFetchTaskClient() {
    Recaptcha
      .fetchTaskClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

הגדרת זמן קצוב לתפוגה של קריאות ל-API

אפשר לציין ערך של זמן קצוב לתפוגה לממשקי execute API באמצעות המאפיין withTimeout.

Kotlin

• הגדרת זמן קצוב לתפוגה כשמתקשרים אל execute.

      recaptchaScope.launch {
        recaptchaClient
          .execute(RecaptchaAction.LOGIN(), timeout = 10000L)
          .onSuccess { token ->
            // Handle success ...
            // See "What's next" section for instructions
            // about handling tokens.
          }
          .onFailure { exception ->
            // Handle errors ...
            // See "Handle errors" section
          }
      }
  

  בקטע הקוד הזה, הגדרנו את הזמן הקצוב לתפוגה של execute ל-10 שניות.

Java

• הגדרת זמן קצוב לתפוגה כשמתקשרים אל execute.

    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"), 10000L)
      .addOnSuccessListener(
          this,
          new OnSuccessListener<String>() {
            @Override
            public void onSuccess(String token) {
              // Handle success ...
              // See "What's next" section for instructions
              // about handling tokens.
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
              // See "Handle errors" section
            }
          });
  

  בקטע הקוד הזה, הגדרנו את הזמן הקצוב לתפוגה של execute ל-10 שניות.

טיפול בשגיאות

אם האפליקציה לא מצליחה לתקשר עם שירות reCAPTCHA, יכול להיות שממשק ה-API נתקל בשגיאה. אתם צריכים להוסיף לאפליקציה לוגיקה שתטפל בשגיאות כאלה בצורה תקינה.

מידע נוסף על פתרונות לשגיאות נפוצות ב-API זמין במאמר RecaptchaErrorCode.

הפניית API

לעיון בהפניה מלאה ל-reCAPTCHA API ל-Android, אפשר לעבור אל com.google.android.recaptcha.

המאמרים הבאים

• כדי להעריך את אסימון התגובה של reCAPTCHA, צריך ליצור הערכה.

  הערה: טוקנים של תגובות ל-reCAPTCHA נבדקים ומקבלים הערות משרת הבק-אנד, ולא מהמכשיר הנייד.