Getting started

Using the Android library will allow you to quickly implement remote notifications, use actionable analytics or display content in your app.

Pre-requisites

• An Actito app
• The latest version of Android Studio

Understanding the environments

Applications commonly operate across two primary environments: development and production.

• The development environment is used for feature implementation, debugging, and internal testing.
• The production environment represents the live deployment accessed by end users.

It is strongly recommended to assign distinct bundle identifiers to each environment (for example, com.example.app.dev for development and com.example.app for production). Maintaining separate identifiers allows both versions to coexist on the same device, ensures each build connects to the appropriate Actito environment, and prevents data or configuration conflicts.

In most configurations:

• The development environment corresponds to the debug build type.
• The production environment corresponds to the release build type.

Establishing a clear separation between environments minimizes the risk of deploying builds that target incorrect services.

An overview of the library

The Actito SDK is composed of multiple modules designed to integrate seamlessly with your application.

The core Actito module is required and provides the foundational functionality necessary for all Actito integrations.

Additional modules are optional and can be included as needed to extend the SDK's capabilities — for example, in-app messages or an inbox.

This modular structure allows developers to include only the components relevant to their use case, ensuring optimal performance and reduced application size. In the app/build.gradle of your application, add the dependencies that you need.

dependencies {
    def actito_version = 'REPLACE_WITH_LATEST_VERSION'
    implementation "com.actito:actito:$actito_version"

    //
    // Optional modules
    //

    // Support for remote notifications
    implementation "com.actito:actito-push:$actito_version"

    // Our standard UI for notification (recommended)
    implementation "com.actito:actito-push-ui:$actito_version"

    // The tools to build a custom inbox UI
    // Choose one of the following modules depending on your use case
    implementation "com.actito:actito-inbox:$actito_version"
    implementation "com.actito:actito-user-inbox:$actito_version"

    // Automatically display in-app messages
    implementation "com.actito:actito-in-app-messaging:$actito_version"
}

Setting up the configuration file

To establish a connection between your application and Actito, you must download a configuration file for each environment your application supports. In most cases, this includes both development and production configurations.

Once downloaded, place each file in the following locations within your project:

• Production configuration: app/actito-services.json
• Development configuration: app/src/debug/actito-services.json

This approach uses Android's build configuration to determine which configuration file to use. You can read more about this approach in the Android documentation.

To make the values in your actito-services.json config file accessible to the Actito SDK, you need the Actito Services Gradle plugin (actito-services).

In your root-level (project-level) Gradle file (<project>/build.gradle.kts or <project>/build.gradle), add the Actito Services plugin as a dependency:

plugins {
  id("com.android.application") version "8.13.0" apply false
  // ...

  // Add the dependency for the Actito Services Gradle plugin
  id("com.actito.gradle.actito-services") version "1.0.0" apply false
}

In your module (app-level) Gradle file (usually <project>/app/build.gradle.kts or <project>/app/build.gradle), add the Actito Services plugin:

plugins {
  id("com.android.application")
  // ...

  // Add the Actito Services Gradle plugin
  id("com.actito.gradle.actito-services")
}

note

Including the actito-services.json file is the recommended approach. However, in some cases, you may prefer to configure the SDK directly in code. To do so, follow this guide.

Launching Actito

Before using any Actito features, the SDK must be initialized by invoking the launch() method. This process ensures that the Actito SDK is fully set up and ready to operate. Most SDK functionality will remain unavailable until this initialization occurs.

It is recommended to invoke the launch within your application's Application class:

class CustomApplication : Application() {
    private val applicationScope = MainScope()

    override fun onCreate() {
        super.onCreate()

        applicationScope.launch {
            try {
                // Launch Actito! 🚀
                Actito.launch()

                // Actito is now ready.
            } catch (e: Exception) {
                // Something went wrong ...
            }
        }
    }
}

Launching the SDK automatically registers the device with Actito. If your application requires user consent before collecting or registering device information, you may delay the initial launch until consent is granted.

Otherwise, ensure that launch() is called during the application's initialization phase to avoid missing important updates — particularly when the app is created in the background.

Unlaunching Actito

If your application needs to permanently disable Actito functionality, you can invoke the unlaunch() method. This method completely removes all Actito-related functionality and deletes any previously registered device information, both locally and remotely.

While this action is generally discouraged, it may be required in certain cases — such as when a user requests permanent account deletion or data removal — to ensure compliance with privacy and data protection regulations.

Actito.unlaunch()

caution

Once unlaunch() is invoked, all associated data is permanently destroyed and cannot be recovered. Any subsequent calls to Actito APIs will fail until the SDK is reinitialized using the launch() method.