Receive Installation Notifications

DT can send installation progress notifications asynchronously via callbacks or broadcasts. Specify one or both of these notification mechanisms when you call the install() method.

Notifications by Callback

The IResponseCallback interface is a callback included in the DTIS SDK designed specifically for DTIS notifications. To have installation statuses sent to this callback, specify the IResponseCallback interface in the callback parameter when you call the install() method.

The following code snippets demonstrate how to integrate callbacks for DTIS:

• Install App by Package Name and Receive Callback

• Install App by Package Name and Receive Callback and Broadcast

• Install App by URI and Receive Callback

• Install App by URI and Receive Callback and Broadcast

Callback Methods

The IResponseCallback interface uses the following methods to capture installation status updates from Ignite:

Kotlin

interface IResponseCallback {
    /**
     * Called when response is successful
     *
     * @param result result of the operation of the type [R]
     */
    fun onSuccess(result: R)

    /**
     * Called when any error occurred during communication
     *
     * @param error error description of the type [E]
     */
    fun onError(error: E)

    /**
     * Called when Ignite notifies about the task progress
     *
     * @param progress contains [Progress] provided by Ignite
     */
    fun onProgress(progress: P) {
        // Do nothing by default
    }

    /**
     * Called when Ignite started task execution
     *
     * @param taskInfo contains any task info provided by Ignite [TaskInfo]
     */
    fun onStart(taskInfo: TaskInfo) {
        // Do nothing by default
    }

    /**
     * Called when Ignite scheduled task execution
     *
     * @param taskInfo contains any task info provided by Ignite [TaskInfo]
     */
    fun onScheduled(taskInfo: TaskInfo) {
        // Do nothing by default
    }
    }

Callback Error Codes

DT sends the following error codes in callbacks.

ERROR	CODE	DESCRIPTION	HTTP Response
INTEGRATOR_NOT_ENABLED	15, 4000	Host App access to the Ignite Services API not enabled	403 Forbidden
PACKAGE_NOT_IN_INTEGRATOR_INVENTORY	16, 4001	Target Package not in customer's inventory	403 Forbidden
PACKAGE_NOT_VALID_ON_ACTIVE_OPERATOR	17, 4002	Target Package not valid on active mobile network operator/carrier	403 Forbidden
INTEGRATOR_NOT_PERMITTED_ON_OPERATOR	18, 4003	Host App not permitted on mobile network operator/carrier	403 Forbidden
INTEGRATOR_NOT_CONFIGURED	19, 4006	Host App not configured in DT environment	404 Not Found
INTEGRATOR_NOT_PROVIDED	20, 4007	Host App not provided	-

Notifications by Broadcast

You can register a receiver specifically to listen for and process broadcasts from DTIS about your installation status. If you have more than one host app using the DTIS, DT sends broadcast notifications to the host app that initiated the app installation.

To receive installation notifications by broadcast:

1. Specify a receiver in your AndroidManifest.xml.

XML

<!-- ... -->
<receiver android:name="com.mycompany.myapp.MyInstallationBroadcastReceiver"
    android:enabled="true"
    android:exported="true">
    <intent-filter>
        <action android:name="com.digitalturbine.ignite.service.action.STATUS_CHANGED" />
    </intent-filter>
</receiver>
<!-- ... -->

2. Specify how you want to process the broadcasted installation status.

Kotlin

class MyInstallationBroadcastReceiver: BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        Log.i(TAG, "Install application intent=$intent")
        var progress = ""
        val percentage = intent?.getDoubleExtra(STATUS_PROGRESS, -1.0)
        if ((percentage ?: 0.0) > -1.0) {
            progress = "${percentage?.roundToInt()}%"
        }
        
        Log.i(TAG, "BroadcastReceiver: ${intent?.getStringExtra(STATUS_MESSAGE)} $progress")
        
        // Do other work related to the status
    }

    private companion object {
        const val STATUS_MESSAGE = "com.dt.ignite.service.extras.STATUS_MESSAGE"
        const val STATUS_PROGRESS: String = "com.dt.ignite.service.extras.STATUS_PROGRESS"
    }
}

1. Specify the receiver in the action parameter when you call the install() method for an app. For more information, see Install App.

   The following code snippets show how to specify broadcasts when calling the install() method:

   • Install App by Package Name and Receive Broadcast

   • Install App by Package Name and Receive Callback and Broadcast

   • Install App by URI and Receive Broadcast

   • Install App by URI and Receive Callback and Broadcast

Broadcast Notification Content

As the status changes for each installation, DT sends the following information:

• TASK_ID

• PACKAGE_ID

• PACKAGE_NAME

• STATUS

• STATUS_MESSAGE

• NONCE

Broadcast Status Codes

DT uses the following codes to characterize the status of an installation:

STATUS	CODE	STATUS_MESSAGE
STATUS_SUCCESS	0	Target APK installation complete.
STATUS_FAILURE	1	Target APK installation failed.
STATUS_FAILURE_BLOCKED	2	Target APK installation was prohibited by device policy or another app such as a package verifier.
STATUS_FAILURE_ABORTED	3	Target App installation stopped by device user either by declining requested permissions or abandoning the session.
STATUS_FAILURE_INVALID	4	Target APK installation failed because it was malformed, corrupt, mismatched, or incorrectly signed (failed SHA-256 check).
STATUS_FAILURE_STORAGE	5	Target APK installation failed because the device has insufficient storage capacity.
STATUS_FAILURE_CONFLICT	6	Target APK installation failed because it conflicts with another package already on the device.
STATUS_FAILURE_INCOMPATIBLE	7	Target APK installation failed because it is not compatible with device features (hardware or software).
STATUS_PROGRESS	8	Target APK installation in progress.
DOWNLOAD_STARTED	9	Target APK download started.
DOWNLOAD_FINISHED	10	Target APK download complete.
INSTALLATION_STARTED	11	Target APK installation started.

Examples

The following code snippets show how to specify installation notifications when calling the install() method to install an app.

Install App by Package Name and Receive Callback

The following code snippet shows how to call the install() method to install an app by its packageName and receive installation status via the IResponseCallback interface.

Kotlin

// Initialization

// Install application via package name string and listen to updates using callback
val packageName = "com.package.name"
IgniteServiceSdk.instance().install(packageName, buildSingleInstallationCallback())

// ...

private fun buildSingleInstallationCallback() = object : IResponseCallback<InstallationResponse, Error, InstallationProgress> {
    override fun onScheduled(taskInfo: TaskInfo) {
        Log.i(TAG, "Install application onScheduled(): taskId=${taskInfo.taskId}")
        
        // Store task id when scheduled to track it later if needed
        currentInstallTask = taskInfo.taskId
    }

    override fun onStart(taskInfo: TaskInfo) {
        Log.i(TAG, "Install application onStart(): taskId=${taskInfo.taskId}")
        
        // E.g. show indefinite progress as application installation task started
        showProgress()
    }

    override fun onProgress(progress: InstallationProgress) = with(progress) {
        Log.d(TAG, "Install application onProgress(): taskId=${taskId}, appId=${applicationId}, progress=${value}, action=$action")
        
        // E.g. show progress as application started download and installation
        showProgress()
        
        // 0 stands for download progress
        // 1 stands for install progress
        when (action) {
            0 -> updateDownloadProgress(value)
            1 -> updateInstallProgress(value)
        }
    }

    override fun onSuccess(result: InstallationResponse) {
        Log.d(TAG, "Install application onSuccess(): taskId=${result.taskId}, appId=${result.applicationId}, package=${result.packageName}")
        
        // E.g. hide progress as application is installed succesfully
        hideProgress()
    }

    override fun onError(error: Error) {
        Log.e(TAG, "Install application onError(): ${error.message}")
        hideProgress()
    }

    private fun showProgress() = progressBar?.visibility = View.VISIBLE
    private fun hideProgress() = progressBar?.visibility = View.GONE
}

// ...

Install App by Package Name and Receive Broadcast

Before requesting an installation with broadcast notification, ensure that you register a receiver in your AndroidManifest.xml and specify how you want to process the information received in the broadcast. For more information, see Notifications by Broadcast.

Kotlin

// Initialization

// Install application via package name string and listen to updates using broadcast receiver action
val packageName = "com.package.name"
IgniteServiceSdk.instance().install(packageName, action = buildInstallAction())

// ...

private fun buildInstallAction() = Bundle().apply {
    putString("receiver", MyInstallationBroadcastReceiver::class.java.canonicalName)
}

// ...

// Below is the example of MyInstallationBroadcastReceiver class implementation to receive updates about installation

class MyInstallationBroadcastReceiver: BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        Log.i(TAG, "Install application intent=$intent")
        var progress = ""
        val percentage = intent?.getDoubleExtra(STATUS_PROGRESS, -1.0)
        if ((percentage ?: 0.0) > -1.0) {
            progress = "${percentage?.roundToInt()}%"
        }
        
        Log.i(TAG, "BroadcastReceiver: ${intent?.getStringExtra(STATUS_MESSAGE)} $progress")
        
        // Do other work related to the status
    }

    private companion object {
        const val STATUS_MESSAGE = "com.dt.ignite.service.extras.STATUS_MESSAGE"
        const val STATUS_PROGRESS: String = "com.dt.ignite.service.extras.STATUS_PROGRESS"
    }
}

Install App by Package Name and Receive Callback and Broadcast

Kotlin

// Initialization

// Install application via package name string and listen to updates 
// using callback and broadcast receiver action

val packageName = "com.package.name"
IgniteServiceSdk.getInstance().install(
    packageName,
    buildInstallationCallback(),
    buildInstallAction()
)

// ...

// See implementations of buildInstallationCallback() and buildInstallAction() in other examples

Install App by URI and Receive Callback

The following code snippet shows how to use the DTIS SDK to install an app by its URI and receive installation status through the IResponseCallback interface.

Kotlin

// Initialization

// Install application via uri string and listen to updates using callback
val file = File("${context.filesDir}", "MyFunGame.apk")
val uriString = file.toUri().toString()

IgniteServiceSdk.instance().install(uriString, buildSingleInstallationCallback())

// ...

private fun buildSingleInstallationCallback() = object : IResponseCallback<InstallationResponse, Error, InstallationProgress> {
    override fun onScheduled(taskInfo: TaskInfo) {
        Log.i(TAG, "Install application onScheduled(): taskId=${taskInfo.taskId}")
        
        // Store task id when scheduled to track it later if needed
        currentInstallTask = taskInfo.taskId
    }

    override fun onStart(taskInfo: TaskInfo) {
        Log.i(TAG, "Install application onStart(): taskId=${taskInfo.taskId}")
        
        // E.g. show indefinite progress as application installation task started
        showProgress()
    }

    override fun onProgress(progress: InstallationProgress) = with(progress) {
        Log.d(TAG, "Install application onProgress(): taskId=${taskId}, appId=${applicationId}, progress=${value}, action=$action")
        
        // E.g. show progress as application started donwload and installation
        showProgress()
        
        // 0 stands for download progress
        // 1 stands for install progress
        when (action) {
            0 -> updateDownloadProgress(value)
            1 -> updateInstallProgress(value)
        }
    }

    override fun onSuccess(result: InstallationResponse) {
        Log.d(TAG, "Install application onSuccess(): taskId=${result.taskId}, appId=${result.applicationId}, package=${result.packageName}")
        
        // E.g. hide progress as application is installed succesfully
        hideProgress()
    }

    override fun onError(error: Error) {
        Log.e(TAG, "Install application onError(): ${error.message}")
        hideProgress()
    }

    private fun showProgress() = progressBar?.visibility = View.VISIBLE
    private fun hideProgress() = progressBar?.visibility = View.GONE
}

// ...

Install App by URI and Receive Broadcast

Before requesting an installation with broadcast notification, ensure that you register a receiver in your AndroidManifest.xml and specify how you want to process the information received in the broadcast. For more information, see Notifications by Broadcast.

Kotlin

// Initialization

// Install application via uri string and listen to updates
// using callback and broadcast receiver action
val file = File("${context.filesDir}", "MyFunGame.apk")
val uriString = file.toUri().toString()

IgniteServiceSdk.instance().install(
    uriString,
    buildInstallationCallback(),
    action = buildInstallAction()
)

// ...

// See implementations of buildInstallationCallback() and buildInstallAction() in other examples 

Install App by URI and Receive Callback and Broadcast

Kotlin

// Initialization

// Install application via uri string and listen to updates
// using callback and broadcast receiver action
val file = File("${context.filesDir}", "MyFunGame.apk")
val uriString = file.toUri().toString()

IgniteServiceSdk.instance().install(
    uriString,
    buildInstallationCallback(),
    action = buildInstallAction()
)

// ...

// See implementations of buildInstallationCallback() and buildInstallAction() in other examples