Skip to main content

Initialize the Android SDK

Rokt partners can use the Android SDK to display overlay or embedded placements, while Rokt brands can use it to record conversions for their campaigns. The Rokt Android SDK is deployed using Maven and Gradle.

note

Rokt's Android SDK contains ProGuard rules and does not require additional configuration.

All use cases of the SDK follow the same initial steps to integrate and initialize the SDK. At a high level, these steps are:

  1. Set up a workspace and enable the Rokt Gradle repository
  2. Add the Rokt Placement plugin
  3. Add the Rokt Android SDK module
  4. Initialize the Rokt Android SDK

Following these steps, the execute method of the SDK can then be used in various ways to suit the required use case.

Before you begin​

This guide assumes that you are familiar with Gradle and know how to install a plugin for Android development.

Setting up the Android SDK​

  1. Set up a workspace and enable the Rokt Gradle repository. To set up a repository, follow Gradle's instructions.
  2. Add the Rokt Widget plugin repository URL in the settings.gradle file for the project.
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven("https://apps.rokt.com/msdk")
    }
}

Or if you are using a version of Gradle lower than 7.0.0 where the repository settings are instead in the top-level build.gradle file, add the following in the build.gradle file.

 // file => build.gradle.kts (Project: ....)

allprojects {
    repositories {
        google()
        mavenCentral()
        maven("https://apps.rokt.com/msdk")
    }
}
  1. (Optional) If using a version catalog, add the Rokt Android SDK module to your libs.versions.toml (or other named catalog).
[versions]
roktsdk = "4.6.1"

[libraries]
roktsdk = { group = "com.rokt", name = "roktsdk", version.ref = "roktsdk" }
  1. Add the Rokt Android SDK module to build.gradle for the module.

With Version Catalog​

 // file => build.gradle.kts (Module: ...)

dependencies {
    ...
    implementation(libs.roktsdk)
    ...
}

Without Version Catalog​

 // file => build.gradle.kts (Module: ...)

dependencies {
    ...
    implementation('com.rokt:roktsdk:4.6.1')
    ...
}
  1. Initialize the Rokt SDK prior to using it in any activity. We recommend calling the init method from the LauncherActivity class.
caution

Contact Rokt to get the Rokt Account ID associated with your account. To test your integration, you can use the Rokt Account ID below, but you need to replace it with your unique Rokt Account ID before launching in production.

Test account ID: 222

import com.rokt.roktsdk.Rokt;

public class LauncherActivity extends Activity {
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        // The following will reveal a demo integration. To view your integration:
        // 1) Replace the integration test tag ID (222) with your unique Rokt Tag ID
        // 2) Replace Y.Y.Y with the application version
        Rokt.INSTANCE.init("222", "Y.Y.Y", LauncherActivity.this)
        ...
    }
}

Initializing with Fonts​

note

This functionality is supported from version 4.2.0 of the Rokt Android SDK.

Instead of or in addition to supplying your desired fonts on One Platform, you may choose to utilize the fonts already bundled with your application. This carries the advantage of removing the potential for fonts to be downloaded at initialization time, reducing network utilization and the chances of download errors. You may choose to either use font resources located in the assets directory of your application or to pass your own Typeface objects.

Using Font Assets​

You may utilize the fonts stored in the assets directory of your application. For this, you may pass a map to the init method that maps the fonts' postscript names to the filepath in the assets directory (where the assets directory is the root directory). The postscript names should match those being used in your layout, please check with your account manager if you are unsure.

import com.rokt.roktsdk.Rokt;

public class LauncherActivity extends Activity {
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        Map<String,String> fontFilePathMap = new HashMap<String, String>();
        fontFilePathMap.put("Arial-Bold", "fonts/arialbold.otf");
        Rokt.INSTANCE.init(
            "222",
            "Y.Y.Y",
            LauncherActivity.this,
            new HashSet<>(), // fontPostScriptNames can be empty 
            fontFilePathMap
        );
        ...
    }
}

Using Font Typefaces​

You may also use Typeface objects that you have created in your application. For this, you must pass a set of the fonts' postscript names to the init function, and later pass the Typefaces to the execute function (detailed in Adding a placement). 

import com.rokt.roktsdk.Rokt;

public class LauncherActivity extends Activity {
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        Set<String> fontPostScriptNames = new HashSet<String>();
        fontFilePathMap.add("Arial-Bold");
        Rokt.INSTANCE.init(
            "222",
            "Y.Y.Y",
            LauncherActivity.this,
            fontPostScriptNames
        );
        ...
    }
}

Receiving initialization status​

From version 4.6.1, the Rokt SDK provides 2 ways to receive the status of initialization:

Optional callback on initialize​

There is a callback in the Rokt.init method to notify when the initialization is completed and return the status.

import com.rokt.roktsdk.Rokt

public class LauncherActivity: Activity {
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        Rokt.init("222",
                  "Y.Y.Y",
                  this@LauncherActivity,
                  callback = object : Rokt.RoktInitCallback {
                      override fun onInitComplete(success: Boolean) {
                          Log.d("Rokt", "received init completed $success")
                      }
                  },
        )
        ...
    }
}

Global events API​

The SDK also provides the status as a stream through the Rokt.globalEvents API. SDK users can leverage the Kotlin Flow mechanism to consume the status.

// owner: LifecycleOwner
owner.lifecycleScope.launch {
    Rokt.globalEvents().collect { event ->
        if (event is RoktEvent.InitComplete)
            Log.d("Rokt", "received init completed $event")
    }
}

Debugging​

Use the Rokt.setLoggingEnabled(enable = true) API to enable debug logs from the Rokt SDK.

Next steps​

The subsequent steps depend on your use case for integration. Check out these topics for more:

Was this article helpful?