Third-party Integration with Android Service v2.x

Note

UF Service API v2.0 is exclusively compatible with UF Android Service v2.0 and is not backward compatible with UF Android Service v1.x. Please ensure that your target devices are running the correct service version.

This document provides a comprehensive overview of the UF Service API, a powerful library designed to streamline communication between your app and the UF Android Service.

The UF Android Service is a robust background service that manages the entire lifecycle of device updates, from polling the server for new updates to downloading and installing them. By integrating the UF Service API into your application, you can programmatically interact with the UF Android Service, enabling you to create a seamless and customized update experience for your users.

Key Features

The UF Service API empowers your application to:

• Monitor Service Status: Keep track of the UF Android Service's current state and react to changes in real-time.
• Control Update Flow: Programmatically grant or deny authorization for downloading and installing updates, giving you full control over the update process.
• Force Server Polls: Manually trigger a check for new updates, ensuring that your devices are always up-to-date.

A practical example of these features is available in the UF Service API Reference Implementation. The application's APK and source code are available in Kynetics' Maven repository, and we recommend reviewing them for a better understanding of the library's capabilities.

API Compatibility

The UF Service API is designed to work with specific versions of the UF Android Service. The following table outlines the compatibility between the API and the service:

API	UF Android Service
v2.0.0	≥ v2.0.0 (version code 19900)

Getting Started

Installation

To integrate with UF Service API, you need access to Kynetics' private Maven repository. Please contact us to request access.

The UF Service API library is hosted on Kynetics' private Maven repository. To add it to your project, follow these steps:

1. Configure the repository in your settings.gradle.kts file:

   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           maven {
               name = "KyneticsRepo"
               url = uri("https://nexus.kynetics.com/repository/kynetics-uf")
               credentials(PasswordCredentials::class)
           }
       }
   }
   

2. Add your Nexus Maven credentials to your ~/.gradle/gradle.properties file:

   KyneticsRepoUsername=<username>
   KyneticsRepoPassword=<password>
   

3. Add the UF Service API dependency to your app/build.gradle.kts file:

   dependencies {
       implementation("com.kynetics.android:uf-service-api:v2.0.0-beta01")
   }
   

Establishing a Connection

The UFServiceManager is the heart of the UF Service API. It's a singleton class that manages the connection to the UF Android Service and provides a clean, intuitive API for interacting with it.

To start, get an instance of the UFServiceManager:

/**
 * An instance of the UFServiceManager, which serves as the primary entry point for interacting
 * with the Update Factory Service. This manager handles service connection, communication,
 * and provides methods to control and query the update process.
*/
private val ufServiceManager: UFServiceManager = UFServiceManagerFactory.getInstance()

Next, implement the com.kynetics.android.uf.service.api.UFServiceListener interface in your Activity or Service. This interface is crucial for receiving events and state changes from the UF Android Service.

Finally, initiate the connection:

ufServiceManager.startServiceConnection(
    context = this@MainActivity,
    keepAlive = true,
    listener = this@MainActivity
)

Once the connection is established, the UFServiceListener callbacks will be invoked, providing you with real-time updates on the service's status.

Example Implementation

Here's a basic example of how to connect to the UF Android Service from an Activity:

package com.kynetics.android.uf.app.activity

import android.util.Log
import androidx.activity.ComponentActivity
import com.kynetics.android.uf.service.api.UFServiceListener
import com.kynetics.android.uf.service.api.UFServiceManager
import com.kynetics.android.uf.service.api.UFServiceManagerFactory
import com.kynetics.android.uf.service.api.model.AuthorizationRequestType
import com.kynetics.android.uf.service.api.model.UFServiceConfiguration
import com.kynetics.android.uf.service.api.model.UFServiceMessage

class MainActivity : ComponentActivity(), UFServiceListener {

    private val ufServiceManager: UFServiceManager = UFServiceManagerFactory.getInstance()

    override val ufServiceListenerID: String = "MainActivity"

    override fun onStart() {
        super.onStart()
        ufServiceManager.startServiceConnection(
            context = this,
            keepAlive = true,
            listener = this
        )
    }

    override fun onStop() {
        ufServiceManager.unRegisterListener(this)
        super.onStop()
    }

    override fun onAuthorizationRequest(authorizationType: AuthorizationRequestType) {}
    override fun onCurrentServiceConfiguration(configuration: UFServiceConfiguration) {}

    override fun onServiceConnected() {
        Log.d("MainActivity", "Service connected")
    }
    override fun onServiceDisconnected() {
        Log.d("MainActivity", "Service disconnected")
    }
    override fun onServiceEvent(event: UFServiceMessage.Event) {
        Log.d("MainActivity", "Service event received: ${event.name}")
    }
    override fun onServiceStateChange(state: UFServiceMessage.State) {
        Log.d("MainActivity", "Service State Changed. New state: ${state.name}")
    }

}

Core Concepts

Service Configuration

To configure the UF Android Service, you need to create an instance of the UFServiceConfiguration class and pass it to the configureService method. This class holds all the necessary parameters for the service to operate correctly, such as the tenant, controller ID, and server URL.

val ufConfigurations = UFServiceConfiguration(
    tenant = <tenant_name>,
    controllerId = <controller_id>,
    url = <uf_server_url>,
    targetToken = <target_token>
)
ufServiceManager.configureService(ufConfigurations)

If the configuration is valid, the UF Android Service will begin polling the server for updates and will report its status through the UFServiceListener callbacks. If the configuration is invalid, a UFServiceException.UFServiceConfigurationInvalidException will be thrown.

You can retrieve the current service configuration at any time by calling ufServiceManager.getCurrentServiceConfiguration().

Note

For security reasons, the returned UFServiceConfiguration object does not include security tokens. However, the securityMethod property will indicate the authentication method currently in use.

Synchronization

To get the latest state and configuration from the UF Android Service, use the syncWithService method:

ufServiceManager.syncWithService()

This will trigger the onServiceStateChange() and onCurrentServiceConfiguration() callbacks, providing you with the most up-to-date information.

Authorization

In "API mode," the UF Android Service will request authorization from your application before downloading or installing an update. You can grant authorization using the grantAuthorization method:

ufServiceManager.grantAuthorization(AuthorizationRequestType.DOWNLOAD)
// or
ufServiceManager.grantAuthorization(AuthorizationRequestType.UPDATE)

Force Ping

You can manually trigger a server poll using the forcePing method. This is useful for ensuring that a device checks for updates immediately, rather than waiting for the next scheduled poll.

ufServiceManager.forcePing(autoScheduleIfDebounced = true)

To prevent excessive server load, forcePing requests are debounced. If a forcePing is called within 30 seconds of a previous one, it will be ignored. By setting the autoScheduleIfDebounced flag to true, you can ensure that the poll will be executed as soon as the debounce period is over.

API Reference

UFServiceConfiguration

This data class encapsulates the configuration parameters for the UF Android Service.

Property	Description
tenant	The name of your Update Factory tenant.
controllerId	A unique identifier for the device.
url	The URL of the Update Factory server.
targetToken	The device's security token for authenticating with the server.
gatewayToken	A shared token for authenticating multiple devices.
isApiMode	If true, the service will request authorization from your app before updates. If false, it will show a pop-up window. (Default: true)
isEnable	Enables or disables the service. (Default: true)
targetAttributes	A map of custom attributes to send to the server.
timeWindows	Defines time slots for forced updates using a cron expression and duration.

UFServiceMessage

This sealed class represents the various states and events that the UF Android Service can emit.

Statesc

• Downloading: The service is currently downloading an update.
• Updating: The service is installing an update.
• CancellingUpdate: The service is canceling an ongoing update.
• WaitingDownloadAuthorization: The service is waiting for your app to authorize a download.
• WaitingUpdateAuthorization: The service is waiting for your app to authorize an installation.
• WaitingUpdateWindow: The service is waiting for a valid time window to apply a forced update.
• Idle: The service is idle and waiting for new instructions.
• ConfigurationError: The service has encountered a configuration error.

Events

• Polling: The service is contacting the server to check for new updates.
• StartDownloadFile: A file download has started.
• FileDownloaded: A file has been successfully downloaded.
• DownloadProgress: Reports the progress of a file download.
• AllFilesDownloaded: All files for the current update have been downloaded.
• UpdateFinished: The update process has finished.
• Error: An error has occurred.
• UpdateProgress: Reports the progress of the update installation.
• UpdateAvailable: A new update is available on the server.
• Started: The service has started.
• Stopped: The service has stopped.
• CantBeStopped: The service cannot be stopped, usually because an update is in progress.
• ConfigurationUpdated: The service configuration has been updated.
• NewTargetTokenReceived: A new target token has been received from the server.
• NoNewState: A forcePing was performed, but no new state was found on the server.

Additional Resources

• Kynetics - Update Factory
• Kynetics Technical note on Update Factory
• Kynetics Slideshare