יצירת שירותי מילוי אוטומטי

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

קל יותר למלא טפסים ב-Android באמצעות המסגרת למילוי אוטומטי שזמינה ב-Android מגרסה 8.0 (רמת API 26) ואילך. המשתמשים יכולים לנצל את התכונות של המילוי האוטומטי רק אם יש אפליקציה שמספקת שירותי מילוי אוטומטי במכשיר שלהם.

בדף הזה מוסבר איך להטמיע שירות מילוי אוטומטי באפליקציה. אם אתם מחפשים דוגמת קוד שמראה איך מטמיעים שירות, תוכלו לעיין בדוגמה של AutofillFramework ב-Java או ב-Kotlin. פרטים נוספים על אופן הפעולה של שירותי המילוי האוטומטי זמינים בדפי העזרה של הכיתות AutofillService ו-AutofillManager.

הערה: החל מגרסה 11 של Android, הפלטפורמה מאפשרת למקלדות ולעורכים אחרים של שיטות קלט (IME) להציג הצעות למילוי אוטומטי בשורה, במקום להשתמש בתפריט נפתח. למידע נוסף על האופן שבו שירות המילוי האוטומטי יכול לתמוך בפונקציונליות הזו, ראו שילוב מילוי אוטומטי עם מקלדות.

הערה: שירות המילוי האוטומטי לא אמור להשתמש במידע למטרות אחרות מלבד מתן הצעות.

הצהרות והרשאות במניפסט

אפליקציות שמספקות שירותי מילוי אוטומטי חייבות לכלול הצהרה שמתארת את הטמעת השירות. כדי לציין את ההצהרה, צריך לכלול את האלמנט <service> במניפסט של האפליקציה. הרכיב <service> חייב לכלול את המאפיינים והרכיבים הבאים:

• מאפיין android:name שמפנה למחלקה המשנית של AutofillService באפליקציה שבה מוטמע השירות.
• המאפיין android:permission שמצהיר על ההרשאה BIND_AUTOFILL_SERVICE.
• אלמנט <intent-filter> שרכיב הצאצא <action> שלו מציין את הפעולה android.service.autofill.AutofillService.
• רכיב אופציונלי <meta-data> שאפשר להשתמש בו כדי לספק פרמטרים נוספים להגדרת השירות.

בדוגמה הבאה מוצגת הצהרה על שירות מילוי אוטומטי:

<service
    android:name=".MyAutofillService"
    android:label="My Autofill Service"
    android:permission="android.permission.BIND_AUTOFILL_SERVICE">
    <intent-filter>
        <action android:name="android.service.autofill.AutofillService" />
    </intent-filter>
    <meta-data
        android:name="android.autofill"
        android:resource="@xml/service_configuration" />
</service>

הרכיב <meta-data> כולל מאפיין android:resource שמפנה למשאב XML עם פרטים נוספים על השירות. המשאב service_configuration בדוגמה הקודמת מציין פעילות שמאפשרת למשתמשים להגדיר את השירות. בדוגמה הבאה מוצג משאב ה-XML service_configuration:

<autofill-service
  xmlns:android="http://schemas.android.com/apk/res/android"
  android:settingsActivity="com.example.android.SettingsActivity" />

אפשר לקרוא מידע נוסף על משאבי XML במאמר סקירה כללית של משאבי אפליקציות.

הנחיה להפעלת השירות

אפליקציה משמשת כשירות מילוי אוטומטי אחרי שהיא מצהירה על ההרשאה BIND_AUTOFILL_SERVICE והמשתמש מפעיל אותה בהגדרות המכשיר. אפליקציות יכולות לאמת אם הוא השירות שמופעל כרגע, על ידי קריאה ל-method hasEnabledAutofillServices() במחלקה AutofillManager.

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

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

מילוי תצוגות הלקוח

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

איור 1. ממשק משתמש של מילוי אוטומטי שבו מוצג מערך נתונים.

מסגרת המילוי האוטומטי מגדירה תהליך עבודה למלאת תצוגות, שנועד למזער את הזמן שבו מערכת Android קשורה לשירות המילוי האוטומטי. בכל בקשה, מערכת Android שולחת לאובייקט AssistStructure לשירות באמצעות קריאה ל-method‏ onFillRequest().

שירות המילוי האוטומטי בודק אם הוא יכול לענות על הבקשה באמצעות נתוני משתמשים ששמורים בו. אם השירות יכול לענות על הבקשה, הוא יארגן את הנתונים באובייקטים של Dataset. השירות קורא ל-method‏ onSuccess(), ומעביר אובייקט FillResponse שמכיל את האובייקטים Dataset. אם לשירות אין נתונים כדי לענות על הבקשה, הוא מעביר את null לשיטה onSuccess().

השירות קורא במקום זאת ל-method onFailure() אם יש שגיאה בעיבוד הבקשה. להסבר מפורט על תהליך העבודה, ראו תיאור בדף העזר של AutofillService.

הערה: החל מ-Android 10, אפשר להשתמש בדגל FillRequest.FLAG_COMPATIBILITY_MODE_REQUEST כדי לקבוע אם בקשת מילוי אוטומטי נוצרה דרך מצב תאימות.

הקוד הבא מציג דוגמה לשימוש בשיטה onFillRequest():

Kotlin

override fun onFillRequest(
    request: FillRequest,
    cancellationSignal: CancellationSignal,
    callback: FillCallback
) {
    // Get the structure from the request
    val context: List<FillContext> = request.fillContexts
    val structure: AssistStructure = context[context.size - 1].structure

    // Traverse the structure looking for nodes to fill out
    val parsedStructure: ParsedStructure = parseStructure(structure)

    // Fetch user data that matches the fields
    val (username: String, password: String) = fetchUserData(parsedStructure)

    // Build the presentation of the datasets
    val usernamePresentation = RemoteViews(packageName, android.R.layout.simple_list_item_1)
    usernamePresentation.setTextViewText(android.R.id.text1, "my_username")
    val passwordPresentation = RemoteViews(packageName, android.R.layout.simple_list_item_1)
    passwordPresentation.setTextViewText(android.R.id.text1, "Password for my_username")

    // Add a dataset to the response
    val fillResponse: FillResponse = FillResponse.Builder()
            .addDataset(Dataset.Builder()
                    .setValue(
                            parsedStructure.usernameId,
                            AutofillValue.forText(username),
                            usernamePresentation
                    )
                    .setValue(
                            parsedStructure.passwordId,
                            AutofillValue.forText(password),
                            passwordPresentation
                    )
                    .build())
            .build()

    // If there are no errors, call onSuccess() and pass the response
    callback.onSuccess(fillResponse)
}

data class ParsedStructure(var usernameId: AutofillId, var passwordId: AutofillId)

data class UserData(var username: String, var password: String)

Java

@Override
public void onFillRequest(FillRequest request, CancellationSignal cancellationSignal, FillCallback callback) {
    // Get the structure from the request
    List<FillContext> context = request.getFillContexts();
    AssistStructure structure = context.get(context.size() - 1).getStructure();

    // Traverse the structure looking for nodes to fill out
    ParsedStructure parsedStructure = parseStructure(structure);

    // Fetch user data that matches the fields
    UserData userData = fetchUserData(parsedStructure);

    // Build the presentation of the datasets
    RemoteViews usernamePresentation = new RemoteViews(getPackageName(), android.R.layout.simple_list_item_1);
    usernamePresentation.setTextViewText(android.R.id.text1, "my_username");
    RemoteViews passwordPresentation = new RemoteViews(getPackageName(), android.R.layout.simple_list_item_1);
    passwordPresentation.setTextViewText(android.R.id.text1, "Password for my_username");

    // Add a dataset to the response
    FillResponse fillResponse = new FillResponse.Builder()
            .addDataset(new Dataset.Builder()
                    .setValue(parsedStructure.usernameId,
                            AutofillValue.forText(userData.username), usernamePresentation)
                    .setValue(parsedStructure.passwordId,
                            AutofillValue.forText(userData.password), passwordPresentation)
                    .build())
            .build();

    // If there are no errors, call onSuccess() and pass the response
    callback.onSuccess(fillResponse);
}

class ParsedStructure {
    AutofillId usernameId;
    AutofillId passwordId;
}

class UserData {
    String username;
    String password;
}

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

Kotlin

// Add multiple datasets to the response
val fillResponse: FillResponse = FillResponse.Builder()
        .addDataset(Dataset.Builder()
                .setValue(parsedStructure.usernameId,
                        AutofillValue.forText(user1Data.username), username1Presentation)
                .setValue(parsedStructure.passwordId,
                        AutofillValue.forText(user1Data.password), password1Presentation)
                .build())
        .addDataset(Dataset.Builder()
                .setValue(parsedStructure.usernameId,
                        AutofillValue.forText(user2Data.username), username2Presentation)
                .setValue(parsedStructure.passwordId,
                        AutofillValue.forText(user2Data.password), password2Presentation)
                .build())
        .build()

Java

// Add multiple datasets to the response
FillResponse fillResponse = new FillResponse.Builder()
        .addDataset(new Dataset.Builder()
                .setValue(parsedStructure.usernameId,
                        AutofillValue.forText(user1Data.username), username1Presentation)
                .setValue(parsedStructure.passwordId,
                        AutofillValue.forText(user1Data.password), password1Presentation)
                .build())
        .addDataset(new Dataset.Builder()
                .setValue(parsedStructure.usernameId,
                        AutofillValue.forText(user2Data.username), username2Presentation)
                .setValue(parsedStructure.passwordId,
                        AutofillValue.forText(user2Data.password), password2Presentation)
                .build())
        .build();

שירותי מילוי אוטומטי יכולים לנווט בין האובייקטים מסוג ViewNode ב-AssistStructure כדי לאחזר את נתוני המילוי האוטומטי הנדרשים לביצוע הבקשה. שירות יכול לאחזר נתוני מילוי אוטומטי באמצעות שיטות של הכיתה ViewNode, כמו getAutofillId().

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

אם אפליקציית לקוח לא מספקת את המאפיין autofillHints, השירות צריך להשתמש בהיוריסטיקה משלו כדי לתאר את התוכן. השירות יכול להשתמש בשיטות מחלקות אחרות, כמו getText() או getHint(), כדי לקבל מידע על התוכן בתצוגה. מידע נוסף זמין במאמר הוספת רמזים למילוי אוטומטי.

הדוגמה הבאה מראה איך לעבור על AssistStructure ולאחזר נתוני מילוי אוטומטי מאובייקט ViewNode:

Kotlin

fun traverseStructure(structure: AssistStructure) {
    val windowNodes: List<AssistStructure.WindowNode> =
            structure.run {
                (0 until windowNodeCount).map { getWindowNodeAt(it) }
            }

    windowNodes.forEach { windowNode: AssistStructure.WindowNode ->
        val viewNode: ViewNode? = windowNode.rootViewNode
        traverseNode(viewNode)
    }
}

fun traverseNode(viewNode: ViewNode?) {
    if (viewNode?.autofillHints?.isNotEmpty() == true) {
        // If the client app provides autofill hints, you can obtain them using
        // viewNode.getAutofillHints();
    } else {
        // Or use your own heuristics to describe the contents of a view
        // using methods such as getText() or getHint()
    }

    val children: List<ViewNode>? =
            viewNode?.run {
                (0 until childCount).map { getChildAt(it) }
            }

    children?.forEach { childNode: ViewNode ->
        traverseNode(childNode)
    }
}

Java

public void traverseStructure(AssistStructure structure) {
    int nodes = structure.getWindowNodeCount();

    for (int i = 0; i < nodes; i++) {
        WindowNode windowNode = structure.getWindowNodeAt(i);
        ViewNode viewNode = windowNode.getRootViewNode();
        traverseNode(viewNode);
    }
}

public void traverseNode(ViewNode viewNode) {
    if(viewNode.getAutofillHints() != null && viewNode.getAutofillHints().length > 0) {
        // If the client app provides autofill hints, you can obtain them using
        // viewNode.getAutofillHints();
    } else {
        // Or use your own heuristics to describe the contents of a view
        // using methods such as getText() or getHint()
    }

    for(int i = 0; i < viewNode.getChildCount(); i++) {
        ViewNode childNode = viewNode.getChildAt(i);
        traverseNode(childNode);
    }
}

הערה: רוב התצוגות מספקות מאפייני autofillHints שתואמים לרשימה של ערכי AUTOFILL_HINT שכלולים בכיתה View. עם זאת, סביר יותר שתצוגות כמו HtmlInfo יעמדו בדרישות של המאפיינים שמפורטים בדף מאפיין ההשלמה האוטומטית של W3C.

לשמור את נתוני המשתמש.

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

איור 2. ממשק משתמש לשמירה של מילוי אוטומטי.

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

• סוג נתוני המשתמשים שנשמרים. רשימה של הערכים הזמינים של SAVE_DATA מופיעה במאמר SaveInfo.
• קבוצת התצוגות המפורטות המינימלית שצריך לשנות כדי להפעיל בקשה לשמירה. לדוגמה, בטופס התחברות, המשתמש בדרך כלל צריך לעדכן את התצוגות username ו-password כדי להפעיל בקשה לשמירה.

אובייקט SaveInfo משויך לאובייקט FillResponse, כפי שמוצג בדוגמת הקוד הבאה:

Kotlin

override fun onFillRequest(
    request: FillRequest,
    cancellationSignal: CancellationSignal,
    callback: FillCallback
) {
    ...
    // Builder object requires a non-null presentation
    val notUsed = RemoteViews(packageName, android.R.layout.simple_list_item_1)

    val fillResponse: FillResponse = FillResponse.Builder()
            .addDataset(
                    Dataset.Builder()
                            .setValue(parsedStructure.usernameId, null, notUsed)
                            .setValue(parsedStructure.passwordId, null, notUsed)
                            .build()
            )
            .setSaveInfo(
                    SaveInfo.Builder(
                            SaveInfo.SAVE_DATA_TYPE_USERNAME or SaveInfo.SAVE_DATA_TYPE_PASSWORD,
                            arrayOf(parsedStructure.usernameId, parsedStructure.passwordId)
                    ).build()
            )
            .build()
    ...
}

Java

@Override
public void onFillRequest(FillRequest request, CancellationSignal cancellationSignal, FillCallback callback) {
    ...
    // Builder object requires a non-null presentation
    RemoteViews notUsed = new RemoteViews(getPackageName(), android.R.layout.simple_list_item_1);

    FillResponse fillResponse = new FillResponse.Builder()
            .addDataset(new Dataset.Builder()
                    .setValue(parsedStructure.usernameId, null, notUsed)
                    .setValue(parsedStructure.passwordId, null, notUsed)
                    .build())
            .setSaveInfo(new SaveInfo.Builder(
                    SaveInfo.SAVE_DATA_TYPE_USERNAME | SaveInfo.SAVE_DATA_TYPE_PASSWORD,
                    new AutofillId[] {parsedStructure.usernameId, parsedStructure.passwordId})
                    .build())
            .build();
    ...
}

שירות המילוי האוטומטי יכול להטמיע לוגיקה לשמירת נתוני המשתמש בשיטה onSaveRequest(), שמופעל בדרך כלל אחרי שפעילות הלקוח מסתיימת או כשאפליקציית הלקוח קוראת ל-commit(). הקוד הבא מציג דוגמה ל-method onSaveRequest():

Kotlin

override fun onSaveRequest(request: SaveRequest, callback: SaveCallback) {
    // Get the structure from the request
    val context: List<FillContext> = request.fillContexts
    val structure: AssistStructure = context[context.size - 1].structure

    // Traverse the structure looking for data to save
    traverseStructure(structure)

    // Persist the data - if there are no errors, call onSuccess()
    callback.onSuccess()
}

Java

@Override
public void onSaveRequest(SaveRequest request, SaveCallback callback) {
    // Get the structure from the request
    List<FillContext> context = request.getFillContexts();
    AssistStructure structure = context.get(context.size() - 1).getStructure();

    // Traverse the structure looking for data to save
    traverseStructure(structure);

    // Persist the data - if there are no errors, call onSuccess()
    callback.onSuccess();
}

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

דחיית ממשק המשתמש לשמירת פרטי המילוי האוטומטי

החל מ-Android 10, אם משתמשים במספר מסכים כדי להטמיע תהליך עבודה של מילוי אוטומטי – לדוגמה, מסך אחד לשדה של שם המשתמש ומסך נוסף לסיסמה – אפשר לדחות את ממשק המשתמש של שמירת המילוי האוטומטי באמצעות הדגל SaveInfo.FLAG_DELAY_SAVE.

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

דרישה לאימות משתמשים

שירותי מילוי אוטומטי יכולים לספק רמה נוספת של אבטחה על ידי דרישה מהמשתמש לבצע אימות לפני שהוא יכול למלא תצוגות. כדאי להטמיע אימות משתמשים בתרחישים הבאים:

• צריך לבטל את הנעילה של נתוני המשתמש באפליקציה באמצעות סיסמה ראשית או סריקה של טביעת אצבע.
• צריך לבטל את הנעילה של מערך נתונים ספציפי, כמו פרטי כרטיס אשראי, באמצעות קוד אימות כרטיס (CVC).

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

בדוגמת הקוד הבאה מוסבר איך לציין שהבקשה מחייבת אימות:

Kotlin

val authPresentation = RemoteViews(packageName, android.R.layout.simple_list_item_1).apply {
    setTextViewText(android.R.id.text1, "requires authentication")
}
val authIntent = Intent(this, AuthActivity::class.java).apply {
    // Send any additional data required to complete the request
    putExtra(MY_EXTRA_DATASET_NAME, "my_dataset")
}

val intentSender: IntentSender = PendingIntent.getActivity(
        this,
        1001,
        authIntent,
        PendingIntent.FLAG_CANCEL_CURRENT
).intentSender

// Build a FillResponse object that requires authentication
val fillResponse: FillResponse = FillResponse.Builder()
        .setAuthentication(autofillIds, intentSender, authPresentation)
        .build()

Java

RemoteViews authPresentation = new RemoteViews(getPackageName(), android.R.layout.simple_list_item_1);
authPresentation.setTextViewText(android.R.id.text1, "requires authentication");
Intent authIntent = new Intent(this, AuthActivity.class);

// Send any additional data required to complete the request
authIntent.putExtra(MY_EXTRA_DATASET_NAME, "my_dataset");
IntentSender intentSender = PendingIntent.getActivity(
                this,
                1001,
                authIntent,
                PendingIntent.FLAG_CANCEL_CURRENT
        ).getIntentSender();

// Build a FillResponse object that requires authentication
FillResponse fillResponse = new FillResponse.Builder()
        .setAuthentication(autofillIds, intentSender, authPresentation)
        .build();

אחרי שהפעילות משלימה את תהליך האימות, היא צריכה להפעיל את השיטה setResult(), להעביר ערך RESULT_OK ולהגדיר את ה-extra‏ EXTRA_AUTHENTICATION_RESULT באובייקט FillResponse שכולל את מערך הנתונים המאוכלס. הקוד הבא מראה דוגמה לאופן שבו מחזירים את התוצאה בסיום תהליכי האימות:

Kotlin

// The data sent by the service and the structure are included in the intent
val datasetName: String? = intent.getStringExtra(MY_EXTRA_DATASET_NAME)
val structure: AssistStructure = intent.getParcelableExtra(EXTRA_ASSIST_STRUCTURE)
val parsedStructure: ParsedStructure = parseStructure(structure)
val (username, password) = fetchUserData(parsedStructure)

// Build the presentation of the datasets
val usernamePresentation =
        RemoteViews(packageName, android.R.layout.simple_list_item_1).apply {
            setTextViewText(android.R.id.text1, "my_username")
        }
val passwordPresentation =
        RemoteViews(packageName, android.R.layout.simple_list_item_1).apply {
            setTextViewText(android.R.id.text1, "Password for my_username")
        }

// Add the dataset to the response
val fillResponse: FillResponse = FillResponse.Builder()
        .addDataset(Dataset.Builder()
                .setValue(
                        parsedStructure.usernameId,
                        AutofillValue.forText(username),
                        usernamePresentation
                )
                .setValue(
                        parsedStructure.passwordId,
                        AutofillValue.forText(password),
                        passwordPresentation
                )
                .build()
        ).build()

val replyIntent = Intent().apply {
    // Send the data back to the service
    putExtra(MY_EXTRA_DATASET_NAME, datasetName)
    putExtra(EXTRA_AUTHENTICATION_RESULT, fillResponse)
}

setResult(Activity.RESULT_OK, replyIntent)

Java

Intent intent = getIntent();

// The data sent by the service and the structure are included in the intent
String datasetName = intent.getStringExtra(MY_EXTRA_DATASET_NAME);
AssistStructure structure = intent.getParcelableExtra(EXTRA_ASSIST_STRUCTURE);
ParsedStructure parsedStructure = parseStructure(structure);
UserData userData = fetchUserData(parsedStructure);

// Build the presentation of the datasets
RemoteViews usernamePresentation = new RemoteViews(getPackageName(), android.R.layout.simple_list_item_1);
usernamePresentation.setTextViewText(android.R.id.text1, "my_username");
RemoteViews passwordPresentation = new RemoteViews(getPackageName(), android.R.layout.simple_list_item_1);
passwordPresentation.setTextViewText(android.R.id.text1, "Password for my_username");

// Add the dataset to the response
FillResponse fillResponse = new FillResponse.Builder()
        .addDataset(new Dataset.Builder()
                .setValue(parsedStructure.usernameId,
                        AutofillValue.forText(userData.username), usernamePresentation)
                .setValue(parsedStructure.passwordId,
                        AutofillValue.forText(userData.password), passwordPresentation)
                .build())
        .build();

Intent replyIntent = new Intent();

// Send the data back to the service
replyIntent.putExtra(MY_EXTRA_DATASET_NAME, datasetName);
replyIntent.putExtra(EXTRA_AUTHENTICATION_RESULT, fillResponse);

setResult(RESULT_OK, replyIntent);

בתרחיש שבו צריך לבטל את הנעילה של מערך נתונים של כרטיס אשראי, השירות יכול להציג ממשק משתמש עם בקשה להזנת קוד האימות (CVC). אפשר להסתיר את הנתונים עד לביטול הנעילה של מערך הנתונים על ידי הצגת נתונים סטנדרטיים, כמו שם הבנק ו-4 הספרות האחרונות של מספר כרטיס האשראי. בדוגמה הבאה מוסבר איך לדרוש אימות של מערך נתונים ולהסתיר את הנתונים עד שהמשתמש יספק את המספר המזהה:

Kotlin

// Parse the structure and fetch payment data
val parsedStructure: ParsedStructure = parseStructure(structure)
val paymentData: Payment = fetchPaymentData(parsedStructure)

// Build the presentation that shows the bank and the last four digits of the
// credit card number, such as 'Bank-1234'
val maskedPresentation: String = "${paymentData.bank}-" +
        paymentData.creditCardNumber.substring(paymentData.creditCardNumber.length - 4)
val authPresentation = RemoteViews(packageName, android.R.layout.simple_list_item_1).apply {
    setTextViewText(android.R.id.text1, maskedPresentation)
}

// Prepare an intent that displays the UI that asks for the CVC
val cvcIntent = Intent(this, CvcActivity::class.java)
val cvcIntentSender: IntentSender = PendingIntent.getActivity(
        this,
        1001,
        cvcIntent,
        PendingIntent.FLAG_CANCEL_CURRENT
).intentSender

// Build a FillResponse object that includes a Dataset that requires authentication
val fillResponse: FillResponse = FillResponse.Builder()
        .addDataset(
                Dataset.Builder()
                        // The values in the dataset are replaced by the actual
                        // data once the user provides the CVC
                        .setValue(parsedStructure.creditCardId, null, authPresentation)
                        .setValue(parsedStructure.expDateId, null, authPresentation)
                        .setAuthentication(cvcIntentSender)
                        .build()
        ).build()

Java

// Parse the structure and fetch payment data
ParsedStructure parsedStructure = parseStructure(structure);
Payment paymentData = fetchPaymentData(parsedStructure);

// Build the presentation that shows the bank and the last four digits of the
// credit card number, such as 'Bank-1234'
String maskedPresentation = paymentData.bank + "-" +
    paymentData.creditCardNumber.subString(paymentData.creditCardNumber.length - 4);
RemoteViews authPresentation = new RemoteViews(getPackageName(), android.R.layout.simple_list_item_1);
authPresentation.setTextViewText(android.R.id.text1, maskedPresentation);

// Prepare an intent that displays the UI that asks for the CVC
Intent cvcIntent = new Intent(this, CvcActivity.class);
IntentSender cvcIntentSender = PendingIntent.getActivity(
        this,
        1001,
        cvcIntent,
        PendingIntent.FLAG_CANCEL_CURRENT
).getIntentSender();

// Build a FillResponse object that includes a Dataset that requires authentication
FillResponse fillResponse = new FillResponse.Builder()
        .addDataset(new Dataset.Builder()
                // The values in the dataset are replaced by the actual
                // data once the user provides the CVC
                .setValue(parsedStructure.creditCardId, null, authPresentation)
                .setValue(parsedStructure.expDateId, null, authPresentation)
                .setAuthentication(cvcIntentSender)
                .build())
        .build();

אחרי שהפעילות מאמתת את קוד האימות (CVC), היא צריכה לקרוא ל-method setResult(), להעביר ערך של RESULT_OK ולהגדיר את הערך הנוסף EXTRA_AUTHENTICATION_RESULT לאובייקט Dataset שמכיל את מספר כרטיס האשראי ואת תאריך התפוגה. מערך הנתונים החדש מחליף את מערך הנתונים שדורש אימות, והתצוגות מתמלאות באופן מיידי. הקוד הבא מראה דוגמה לאופן שבו מחזירים את מערך הנתונים אחרי שהמשתמש מספק את מספר ה-CVC:

Kotlin

// Parse the structure and fetch payment data.
val parsedStructure: ParsedStructure = parseStructure(structure)
val paymentData: Payment = fetchPaymentData(parsedStructure)

// Build a non-null RemoteViews object to use as the presentation when
// creating the Dataset object. This presentation isn't actually used, but the
// Builder object requires a non-null presentation.
val notUsed = RemoteViews(packageName, android.R.layout.simple_list_item_1)

// Create a dataset with the credit card number and expiration date.
val responseDataset: Dataset = Dataset.Builder()
        .setValue(
                parsedStructure.creditCardId,
                AutofillValue.forText(paymentData.creditCardNumber),
                notUsed
        )
        .setValue(
                parsedStructure.expDateId,
                AutofillValue.forText(paymentData.expirationDate),
                notUsed
        )
        .build()

val replyIntent = Intent().apply {
    putExtra(EXTRA_AUTHENTICATION_RESULT, responseDataset)
}

Java

// Parse the structure and fetch payment data.
ParsedStructure parsedStructure = parseStructure(structure);
Payment paymentData = fetchPaymentData(parsedStructure);

// Build a non-null RemoteViews object to use as the presentation when
// creating the Dataset object. This presentation isn't actually used, but the
// Builder object requires a non-null presentation.
RemoteViews notUsed = new RemoteViews(getPackageName(), android.R.layout.simple_list_item_1);

// Create a dataset with the credit card number and expiration date.
Dataset responseDataset = new Dataset.Builder()
        .setValue(parsedStructure.creditCardId,
                AutofillValue.forText(paymentData.creditCardNumber), notUsed)
        .setValue(parsedStructure.expDateId,
                AutofillValue.forText(paymentData.expirationDate), notUsed)
        .build();

Intent replyIntent = new Intent();
replyIntent.putExtra(EXTRA_AUTHENTICATION_RESULT, responseDataset);

ארגנו את הנתונים בקבוצות לוגיות

שירותי המילוי האוטומטי חייבים לארגן את הנתונים בקבוצות לוגיות שמבודדות מושגים מדומיינים שונים. בדף הזה, הקבוצות הלוגיות האלה נקראות מחיצות. הרשימה הבאה מציגה דוגמאות אופייניות למחיצות ולשדות:

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

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

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

מחיצה	שדה 1	שדה 2
פרטי כניסה	work_username	work_password
	personal_username	סיסמה_אישית
כתובת	רחוב_עבודה	work_city
	Individual_street	personal_city

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

שירות יכול לזהות את השדה שממנו הגיעה הבקשה על ידי קריאה לשיטה isFocused() במהלך סריקה של האובייקט AssistStructure. כך השירות יכול להכין FillResponse עם נתוני המחיצה המתאימים.

מילוי אוטומטי של קוד חד-פעמי ב-SMS

שירות המילוי האוטומטי יכול לעזור למשתמש למלא קודים חד-פעמיים שנשלחים באמצעות SMS באמצעות ממשק ה-API של SMS Retriever.

כדי להשתמש בתכונה הזו, צריך לעמוד בדרישות הבאות:

• שירות המילוי האוטומטי פועל ב-Android מגרסה 9 (API ברמה 28) ואילך.
• המשתמש נותן הסכמה לשירות המילוי האוטומטי לקרוא קודים חד-פעמיים מ-SMS.
• האפליקציה שבה אתם רוצים להשתמש במילוי אוטומטי לא משתמשת עדיין ב-SMS Retriever API כדי לקרוא קודים חד-פעמיים.

שירות המילוי האוטומטי יכול להשתמש ב-SmsCodeAutofillClient, שזמין בהתקשרות אל SmsCodeRetriever.getAutofillClient() משירותי Google Play בגרסה 19.0.56 ואילך.

השלבים העיקריים לשימוש ב-API הזה בשירות מילוי אוטומטי הם:

1. בשירות המילוי האוטומטי, משתמשים ב-hasOngoingSmsRequest מ-SmsCodeAutofillClient כדי לקבוע אם יש בקשות פעילות בשם החבילה של האפליקציה שאתם ממלאים באופן אוטומטי. שירות המילוי האוטומטי חייב להציג הצעה רק אם הפונקציה הזו מחזירה את הערך false.
2. בשירות המילוי האוטומטי, משתמשים ב-checkPermissionState מ-SmsCodeAutofillClient כדי לבדוק אם לשירות המילוי האוטומטי יש הרשאה למלא אוטומטית קודים חד-פעמיים. מצב ההרשאה יכול להיות NONE,‏ GRANTED או DENIED. שירות המילוי האוטומטי חייב להציג הצעה בנוגע למדינות NONE ו-GRANTED.
3. בפעילות האימות של המילוי האוטומטי, משתמשים בהרשאה SmsRetriever.SEND_PERMISSION כדי לרשום האזנה ל-BroadcastReceiver ל-SmsCodeRetriever.SMS_CODE_RETRIEVED_ACTION כדי לקבל את תוצאת קוד ה-SMS כשהיא זמינה.

4. ניתן להתקשר למספר startSmsCodeRetriever ב-SmsCodeAutofillClient כדי להתחיל להאזין לקודים חד-פעמיים שנשלחו ב-SMS. אם המשתמש מעניק הרשאות לשירות המילוי האוטומטי לאחזר קודים חד-פעמיים מ-SMS, המערכת מחפשת הודעות SMS שהתקבלו ב-1-5 הדקות האחרונות.

   אם שירות המילוי האוטומטי צריך לבקש ממשתמש הרשאה לקרוא קודים חד-פעמיים, יכול להיות שהשדה Task שהוחזר על ידי startSmsCodeRetriever ייכשל ותוחזר ResolvableApiException. במקרה כזה, צריך להפעיל את השיטה ResolvableApiException.startResolutionForResult() כדי להציג תיבת דו-שיח של הסכמה לבקשת ההרשאה.

5. מקבלים את התוצאה של קוד ה-SMS מהכוונה, ואז מחזירים את קוד ה-SMS בתור תגובה למילוי אוטומטי.

הערה: כדי לזהות שהכוונה להעברה (intent) היא מ-SMS Retriever API, צריך להוסיף את ההרשאה com.google.android.gms.auth.api.phone.permission.SEND למכשיר המקבל. הגדרת ההרשאה הזו זמינה ב-Google Play Services מגרסה 19.8.31 ואילך.

תרחישים מתקדמים של מילוי אוטומטי

שילוב עם המקלדת

החל מ-Android 11, בפלטפורמה יש אפשרות למקלדות ולעורכים אחרים של שיטות קלט (IME) להציג הצעות למילוי אוטומטי בשורה, במקום להשתמש בתפריט נפתח. למידע נוסף על האופן שבו שירות המילוי האוטומטי יכול לתמוך בפונקציונליות הזו, ראו שילוב מילוי אוטומטי עם מקלדות.

חלוקה לדפים של מערכי נתונים

תגובה גדולה של מילוי אוטומטי עלולה לחרוג מגודל העסקה המותרת של האובייקט Binder שמייצג את האובייקט שניתן להעביר מרחוק שנדרש לעיבוד הבקשה. כדי למנוע ממערכת Android להפעיל חריגה בתרחישים האלה, אפשר להקטין את FillResponse על ידי הוספה של לא יותר מ-20 אובייקטים מסוג Dataset בכל פעם. אם התשובה צריכה מערכי נתונים נוספים, תוכלו להוסיף מערך נתונים שמיידע את המשתמשים שיש עוד מידע, ומאחזר את הקבוצה הבאה של מערכי הנתונים כשהם נבחרים. מידע נוסף זמין בכתובת addDataset(Dataset).

שמירת נתונים שמפוצלים לכמה מסכים

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

1. בבקשת המילוי הראשונה, מוסיפים לתגובה חבילת מצב לקוח שמכילה את מזהי המילוי האוטומטי של השדות החלקים שמוצגים במסך.
2. בבקשת המילוי השנייה, מאחזרים את החבילה של מצב הלקוח, מקבלים את מזהי המילוי האוטומטי שהוגדרו בבקשה הקודמת ממצב הלקוח ומוסיפים את המזהים האלה ואת הדגל FLAG_SAVE_ON_ALL_VIEWS_INVISIBLE לאובייקט SaveInfo שמשמש בתגובה השנייה.
3. בבקשה לשמירה, משתמשים באובייקטים FillContext המתאימים כדי לקבל את הערך של כל שדה. לכל בקשה למילוי יש הקשר אחד למילוי.

מידע נוסף זמין במאמר שמירה כשהנתונים מחולקים לכמה מסכים.

לספק לוגיקה של אתחול ופירוק לכל בקשה

בכל פעם שמופיעה בקשה למילוי אוטומטי, מערכת Android מקשרת את השירות ומפעילה את השיטה onConnected() שלו. אחרי שהשירות מעבד את הבקשה, מערכת Android מבצעת קריאה ל-method‏ onDisconnected() ומבטלת את הקישור לשירות. אפשר להטמיע את onConnected() כדי לספק קוד שפועל לפני עיבוד הבקשה, ואת onDisconnected() כדי לספק קוד שפועל אחרי עיבוד הבקשה.

התאמה אישית של ממשק המשתמש לשמירת המילוי האוטומטי

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

מצב תאימות

מצב התאימות מאפשר לשירותי מילוי אוטומטי להשתמש במבנה הווירטואלי של הנגישות למטרות מילוי אוטומטי. היא שימושית במיוחד כשרוצים לספק פונקציונליות של מילוי אוטומטי בדפדפנים שלא מיישמים באופן מפורש את ממשקי ה-API של המילוי האוטומטי.

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

$ adb shell settings get global autofill_compat_mode_allowed_packages

אם החבילה שאתם בודקים לא מופיעה ברשימה, מוסיפים אותה על ידי הרצת הפקודה הבאה, שבה pkgX היא החבילה של האפליקציה:

$ adb shell settings put global autofill_compat_mode_allowed_packages pkg1[resId1]:pkg2[resId1,resId2]

אם האפליקציה היא דפדפן, צריך להשתמש ב-resIdx כדי לציין את מזהה המשאב של שדה הקלט שמכיל את כתובת ה-URL של הדף שעבר עיבוד.

למצב התאימות יש את המגבלות הבאות:

• בקשת שמירה מופעלת כשהשירות משתמש בדגל FLAG_SAVE_ON_ALL_VIEWS_INVISIBLE או כשמתבצעת קריאה לשיטה setTrigger(). FLAG_SAVE_ON_ALL_VIEWS_INVISIBLE מוגדר כברירת מחדל כשמשתמשים במצב תאימות.
• יכול להיות שערך הטקסט של הצמתים לא יהיה זמין ב-method onSaveRequest(SaveRequest, SaveCallback).

למידע נוסף על מצב תאימות, כולל המגבלות שמשויכות אליו, אפשר לעיין במסמך העזרה של הכיתה AutofillService.