1
2Android AutofillFramework Sample
3===================================
4
5This sample demonstrates the use of the Autofill Framework. It includes implementations of client
6Activities with views that should be autofilled, and a Service that can provide autofill data to
7client Activities.
8
9Introduction
10------------
11
12This sample demonstrates the use of the Autofill framework from the service side and the client
13side. In practice, only a small handful of apps will develop Autofill services because a device
14will only have one service as default at a time, and there is just a small number of 3rd-party apps
15providing these services (typically password managers). However, all apps targeting O with any
16autofillable fields should follow the necessary steps to 1) ensure their views can be autofilled
17and 2) optimize their autofill performance. Most of the time, there is little to no extra code
18involved, but the use of custom views and views with virtual child views requires more work.
19
20The sample's Autofill service is implemented to parse the client's view hierarchy in search of
21autofillable fields that it has data for. If such fields exist in the hierarchy, the service sends
22data suggestions to the client to autofill those fields. The client uses the following attributes
23to specify autofill properties: `importantForAutofill`, `autofillHints`, and `autofillType`.
24`importantForAutofill` specifies whether the view is autofillable. `autofillHints` is a list of
25strings that hint to the service **what** data to fill the view with. This sample service only
26supports the hints listed [here](https://developer.android.com/reference/android/view/View.html#AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DATE)
27with the prefix AUTOFILL_HINT_*. `autofillType` tells the service the type of data it expects to
28receive (i.e. a list index, a date, or a string). Specifying `autofillType` is only necessary
29when implementing a custom view since all of the provided widgets in the UI toolkit do this for you.
30
31To set the device's default Autofill service to the one in the sample, edit **Settings** >
32**System** > **Languages & Input** > **Advanced** > **Auto-fill service** and select the sample
33app. To edit the service's settings, tap the settings icon next to the **Auto-fill service** list
34item or open the **Autofill Settings** launcher icon.. Here, you can set whether you want to enable
35authentication on the entire autofill Response or just on individual autofill datasets. You should
36also set the master password to “unlock” authenticated autofill data with.
37
38**Note:** This sample service stores all autofill data in SharedPreferences and thus is not secure.
39Be careful about what you store when experimenting with the sample because anyone with root access
40to your device will be able to view your autofill data.
41
42The client side of the app has three Activities that each have autofillable fields. The first
43Activity uses standard views to comprise a login form. Very little needs to be done by the client
44app to ensure the views get autofilled properly. The second Activity uses a custom view with
45virtual children, meaning some autofillable child views are not known to the View hierarchy to be
46child views. Supporting autofill on these child views is a little more involved.
47
48The following code snippet shows how to signal to the autofill service that a specific
49autofillable virtual view has come into focus:
50
51```java
52class CustomVirtualView {
53...
54    // Cache AutofillManager system service
55    mAutofillManager = context.getSystemService(AutofillManager.class);
56...
57    // Notify service which virtual view has come into focus.
58    mAutofillManager.notifyViewEntered(CustomVirtualView.this, id, absBounds);
59...
60   // Notify service that a virtual view has left focus.
61   mAutofillManager.notifyViewExited(CustomVirtualView.this, id);
62}
63```
64
65Now that the autofillable view has signaled to the service that it has been autofilled, it needs
66to provide the virtual view hierarchy to the Autofill service. This is done out of the box for
67views part of the UI toolkit, but you need to implement this yourself if you have the view has
68virtual child views. The following code example shows the `View` method you have to override in
69order to provide this view hierarchy data to the Autofill service.
70
71```java
72@Override
73public void onProvideAutofillVirtualStructure(ViewStructure structure, int flags) {
74    // Build a ViewStructure that will get passed to the AutofillService by the framework
75    // when it is time to find autofill suggestions.
76    structure.setClassName(getClass().getName());
77    int childrenSize = mItems.size();
78    int index = structure.addChildCount(childrenSize);
79    // Traverse through the view hierarchy, including virtual child views. For each view, we
80    // need to set the relevant autofill metadata and add it to the ViewStructure.
81    for (int i = 0; i < childrenSize; i++) {
82        Item item = mItems.valueAt(i);
83        ViewStructure child = structure.newChild(index);
84        child.setAutofillId(structure, item.id);
85        child.setAutofillHints(item.hints);
86        child.setAutofillType(item.type);
87        child.setDataIsSensitive(!item.sanitized);
88        child.setText(item.text);
89        child.setAutofillValue(AutofillValue.forText(item.text));
90        child.setFocused(item.focused);
91        child.setId(item.id, getContext().getPackageName(), null, item.line.idEntry);
92        child.setClassName(item.getClassName());
93        index++;
94    }
95}
96```
97
98After the service processes the Autofill request and sends back a series of Autofill `Datasets`
99(wrapped in a `Response` object), the user can pick which `Dataset` they want to autofill their
100views with. When a `Dataset` is selected, this method is invoked for all of the views that were
101associated with that `Dataset` by the service. For example, the `Dataset` might contain Autofill
102values for username, password, birthday, and address. This method would then be invoked on all
103four of those fields. The following code example shows how the sample app implements the method
104to deliver a UI update to the appropriate child view after the user makes their selection.
105
106```java
107@Override
108public void autofill(SparseArray<AutofillValue> values) {
109    // User has just selected a Dataset from the list of autofill suggestions.
110    // The Dataset is comprised of a list of AutofillValues, with each AutofillValue meant
111    // to fill a specific autofillable view. Now we have to update the UI based on the
112    // AutofillValues in the list.
113    for (int i = 0; i < values.size(); i++) {
114        final int id = values.keyAt(i);
115        final AutofillValue value = values.valueAt(i);
116        final Item item = mItems.get(id);
117        if (item != null && item.editable) {
118            // Set the item's text to the text wrapped in the AutofillValue.
119            item.text = value.getTextValue();
120        } else if (item == null) {
121            // Component not found, so no-op.
122        } else {
123            // Component not editable, so no-op.
124        }
125    }
126    postInvalidate();
127}
128```
129
130Pre-requisites
131--------------
132
133- Android SDK 26
134- Android Build Tools v27.0.3
135- Android Support Repository
136
137Screenshots
138-------------
139
140<img src="screenshots/1_MainPage.png" height="400" alt="Screenshot"/> <img src="screenshots/2_SampleLoginEditTexts.png" height="400" alt="Screenshot"/> <img src="screenshots/3_SampleLoginEditTextsAutofilled.png" height="400" alt="Screenshot"/> <img src="screenshots/4_WelcomeActivity.png" height="400" alt="Screenshot"/> <img src="screenshots/5_SampleLoginCustomVirtualView.png" height="400" alt="Screenshot"/> <img src="screenshots/6_SampleLoginCustomVirtualViewAutofilled.png" height="400" alt="Screenshot"/> <img src="screenshots/7_SampleCheckOutSpinnersAutofillable.png" height="400" alt="Screenshot"/> <img src="screenshots/8_SampleCheckOutSpinnersAutofilled.png" height="400" alt="Screenshot"/> <img src="screenshots/9_SettingsActivity.png" height="400" alt="Screenshot"/> <img src="screenshots/10_AuthNeeded.png" height="400" alt="Screenshot"/> <img src="screenshots/11_AuthActivity.png" height="400" alt="Screenshot"/>
141
142Getting Started
143---------------
144
145This sample uses the Gradle build system. To build this project, use the
146"gradlew build" command or use "Import Project" in Android Studio.
147
148Support
149-------
150
151- Google+ Community: https://plus.google.com/communities/105153134372062985968
152- Stack Overflow: http://stackoverflow.com/questions/tagged/android
153
154If you've found an error in this sample, please file an issue:
155https://github.com/googlesamples/android-AutofillFramework
156
157Patches are encouraged, and may be submitted by forking this project and
158submitting a pull request through GitHub. Please see CONTRIBUTING.md for more details.
159
160License
161-------
162
163Copyright 2017 The Android Open Source Project, Inc.
164
165Licensed to the Apache Software Foundation (ASF) under one or more contributor
166license agreements.  See the NOTICE file distributed with this work for
167additional information regarding copyright ownership.  The ASF licenses this
168file to you under the Apache License, Version 2.0 (the "License"); you may not
169use this file except in compliance with the License.  You may obtain a copy of
170the License at
171
172http://www.apache.org/licenses/LICENSE-2.0
173
174Unless required by applicable law or agreed to in writing, software
175distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
176WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
177License for the specific language governing permissions and limitations under
178the License.
179