1 2 Android AutofillFramework Sample 3 =================================== 4 5 This sample demonstrates the use of the Autofill Framework. It includes implementations of client 6 Activities with views that should be autofilled, and a Service that can provide autofill data to 7 client Activities. 8 9 Introduction 10 ------------ 11 12 This sample demonstrates the use of the Autofill framework from the service side and the client 13 side. In practice, only a small handful of apps will develop Autofill services because a device 14 will only have one service as default at a time, and there is just a small number of 3rd-party apps 15 providing these services (typically password managers). However, all apps targeting O with any 16 autofillable fields should follow the necessary steps to 1) ensure their views can be autofilled 17 and 2) optimize their autofill performance. Most of the time, there is little to no extra code 18 involved, but the use of custom views and views with virtual child views requires more work. 19 20 The sample's Autofill service is implemented to parse the client's view hierarchy in search of 21 autofillable fields that it has data for. If such fields exist in the hierarchy, the service sends 22 data suggestions to the client to autofill those fields. The client uses the following attributes 23 to specify autofill properties: `importantForAutofill`, `autofillHints`, and `autofillType`. 24 `importantForAutofill` specifies whether the view is autofillable. `autofillHints` is a list of 25 strings that hint to the service **what** data to fill the view with. This sample service only 26 supports the hints listed [here](https://developer.android.com/reference/android/view/View.html#AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DATE) 27 with the prefix AUTOFILL_HINT_*. `autofillType` tells the service the type of data it expects to 28 receive (i.e. a list index, a date, or a string). Specifying `autofillType` is only necessary 29 when implementing a custom view since all of the provided widgets in the UI toolkit do this for you. 30 31 To 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 33 app. To edit the service's settings, tap the settings icon next to the **Auto-fill service** list 34 item or open the **Autofill Settings** launcher icon.. Here, you can set whether you want to enable 35 authentication on the entire autofill Response or just on individual autofill datasets. You should 36 also 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. 39 Be careful about what you store when experimenting with the sample because anyone with root access 40 to your device will be able to view your autofill data. 41 42 The client side of the app has three Activities that each have autofillable fields. The first 43 Activity uses standard views to comprise a login form. Very little needs to be done by the client 44 app to ensure the views get autofilled properly. The second Activity uses a custom view with 45 virtual children, meaning some autofillable child views are not known to the View hierarchy to be 46 child views. Supporting autofill on these child views is a little more involved. 47 48 The following code snippet shows how to signal to the autofill service that a specific 49 autofillable virtual view has come into focus: 50 51 ```java 52 class 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 65 Now that the autofillable view has signaled to the service that it has been autofilled, it needs 66 to provide the virtual view hierarchy to the Autofill service. This is done out of the box for 67 views part of the UI toolkit, but you need to implement this yourself if you have the view has 68 virtual child views. The following code example shows the `View` method you have to override in 69 order to provide this view hierarchy data to the Autofill service. 70 71 ```java 72 @Override 73 public 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 98 After 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 100 views with. When a `Dataset` is selected, this method is invoked for all of the views that were 101 associated with that `Dataset` by the service. For example, the `Dataset` might contain Autofill 102 values for username, password, birthday, and address. This method would then be invoked on all 103 four of those fields. The following code example shows how the sample app implements the method 104 to deliver a UI update to the appropriate child view after the user makes their selection. 105 106 ```java 107 @Override 108 public 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 130 Pre-requisites 131 -------------- 132 133 - Android SDK 26 134 - Android Build Tools v27.0.2 135 - Android Support Repository 136 137 Screenshots 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 142 Getting Started 143 --------------- 144 145 This sample uses the Gradle build system. To build this project, use the 146 "gradlew build" command or use "Import Project" in Android Studio. 147 148 Support 149 ------- 150 151 - Google+ Community: https://plus.google.com/communities/105153134372062985968 152 - Stack Overflow: http://stackoverflow.com/questions/tagged/android 153 154 If you've found an error in this sample, please file an issue: 155 https://github.com/googlesamples/android-AutofillFramework 156 157 Patches are encouraged, and may be submitted by forking this project and 158 submitting a pull request through GitHub. Please see CONTRIBUTING.md for more details. 159 160 License 161 ------- 162 163 Copyright 2017 The Android Open Source Project, Inc. 164 165 Licensed to the Apache Software Foundation (ASF) under one or more contributor 166 license agreements. See the NOTICE file distributed with this work for 167 additional information regarding copyright ownership. The ASF licenses this 168 file to you under the Apache License, Version 2.0 (the "License"); you may not 169 use this file except in compliance with the License. You may obtain a copy of 170 the License at 171 172 http://www.apache.org/licenses/LICENSE-2.0 173 174 Unless required by applicable law or agreed to in writing, software 175 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 176 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 177 License for the specific language governing permissions and limitations under 178 the License. 179
