Wizard is user-friendly activity with step-by-step description of each required permissions and Proceed button to request them. For example, wizard will look like this on Android 10:
To start wizard from your activity or fragment use code below:
Where enableAggressivePermissionsWizard flag you set to true when wizard will be finished if all required permissions granted (user can’t cancel it with back button), and false if wizard can be finished with not all granted permissions or cancelled with back button.
Where enableAggressivePermissionsWizardPage flag you set to true when wizard will slide to next page if requested permissions granted on current page, and false if wizard can slide with not granted permissions.
See table below to see how it works:
enabled Aggressive Permissions Wizard
enabled Aggressive Permissions WizardPage
cancelable wizard
can deny requested pemission and slide to next step
can finish wizard without all granted perms
true
true
no
no
no
true
false
no
yes
no
false
true
yes
no
no
false
false
yes
yes
yes
And after that you can get the result in onActvityResult method by this way:
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
// don’t forget to call here and in all base activity/fragments
if (requestCode == PermissionsWizardActivity.WIZARD_PERMISSIONS_CODE) {
when (resultCode) {
WIZARD_RESULT_ALL_GRANTED -> {
/* when user finished wizard with all required permissions
granted - enable SDK if Device ID is exist*/
enableSDK()
}
WIZARD_RESULT_CANCELED -> {
// when user canceled wizard
Toast.makeText(this, "Wizard canceled!",
Toast.LENGTH_SHORT).show()
}
WIZARD_RESULT_NOT_ALL_GRANTED -> {
/* when user finished wizard with not all required permissions
granted*/
Toast.makeText(this, "NOT All Required Permissions Granted!",
Toast.LENGTH_SHORT).show()
}
}
}
}
Customizing
The permission wizard can be different. But generally there could be 8 screens:
Location permission screen
Location restrictions on Android were chaged twice in 10 and 11 versions.
If you want to customize description of this screen you should override resources:
values/strings.xml
<!-- Generic location permission description -->
<string name="wizard_telematics_location_desc">As the next step, you will receive a popup to grant rights to access to <b>location</b>.\n\n
We use location service for evaluating your driving manner.\nBy enabling <b>Allow</b> on location, application will be able to automatically determine when you have started and ended a drive.
</string>
<!-- Bottom dialog before the app name text-->
<string name="wizard_telematics_attention_dialog_location_before">Allow</string>
<!-- Bottom dialog after the app name text -->
<string name="wizard_telematics_attention_dialog_location_after">to\naccess this device\'s location?</string>
values-v29/strings.xml
<!-- Android 10 location permission description -->
<string name="wizard_telematics_location_desc">As the next step, you will receive a popup to grant rights to access to <b>location</b>.\n\n
We use location service for evaluating your driving manner.\nBy enabling <b>Allow all the time</b> on location, application will be able to automatically determine when you have started and ended a drive.
</string>
<!-- Bottom dialog after the app name text-->
<string name="wizard_telematics_attention_dialog_location_after">to access this device\'s location?</string>
values-v30/strings.xml
<!-- Android 11 location permission description -->
<string name="wizard_telematics_location_desc">As the next step, you’ll see a popup to grant app access to <b>location services</b>.\n\n
The app uses your location data to automatically record your trips in background, determine when you have started and ended your trip and to measure your score.\n\n
The app will not work without this permission.\n\n
On the next popup, please select <b>While using the app</b>.
</string>
Background location permission screen
Since Android 11 Google introduced new privacy feature releated to location permission granting. Now if application needs access to users location in the background it should first grant access to foreground location and only after that it can ask permission to access locaition in the background.
values/strings.xml
<!-- background location permission description -->
<string name="wizard_telematics_background_location_desc">
As the next step, you should grant rights to access to <b>location in background.</b>\n\n
The app will not work without this permission.\n\n
You should navigate to app settings and choose "<b>Allow all the time</b> on the Location permission screen.</string>
<!-- Additional text in the bottom dialog -->
<string name="wizard_telematics_location_additional_description">This app may want to access your location all the time, even when you\'re not using the app. <font color="#a7c7f9"><u>Allow in settings.</u></font></string>
<!-- Dialog text before app name -->
<string name="wizard_telematics_attention_dialog_background_location_before">Change location access for </string>
<!-- Dialog text after app name -->
<string name="wizard_telematics_attention_dialog_background_location_after">\?</string>
<!-- Dialog text to keep permission in "While using the app" -->
<string name="wizard_telematics_location_additional_keep">Keep \'While using the app\'</string>
<!-- Wizard activity recognition section -->
<string name="wizard_telematics_activity_recognition_desc">Then, you will receive a popup to grant access to your <b>physical activity</b>. \nWe need this information to create a driving score.\n\n
Please, choose <b>Allow</b> for application to grant access to physical activity.
</string>
<!-- Bottom dialog before the app name text-->
<string name="wizard_telematics_attention_dialog_activity_recognition_before">Allow</string>
<!-- Bottom dialog after the app name text-->
<string name="wizard_telematics_attention_dialog_activity_recognition_after">to\naccess your physical activity?</string>
values-v29/strings.xml
<!-- Bottom dialog after the app name text-->
<string name="wizard_telematics_attention_dialog_activity_recognition_after">to access your physical activity?</string>
Device location permission screen (when location services are switched off on the device)
values/strings.xml
<!-- Gps services description -->
<string name="wizard_telematics_gps_google_desc">You will receive a popup shortly to turn on <b>device location</b>, which uses Google\'s location service.\n\n
For the app to work properly choose <b>OK</b>
</string>
<string name="wizard_telematics_attention_dialog_gps_google">For a better experience, turn on device location, which uses Google\'s location service.</string>
<string name="dialog_telematics_attention_dialog_gps_google_ok">OK</string>
<string name="dialog_telematics_attention_dialog_gps_google_no">No, thanks</string>
Battery optimization permission screen
values/strings.xml
<string name="wizard_telematics_ignore_system_battery_optimization_desc">You will receive a popup shortly to ignore <b>battery optimizations</b>.\n\n
For the app to work properly choose <b>ALLOW</b>
</string>
<string name="wizard_telematics_attention_dialog_battery">Let app always run in background?\n\nAllowing application to always run in the\nbackground may reduce battery life.\n\nYou can change this later from\nSettings > Apps & notifications.</string>
<string name="dialog_telematics_attention_dialog_battery_ok">ALLOW</string>
<string name="dialog_telematics_attention_dialog_battery_no">DENY</string>
Custom power management tools disabling screen (custom feature for smartphones manufacturers like Samsung, Xiaomi, Huawei etc.)
values/strings.xml
<string name="wizard_telematics_extra_power_management_desc">By press "Proceed" you will be forwarded to settings to setup <b>power management</b>.\n
For the app to work properly <b>DISABLE</b> power management.
</string>
Autostart enabling screen (custom feature for smartphones manufacturers like Xiaomi, Huawei etc.)
values/strings.xml
<string name="wizard_telematics_extra_autostart_desc">By press "Proceed" you will be forwarded to settings to setup <b>AUTOSTART</b>.\n
For the app to work properly <b>ENABLE</b> autostart</string>
Notifications showing permissions screen (custom feature for smartphones manufacturers)
values/strings.xml
<string name="wizard_telematics_extra_notifications_desc">By press "Proceed" you will be forwarded to settings to setup <b>notifications</b>.\n
For the app to work properly <b>ENABLE</b> all notification.</string>
Additional resources
values/strings.xml
<!-- Bottom proceed button resource -->
<string name="wizard_telematics_show_request">Proceed</string>
<!-- Allow button resource -->
<string name="wizard_telematics_deny">Deny</string>
<!-- Deny button resource -->
<string name="wizard_telematics_allow">Allow</string>
<!-- Allow all the time resource -->
<string name="wizard_telematics_allow_all_time">Allow all the time</string>
<!-- Allow only while using the app resource -->
<string name="wizard_telematics_allow_while_using">Allow only while using the app</string>
<!-- Steps resource in the top of wizard. !Important! FORMAT SHOULD BE THE SAME! -->
<string name="wizard_telematics_step">STEP %1s of %2s</string>
<string name="wizard_telematics_please_grant">Please, grant all required permissions</string>
<!-- Android 11 new resoucres-->
<string name="wizard_telematics_while_using_11">While using the app</string>
<string name="wizard_telematics_only_this_time">Only this time</string>
<string name="wizard_telematics_ask_every_time">Ask every time</string>
Common text customizations
All resources which are used are supporting Html-markup styling. But also you can set custom font and font the text (or to the part of the text) via annotations
Customizing font:
Specify your font in resources (check documentation)
Add the <annotation> tag, and define the key-value pair. In this case, the key is font, and the value is the font-resource name
<string name="wizard_telematics_gps_google_desc">You will receive a popup shortly to turn on <b>device location</b>, which uses <annotation font="digital">Google\'s</annotation> location service.\n\n
For the app to work properly choose <b>OK</b>
</string>
Customizing size of the text
Add dimen resource of the
Specify annotation for the text with name textSize
Sample
Dimen-resource:
<dimen name="text_size">12sp</dimen>
Add the <annotation> tag, and define the key-value pair. In this case, the key is textSize, and the value is the dimen-resource name
<string name="wizard_telematics_gps_google_desc">You will receive a popup shortly to turn on <b>device location</b>, which uses <annotation font="digital" textSize="text_size">Google\'s</annotation> location service.\n\n
For the app to work properly choose <b>OK</b>
</string>
Customizing image-resources
If you dont want to use our bottom dialog view you can replace it with your own drawable-resource:
