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"
    app:serviceHostPackage="com.example.host"
    app:serviceIntentAction="com.example.host.action.LAUNCH_SERVICE"
    />

Or in your composable, add:

KanziServiceComposable(
        Modifier,
        Request(
            clientId = "clientblue",
            kzbPathList = "clientblue.kzb",
            startupPrefabUrl = "kzb://clientblue/StartupPrefab"
            serviceHostPackage = "com.example.host",
            serviceIntentAction = "com.example.host.action.LAUNCH_SERVICE"
        )
    )

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.
serviceHostPackage is the Android package name of the application that hosts Kanzi Android Service.
serviceIntentAction is the Intent action that Kanzi Android Service uses to bind the client application with the service.

Ensure that serviceHostPackage and serviceIntentAction exactly match applicationId and the Intent action declared in the manifest file of your Service host application.

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.

Manual client detachment¶

By default, the client application does not explicitly detach from the service when the activity stops. As a result, the service continues running the associated Kanzi Engine instance and keeps the resources allocated for that client.

To explicitly detach, call handleClientAttached and handleClientDetached on the KanziServiceClient instance within the activity’s lifecycle methods.

override fun onStop() {
    super.onStop()
    kanziServiceClient?.handleClientDetached()
}

override fun onStart() {
    super.onStart()
    kanziServiceClient?.handleClientAttached()
}

Note

Manual detach is incompatible with the seamless transition feature. Do not call these methods if you are using cross-application transitions.

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 implement KanziServiceViewAdapterListener to listen for state changes in a KanziViewAdapter associated with a client application in your service host aplication.

For example, use the KanziServiceViewAdapterListener.onPrefabLoaded callback to access and modify the node tree instantiated from the startup prefab that you have configured.

override fun onCreate() {
    super.onCreate()
     KanziRuntimeCallbackRegistry.addViewAdapterListener(clientId, object : KanziServiceViewAdapterListener {
         override fun onAttachedToWindow(
             clientId: String,
             viewAdapter: KanziViewAdapter,
             domain: Domain
         ) {
               // Look up a child node starting from the root.
               val text = viewAdapter.root.lookupNode<TextBox2D>("#Text")
               // Set properties on a node.
               text.setProperty(TextBox2D.TextProperty, "Hello world!")            }
         }
     })

Setting up cross-application transition animations¶

Cross-application transition animations allow you to create seamless visual transitions when moving between different Android applications in your Kanzi project.

To set up a cross-application transition:

Call the startSeamlessTransition API with the following parameters:

clientId - The client ID that moves across Android applications.
duration - The duration of the transition animation.
kanziTransition - A lambda function that updates the Kanzi state to drive the visual transition.
androidTransition - A lambda function that initiates the Android-side application transition.

Ensure that both client applications use the same clientId and startupPrefabUrl in their KanziServiceSurfaceView or KanziServiceComposable components.

// Start a seamless transition between applications.
kanziServiceView?.startSeamlessTransition(
    clientId = "coverflow",
    duration = 2.seconds,
    kanziTransition = {
        // Update Kanzi state to drive the visual transition.
        kanziServiceView?.pushDataInt(
            "kzb://service/Data Sources/Data source",
            "State",
            1
        )
    },
    androidTransition = {
        // Launch the target application.
        val intent = Intent().apply {
            setClassName(
                "com.example.clientred",
                "com.example.clientred.MainActivity"
            )
            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        }
        startActivity(intent)
    }
)

When you call this API, Kanzi Android Service creates an overlay window that displays the animation during the application transition.

Cross-application transition animations require the Display over other applications permission. To grant this permission:
1. Install the service host and client applications on your device.
2. For each application involved in the transition:
  1. Open the device settings.
  2. Navigate to Apps > <ApplicationName> > Permissions.
  3. Enable the Display over other applications permission.
Note

On Android Automotive devices, you cannot grant the Display over other applications permission through the Android UI for newly installed applications.

As an alternative, you can sign the APK with platform keys to automatically grant this permission.

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¶

Manual client detachment¶

Using the Service API¶

Setting up cross-application transition animations¶

Known issues¶

See also¶