Prerequisite

Before starting DriveKit Permissions Utils UI integration, make sure that you have initialized Common UI module, especially if you have disabled the SDK auto-initialization.

Integration

The Permissions Utils UI SDK is available on Swift Package Manager and Cocoapods master repo.

Swift Package Manager

Via Xcode:

• In Xcode, if not yet done, add the DriveKitUI SDK by navigating to File > Add Package Dependencies… and in the prompt that appears, enter the DriveKitUI repository: https://github.com/DriveQuantPublic/drivekit-ui-ios.git

• Include DriveKitPermissionsUtilsUI in your app.

Via Package.swift:

• If not yet done, to integrate DriveKitUI to a Swift package via a Package.swift file, you can add DriveKitUI to the dependencies array of your package. For more details, see the Swift Package Manager documentation.

dependencies: [
  .package(name: "DriveKitUI",
           url: "https://github.com/DriveQuantPublic/drivekit-ui-ios.git",
           from: "2.0.0"),
  // ...
],

• Then in your target, add DriveKitPermissionsUtilsUI to the dependencies array of that target:

.target(
  name: "MyTarget",
  dependencies: [
    .product(name: "DriveKitPermissionsUtilsUI", package: "DriveKitUI"),
    // ...
  ]
),

Cocoapods (deprecation scheduled for the end of 2025)

Add the following lines to your Podfile:

target 'MyTarget' do
  pod 'DriveKitPermissionsUtilsUI'
end

Then, run pod install

Initialization

If you have disabled the SDK auto-initialization, the Permissions Utils UI module must also be manually initialized. In the application's AppDelegate file, import DriveKitPermissionsUtilsUI:

import DriveKitPermissionsUtilsUI

Then, to initialize the Permissions Utils module in your app, you must call the initialization method in didFinishLaunchingWithOptions method of your AppDelegate:

import DriveKitCoreModule
import DriveKitCommonUI
import DriveKitPermissionsUtilsUI

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
   DriveKitUI.shared.initialize()
   DriveKitPermissionsUtilsUI.shared.initialize()
   ...
}

Permission management

On iOS, the user must grant access permission to the phone's location in background to enable the trip detection function included in the Trip Analysis component. There are several options for this permission and automatic mode will only work if the user selects the "Always" option.

The Permissions Utils component provides a set of screens to guide the user through the selection of the right options. Once the user has correctly authorized access to the location, you are warned by the closure passed in parameter:

DriveKitPermissionsUtilsUI.shared.getLocationPermissionViewController {
    // Code called when location permission is properly granted.
}

It is also recommended that the user allows access to activity recognition (aka "Motion and fitness"). The Permissions Utils component contains a dedicated screen to help the user:

DriveKitPermissionsUtilsUI.shared.getActivityPermissionViewController {
    // Code called when activity permission is properly granted.
}

The method below helps you to configure the required permission requests and the order in which they are displayed. You will be notified when the requested permissions are successfully granted:

DriveKitPermissionsUtilsUI.shared.showPermissionViews([.location, .activity], parentViewController: <UINavigationController>) {
    // Code called when permissions (here: "location" and "activity"), are both properly granted.
}

SDK diagnosis

Diagnosis screen areas

The diagnosis screen is divided into three areas:

1. The first displays the status of sensors and permissions.

2. The second contains a quick link to the battery optimization functions.

3. The third displays a contact button to reach support.

The first two areas are always displayed. The third is optional.

The diagnosis function of the SDK has the following configurations:

• In area 1, the sensors and permissions to be checked are selected automatically except for the Bluetooth sensor. If your application does not use a Bluetooth device or an iBeacon, it is not necessary to monitor the status of the Bluetooth sensor.

• Area 2 is always displayed. If battery optimization is enabled, a link will appear to redirect the user to the phone settings. The user will have to open the battery settings to disable the optimization.

• In area 3, it is possible to configure the recipient's email address for the support request or a web address to which the user can be directed.

Bluetooth sensor status check

Access to the Bluetooth sensor is not required on iOS. This permission is not requested when the application is first installed.

For natural triggering (i.e. from the phone's sensors), or using an iBeacon, Bluetooth access is not required.

Access to the Bluetooth sensor is required in the two cases described below:

1. To enable automatic start of trip recording from a Bluetooth device.

2. To measure the battery level of an iBeacon device.

Support Request Management

The user can make a support request if the application does not work properly.

When the user clicks on the support request button, you can choose between two actions:

1. An email will be automatically composed,

2. or a redirection to a web page of your choice will be made.

The email contains the key information to ease the diagnosis of a problem (status of permissions and phone sensors). The recipient's email is configurable, as well as other parameters:

import DriveKitCoreModule
import DriveKitCommonUI
import DriveKitPermissionsUtilsUI

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      DriveKitUI.shared.initialize()
      DriveKitPermissionsUtilsUI.shared.initialize()
      ...
      DriveKitPermissionsUtilsUI.shared.configureContactType(
         DKContactType.email(MailConfiguration())
      )
   }
}

class MailConfiguration: DKContentMail {
    func getRecipients() -> [String] {
        ["support@company.com"]
    }

    func getBccRecipients() -> [String] {
        []
    }

    func getSubject() -> String {
        "[App] Technical support request"
    }

    func getMailBody() -> String {
        ""
    }

    func overrideMailBodyContent() -> Bool {
        false
    }
}

If you don’t want the email body to contain information about the state of permissions and sensors, then return “true” in the method “overrideMailBodyContent()”.

If you want to redirect the user to a web page instead of composing an email, you have to add the following line:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
   DriveKitUI.shared.initialize()
   DriveKitPermissionsUtilsUI.shared.initialize()
   ...
   DriveKitPermissionsUtilsUI.shared.configureContactType(DKContactType.web(<url>))
}

In this specific case, there is no way to obtain information about authorization and sensor status.

If you do not configure the contact type, this area will be hidden and will not appear on the diagnosis screen.

Prerequisite

Before starting DriveKit Permissions Utils UI integration, make sure that you have initialized Common UI module, especially if you have disabled the SDK auto-initialization.

Integration

To add the Permissions Utils UI module to your app, add the following line to your dependencies in your application build.gradle file:

dependencies {
    implementation 'com.drivequant.drivekit:drivekit-permissions-utils-ui:$drivekitui_version'
}

On a Github repository, you can find a demo app and the source code of Permissions Utils UI that you can use as an example.

Initialization

If you have disabled the SDK auto-initialization, the Permissions Utils UI module must also be manually initialized.

Then, to initialize the module in your app, you must call the initialization method in onCreate method of your Application class:

fun initialize()

Permission management

On Android, the user must grant the SDK access to:

• the phone's location and background activity monitoring to enable the trip detection function included in the Trip Analysis component;

• the Nearby Devices permission to detect Bluetooth devices;

• the background execution authorization to avoid the application being stopped by the power saving system.

Starting from Android 13, the user also needs to authorize the app to send notifications.

The Permissions Utils component provides a set of screens to guide the user through the selection of the right options.

Once all permissions have been granted by the user, you are warned by the closure passed in parameter:

PermissionsUtilsUI.showPermissionViews(this, object : PermissionViewListener {
       override fun onFinish() {
          //Code called when all permissions in the list are properly granted
       }
   })

PermissionsUtilsUI.INSTANCE.showPermissionViews(this, new PermissionViewListener() {
   @Override
   public void onFinish() {
       //Code called when all permissions in the list are properly granted
   }
});

The Permissions Utils component automatically manages the permission request workflow depending on the version of Android installed on the user's smartphone.

SDK diagnosis

Diagnosis state

Each monitored setting has three levels of criticity defined by the enum PermissionStatus : VALID, NOT_VALID and WARNING.

• VALID: The setting is correctly configured (device sensor is ON and/or permission is authorized). There is no error and the trip analysis will work well.

• NOT_VALID: The setting is not correctly configured (device sensor is OFF and/or permission is declined). There is an error and the trip analysis will not work as expected.

• WARNING: The setting is not correctly configured, but it will not affect the trip analysis.

Diagnosis screen areas

The diagnosis screen is divided into three areas:

1. The first displays the status of sensors and permissions.

2. The second contains a quick link to the battery optimization functions.

3. The third displays a contact button to reach support.

The first two areas are always displayed. The third is optional.

The diagnostic function of the SDK has the following configurations:

• In area 1, the sensors and permissions to be checked are selected automatically except for the Bluetooth sensor. If your application does not use a Bluetooth device or an iBeacon, it is not necessary to monitor the status of the Bluetooth sensor.

• Area 2 is always displayed if the Android version includes power-saving features (introduced from Android 6.0 - API level 23).

• In area 3, it is possible to configure the recipient's email address for the support request or a web address to which the user can be directed.

To use the app diagnosis display into your app, you must enter the following lines of code:

DriveKitNavigationController.permissionsUtilsUIEntryPoint?.let {
   it.startAppDiagnosisActivity(this)
}

PermissionsUtilsUIEntryPoint permissionsUtilsUIEntryPoint = DriveKitNavigationController.INSTANCE.getPermissionsUtilsUIEntryPoint();
if (permissionsUtilsUIEntryPoint != null) {
   permissionsUtilsUIEntryPoint.startAppDiagnosisActivity(this);
}

Bluetooth sensor status check

For natural triggering (i.e. from the phone's sensors), Bluetooth access is not required.

Access to the Bluetooth sensor is required in the two cases described below:

1. To enable automatic start of trip recording from an iBeacon device.

2. To enable automatic start of trip recording from a Bluetooth device.

Support Request Management

The user can make a support request if the application does not work properly.

When the user clicks on the support request button, you can choose between two actions:

1. An email will be automatically composed,

2. or a redirection to a web page of your choice will be made.

The email contains the key information to ease the diagnosis of a problem (status of permissions and phone sensors). The recipient's email is configurable, as well as other parameters:

PermissionsUtilsUI.configureContactType(ContactType.EMAIL(object : ContentMail {
   override fun getBccRecipients(): List<String> {
       //return a list of bcc recipients
   }

   override fun getMailBody(): String {
       //return mail body
   }

   override fun getRecipients(): List<String> {
       //return list of recipients
   }

   override fun getSubject(): String {
       //return mail body message
   }   

   override fun overrideMailBodyContent() {
      //return true if you want to override the default support mail body 
   }
})

PermissionsUtilsUI.INSTANCE.configureContactType(new ContactType.EMAIL(
       new ContentMail() {
           @NotNull
           @Override
           public List<String> getRecipients() {
               //return list of recipients
           }

           @NotNull
           @Override
           public List<String> getBccRecipients() {
               //return a list of bcc recipients
           }

           @NotNull
           @Override
           public String getSubject() {
                //return subject            
           }

           @NotNull
           @Override
           public String getMailBody() {
                //return mail body message
           }

           @Override
           public boolean overrideMailBodyContent() {
               //return true if you want to override the default support mail body
           }
       }
));

If you want to redirect the user to a web page instead of composing an email, you have to add the following line:

PermissionsUtilsUI.configureContactType(ContactType.WEB(Uri.parse("https://www.docs.drivequant.com")))

PermissionsUtilsUI.INSTANCE.configureContactType(new ContactType.WEB(Uri.parse("https://www.docs.drivequant.com/")));

In this specific case, there is no way to obtain information about authorization and sensor status.

If you do not configure the contact type, this area will be hidden and will not appear on the diagnosis screen.

fun configureContactType(contactType: ContactType)

PermissionsUtilsUI.INSTANCE.configureContactType(ContactType.NONE.INSTANCE);