Naming conventions

Activation PowerAuth activation inside the PowerAuthSDK instance which user enrolled.
Activation Data Data retrieved from the server by the Source App that can activate Target App.
Source App Application that is starting the activation spawn process with a valid Activation.
Target App Application that will be installed (if not already) and activated.

Integrating into the Source App

Prerequisite of an application that will activate the Target App is properly configured and activated PowerAuthSDK instance.

  1. Define the Target App in your code:

  val application = SpawnableApplication(
	    // package name of the app
	    // url deeplink scheme 
	    // needs to be provided by the powerauth backend administrator at your company 
  1. If your application targets Android 11+ (SDK 30+), you need to declare the query “permissions” for the package name of Target App in the AndroidManifest.xml of the Source App. Otherwise, you won’t be able to detect if the app is already installed.

For more information, visit official documentation

Enable queries in the manifest

Enable queries inside the Android manifest.

Enable all queries in the manifest

You can also enable all queries inside the Android manifest. This approach is not recommended if not needed otherwise.

  1. Integrate into your ViewModel.
  • Sample implementation:

    import android.content.Context
    import androidx.lifecycle.ViewModel
    import kotlin.jvm.Throws
    class SampleViewModel(powerAuth: PowerAuthSDK, appContext: Context): ViewModel() {
        // Additional data for generator (must be the same for both Source and Target App).
        var additionalData: ByteArray? = null
        // Additional data for transport (must be the same for both Source and Target App).
        var sharedInfo: ByteArray? = null
        // application that can be activated
        val application = SpawnableApplication("com.mycompany.myapp", "myappdeeplink", "123")
        // Note that the generator configuration must be the same
        // for both Target and Source App. Please consult with Wultra
        // what configuration suits your needs.
        private val generator = DeviceFingerprintGenerator.getSemiStable(appContext, false, 10, additionalData)
        // manager that handles the activation
        private val manager = powerAuth.createSpawnManager(appContext, SSLValidationStrategy.default(), generator, "")
        fun isAppInstalled(): Boolean {
            return manager.isInstalled(application)
        fun installApp() {
            // SpawnManager will open store with the application page.
            return manager.openStore(application)
        fun activationApp() {
            // You need to authenticate the user with 2-factor scheme.
            // Note that for this you need to prompt the user for PIN code/password
            // or use biometry with "auth.useBiometry = true".
            // For demo purposes, we assume that the user has pin 1234.
            val auth = PowerAuthAuthentication()
            auth.usePossession = true
            auth.usePassword = "1234" // for demo purposes
            manager.retrieveActivationData(application, auth, object : IRetrieveActivationDataListener {
                override fun onSuccess(data: ActivationSpawnData) {
                    try {
                        val tag = "User123" // tag that will be transported along with the activation data
                        val annotation = "MyDemoApp" // to tell the target app who opened it
                        // Send it to the Target App. This might prompt the user if he wants to
                        // open the application.
                        manager.transportDataToApp(data, application, tag, annotation, sharedInfo)
                    } catch (t: Throwable) {
                        // process transport exception
                override fun onError(error: ApiError) {
                    // show error to user

Integrating into the Target App

  1. Declare a URL scheme for the application to enable digesting the deeplink.

Deeplink scheme settings

  1. Retrieve the activation data from a deeplink and prepare the PowerAuth activation.

     import android.os.Bundle
     class TestActivity: Activity() {
         // dependencies you need to prepare
         private lateinit var manager: ActivationSpawnManager
         private lateinit var powerAuth: PowerAuthSDK
         // Additional data for transporter (must be the same for both Source and Target App).
         private val sharedInfo: ByteArray? = null
         override fun onCreate(savedInstanceState: Bundle?) {
             val data =
             if (data != null) {
                 try {
                     val annotation = appManager.validateDeeplink(it).getOrNull()?.annotation
                     val transportData = manager.processDeeplink(data, sharedInfo)
                     if (annotation == "MySourceApp") {
                         // do something based on the source app
                     if (transportData.tag != null) {
                     	// do something with the tag data
                     powerAuth.createActivation(activationData, "Simon's phone", object : ICreateActivationListener {
                         override fun onActivationCreateSucceed(result: CreateActivationResult) {
                             // continue with the activation
                         override fun onActivationCreateFailed(t: Throwable) {
                             // process the error
                 } catch (t: Throwable) {
                     // deeplink cannot be processed

Passing additional data

For your convenience, you can pass additional data from the Source App to the Target App. There are 2 different types of custom string data that you can pass:


Annotation is a string in the deeplink and is accessible without the need to decrypt the data.

This is good for example if you want to pass some data that will help you with decoding, like the id of the Source App or other public data. Always assume that the annotation data can be logged as plain-text in the system console.

Example usage of annotation:

// In the source app:
manager.transportDataToApp(data, application, null, "annotationData", sharedInfo)

// In the target app
	.onSuccess { 
       // validated
		Log.d("aspawn", it.annotation) // prints "annotationData"
    }.onFailure { 
      // invalid activation spawn deeplink


A tag is a string in the encrypted data and is accessible only after successful transport data decryption.

This is good for example if you want to pass some data that will help you during the activation process in the Target App, like an ID of the user or other sensitive data.

Example usage of tag:

// In the source app:
manager.transportDataToApp(data, application, "user1", null, sharedInfo)

// In the target app
val data = appManager.processDeeplink(url)
Log.d("aspawn", data.tag) // prints "user1"

Error handling and logging

If you have a problem with syncing your Source and Target App configuration, we recommend turning on debug logging by ActivationSpawnLogger.verboseLevel = ActivationSpawnLogger.VerboseLevel.DEBUG


All methods that can produce an error are throwing various exceptions (as described in the in-code documentation).

All exceptions use message property where details about the exception and possible solutions are explained (in the description property). We highly recommend logging these exceptions into your log system as they provide great debug value about what went wrong.

ProcessDeeplinkException and TransportDataException exceptions contain reason property with the enum value of the error description for convenience.


The library is intensively logging into the console via ActivationSpawnLogger.

Possible log levels:

  • DEBUG - Debug logging that outputs more granular data, use this only during development
  • INFO - prints info logs + logs for warning level produced by the library (default level)
  • WARNING - prints warnings and errors
  • ERROR - prints errors only
  • OFF - logging is turned off

You can set the log level by ActivationSpawnLogger.verboseLevel = ActivationSpawnLogger.VerboseLevel.OFF.

ActivationSpawnLogger calls internally android.util.Log class.

Last updated on Mar 04, 2024 (21:32) Edit on Github Send Feedback


Activation Spawn SDK for Android