Developing with the Kanzi Android Service¶

The Kanzi Android Service enables using the same Kanzi Android framework (droidfw) instance from multiple applications on your device. This is done by hosting Kanzi Android framework (droidfw) in an Android service in one application, and then utilizing it from all the client applications, using Android IPC mechanisms.

This enables the following capabilities:

Shared libraries. Optimizes static memory usage by reusing a single set of Kanzi libraries across the client applications.
Shared runtime and resources. Optimizes runtime memory and GPU usage by sharing the same Kanzi Engine and resources across the client applications.
Improved application startup time. Improves startup time by preloading Kanzi Engine and resources in the background.
Cross-application transition animations. Enables seamless transition animations between different applications using shared Kanzi resources.

For an example on how the Kanzi Android Service can be used, see Android Service example.

Note

Kanzi Android Service is an experimental feature, and your feedback is very important to us. To submit your feedback, use this feedback form.

Breakdown of the architecture¶

Service host application¶

This application hosts a Kanzi Android Service through the kzservice library. The service is responsible for initializing the Kanzi Android framework (droidfw), and through it the Kanzi runtime. The host application is where you bundle all your Kanzi assets, Kanzi native libraries and Kanzi Engine plugins.

Client applications¶

These are any number of applications on the same system that use the Kanzi functionality from the Service application. They access Kanzi using the view and composable types from the kzclient library.

Cross-application transition animations¶

Clients can request the service to perform seamless transition animations between different applications using shared Kanzi resources. This works by the service creating an overlay window that is visible on top of all other applications, and rendering the transition animation there. When the animation is done, the overlay window is hidden.

Example of cross-application transition animation

Getting started¶

You can create Kanzi Android Service project using the application template provided by Package Manager. See Installing the Package Manager.

In the Kanzi Studio New Project window:

Set Template to Kanzi Android Service based Application Template
Click Create.

Kanzi creates a Kanzi Studio project and two Android Studio application projects:
1. MyProjectHost service host application located in the <MyProject>Applicationandroid_service directory.
2. MyProjectClient application located in the <MyProject>MyProjectClient directory.

Using the Client API¶

This is the API that you use in your client applications to configure and communicate with the Kanzi Engine instance in the service application.

View and Composable types¶

You can add Kanzi content to your XML layout or Composables:

In XML layout, add

<com.rightware.kanzi.KanziServiceSurfaceView
    android:id="@+id/clientred"
    app:clientId="clientred"
    app:kzbPathList="clientred.kzb"
    app:startupPrefabUrl="kzb://clientred/StartupPrefab"
    />

Or in your composable, add:

KanziServiceComposable(
        Modifier,
        Request(
            clientId = "clientblue",
            kzbPathList = "clientblue.kzb",
            startupPrefabUrl = "kzb://clientblue/StartupPrefab"
        )
    )

where

clientId is a unique identifier each client must supply
kzbPathList is a comma-separated list of .kzb or .kzb.cfg files to be loaded for this client
startupPrefabUrl is the URL of the prefab that will be instantiated onto the client’s surface when it loads

Data source setters¶

You can obtain a KanziServiceClient reference, in view-based application as:

val clientX = findViewById(R.id.clientred) as KanziServiceClient

And in compose-based application as:

var kanziServiceClient: KanziServiceClient? by remember { mutableStateOf(null) }
KanziServiceComposable(
    ...
    callback = { kanziServiceClient = it },
)

Through this reference, you get access to setters pushDataInt, pushDataString``and ``pushDataReal. For example:

kanziServiceClient?.pushDataInt(
    "kzb://launcher/Data Sources/Scene Data source",
    "MainMenuScene",
    MainMenuScenes.HOME.value
)

You need to provide the KZB URL of the data source, the path to the data object, and the value to be pushed.

Using the Service API¶

This is the API that you use in the service host application to initialize and configure Kanzi Android framework (droidfw) through the Kanzi Java API.

You can perform pre-prefab-loading initializations using the InitCallback in the application onCreate method. This is where you must register all your Kanzi Engine Java plugins. For example:

override fun onCreate() {
    super.onCreate()
    KanziRuntimeRegistry.addInitCallback { runtime ->
        runtime.domain.registerPlugin(MyJavaPlugin())
    }
}

You can perform post-prefab-loading initializations as needed by using the PrefabLoadedCallback in the application onCreate method:

override fun onCreate() {
    super.onCreate()
    KanziRuntimeRegistry.addPrefabLoadedCallback("ClientA") { clientId, root, domain ->
        // Do something with the loaded prefab
    }
}

Setting up cross-application transition animations¶

To enable the cross-application transition animation feature:

Both client applications should use the same clientId and startupPrefabUrl in their KanziServiceSurfaceView or KanziServiceComposable.
Trigger transition animation before invoking any API that switches the activity. This will allow Kanzi Android Service to show the application overlay before the application transition start.

You can invoke changeActivity API call, providing the target application package name, the activity name, and the clientId to switch to the target app:
```
kanziServiceClient?.changeActivity(
    context = context,
    packageName = "com.example.clientred",
    activityName = "com.example.clientred.MainActivity",
    clientId = "clientred"
)
```
This will start the target application activity after showing the transition animation.

Alternatively, you can start the target application activity using an Intent by yourself after invoking startAnimation API call:
```
kanziServiceClient.startAnimation("clientId")
startActivity(intent)
```
After installation, the service host and the client applications involved in the animation need to manually allow the Display over other applications permission to be able to use the animation feature. Alternatively, signing the APK with the platform keys would work.

Note

On Android automotive devices it is not possible to grant the Display over other applications permission for newly installed applications using the Android UI.

Known issues¶

The service host application currently requires the Display over other applications permission, even if the animation feature is not used by any client.

Developing with the Kanzi Android Service¶

Breakdown of the architecture¶

Service host application¶

Client applications¶

Cross-application transition animations¶

Getting started¶

Using the Client API¶

View and Composable types¶

Data source setters¶

Using the Service API¶

Setting up cross-application transition animations¶

Known issues¶

See also¶