*Permissions wizard

Since 2.2.225 version we don't need access to phone's local storage and implemented more comfortable way to customize our Permissions wizard.

Overview

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:

startActivityForResult(
       PermissionsWizardActivity
               .getStartWizardIntent(
                       context = this,
                       enableAggressivePermissionsWizard  = false,
                       enableAggressivePermissionsWizardPage  = false
               ),
       PermissionsWizardActivity.WIZARD_PERMISSIONS_CODE
)

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>  

Activity recognition permission screen (since Android 10)

values/strings.xml

<!-- 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 &amp; 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:

1. Specify your font in resources (check documentation)
2. Specify annotation for the text with name font

Sample:

Add custom support library font

digital_font.xml

<?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:app="http://schemas.android.com/apk/res-auto">
    <font app:font="@font/digital" />
</font-family>

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

1. Add dimen resource of the

2. 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:

Specify drawable resource with the name:

// location permission screen image
ic_wizard_image_location

// background location permission screen image
ic_wizard_image_location_background

// activity recognition permission screen image
ic_wizard_image_activity_recognition

// device location screen image
ic_wizard_image_gps_sensor

// battery optimization permission screen image
ic_wizard_image_battery_optimization

// huawei autostart permission screen image
ic_wizard_autostart_huawei

// xiaomi autostart permission screen image
ic_wizard_autostart_xiaomi

// default autostart permission screen image
ic_wizard_autostart_default

// notifications showing permission screen image
ic_wizard_notifications_default

Customizing colors

values\colors.xml

<!-- Wizard -->
<color name="colorTelematicsWizardBackground">#FAFAFA</color>
<color name="colorTelematicsWizardPrimaryText">#494949</color>
<color name="colorTelematicsWizardSecondaryText">#80464646</color>
<color name="colorTelematicsWizardButtonText">#fff</color>
<color name="colorTelematicsWizardButtonNorm">#80464646</color>
<color name="colorTelematicsWizardButtonPressed">#464646</color>

<!-- Alert dialog inside wizard - common colors -->
<color name="colorTelematicsDialogAlertBackground">#fff</color>
<color name="colorTelematicsDialogAlertButtonActiveBg">#ff8400</color>
<color name="colorTelematicsDialogAlertText">#80464646</color>
<color name="colorTelematicsDialogAlertButtonActiveText">#fff</color>

<!-- Alert dialog inside wizard for Android =< 9 -->
<color name="colorTelematicsDialogAlertInactiveText">#009687</color>

<!-- Alert dialog inside wizard for Android >= 10 -->
<color name="colorTelematicsDialogAlertInactiveTextQ">#a7c7f9</color>

Customizing dimens

values\dimens.xml values-xhdpi\dimens.xml values-xxhdpi\dimens.xml

<!-- Overrided DialogFragment SDK resources -->
<dimen name="dialog_telematics_view_bubble_corners">20dp</dimen>
<dimen name="dialog_telematics_button_corners">35dp</dimen>

<!-- Overrided Wizard SDK resources -->
<dimen name="wizard_telematics_button_corners">5dp</dimen>