Skip to main content

Android (3.3.0+)

Before I start

Piano Analytics SDKs have been designed for the Piano Analytics solution. Data sent through these SDKs will not be processed within the Analytics Suite 2. Since version 3.3.0, our Android SDK is written in Kotlin.

Integrate the library

The first step to use our SDK is to integrate our library in your project. You have multiple ways to do this.


Add this following line in your build.gradle file (app-level) under dependencies:

implementation("") // replace VERSION with the version you target

Add required Google/Huawei ID libraries, if you want to use it as Visitor ID

dependencies {

Add Huawei libraries repository (only if you've added Huawei ID library at the previous step)

repositories {


  1. Clone the Android SDK from our Github repository:

    • SSH:
    • HTTPS:
  2. From your Android Studio

    • Go to File > Project Structure > Modules
    • Click on the plus sign + and go to Import...
    • Search for the cloned directory and select the piano-analytics folder
    • Click on Finish
  3. After a sync of Gradle you might have an error like 'Build was configured to prefer settings repositories over project repositories'

    • Open your project-level settings.gradle file and replace/add the repositoriesMode as below
      • repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    • Resync Gradle
  4. As a support to Huawei in our SDK, you might also have a warning on sync (error on build) talking about a library from com.huawei.hms

    • For Gradle plugin earlier than 7.0

      • Open your project-level build.gradle file
      • Add the Maven repository as below under buildscript > repositories and allproject > repositories
        • maven {url ''}
    • For Gradle plugin 7.0

      • Open your project-level build.gradle file
      • Add the Maven repository as below under buildscript > repositories
        • maven {url ''}
      • Open your project-level settings.gradle file
      • Add the Maven repository as below under dependencyResolutionManagement > repositories
        • maven {url ''}
    • For Gradle plugin 7.1 or Later

      • Open your project-level settings.gradle file
      • Add the Maven repository as below under pluginManagement > repositories and dependencyResolutionManagement > repositories
        • maven {url ''}

piano-analytics should now be recognized as a library

Instantiate tracker

First of all, you should ensure that your app permissions are correctly set. You need the following permissions in your AndroidManifest.xml:

<!-- Allow the application to send events to Piano Analytics -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Allow to check network condition before trying to send events -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Our Android SDK requires you to configure and init a tracker before using it.

You should pass the application context as a parameter.

val configuration = Configuration.Builder(
collectDomain = "<xxxxxxx>",
site = 123456789,
// you can set other configurations here
// or set configurations via builder methods

PianoAnalytics.init(applicationContext, configuration)

Don't hesitate to read our collection methods article to find the collection domain that has been assigned to you.

You can also use a custom domain thanks to our CDDC.

Here are the available configurations:

TypeValueMore info
GlobalcollectDomainCollection domainstringhttps://<xxxxxxx>.pa-cd.comView
GlobalsiteSite idint123456789View
GlobalpathRequest pathstringevent
GlobaldetectCrashesEnable (true) or not (false) automatic crash detectionbooleantrue (default), false
GlobalsessionBackgroundDurationBackgound delay before considering a session as over (seconds)int30 (default)
PrivacyignoreLimitedAdTrackingWhether the SDK should ignore (true) or not (false) the end-user choice to limit ad tracking.booleantrue, false (default)
PrivacysendEventWhenOptoutDo you want to send events when optout?booleantrue (default), false
PrivacydefaultPrivacyModePrivacy mode by defaultConfiguration.PrivacyModeoptin (default)View
StorageofflineStorageModeOffline feature storage mode. Configuration.OfflineStorageMode.ALWAYS will always store data, you need to send data yourself Configuration.OfflineStorageMode.REQUIRED automatically manage offline storage depending on network conditions, Configuration.OfflineStorageMode.NEVER will never store dataConfiguration.OfflineStorageModeConfiguration.OfflineStorageMode.ALWAYS, Configuration.OfflineStorageMode.REQUIRED (default), Configuration.OfflineStorageMode.NEVER
StorageprivacyStorageLifetimeLifetime Storage Privacy valueint395 (days)View
StorageuserStorageLifetimeLifetime Storage User valueint395 (days)View
StoragevisitorStorageLifetimeLifetime Storage Visitor valueint395 (days)View
StoragevisitorStorageModeRelative or fixed cookie lifetime value for visitorConfiguration.VisitorStorageModeConfiguration.VisitorStorageMode.FIXED (default), Configuration.VisitorStorageMode.RELATIVE
Visitor PolicyvisitorIDTypeVisitor ID typeConfiguration.VisitorIDTypeConfiguration.VisitorIDType.UUID (default), Configuration.VisitorIDType.ADVERTISING_ID, Configuration.VisitorIDType.GOOGLE_ADVERTISING_ID, Configuration.VisitorIDType.HUAWEI_OPEN_ADVERTISING_ID, Configuration.VisitorIDType.CUSTOM

Data storage encryption

If you need your data storage to be encrypted, you should specify an encoder on SDK init:

object PlainDataEncoder : DataEncoder {
override fun encode(data: String): String = data
override fun decode(data: String): String = data

PianoAnalytics.init(applicationContext, configuration, PlainDataEncoder)


You can find the Android changelog directly on GitHub.

Migration from < 3.3.0

We rewritten our SDK from Java to Kotlin starting from version 3.3.0.

Here are the breaking changes you should be aware of when migrating from a version < 3.3.0:

  • is now
    • You should update your Maven implementation: implementation("").
    • You should update your imports: import
  • Event tagging has changed. Please check our documentation.
    • We do not provide sendEvent() method anymore, only sendEvents().
  • AV Insights tagging has changed. Please check our documentation.
  • setProperty method should be updated to use ContextProperties.
  • Privacy management has been reviewed, please check our documentation.
  • We don't offer Android ID as a visitor identification option anymore, to follow Android guidelines.
  • SDK initialisation has changed. Please check our documentation.
  • Configuration can't be changed after init anymore.
  • Some configuration names have changes:
    • visitorIdType -> visitorIDType
    • privacyDefaultMode -> defaultPrivacyMode
    • storageLifetimeVisitor -> visitorStorageLifetime
    • storageLifetimePrivacy -> privacyStorageLifetime
    • storageLifetimeUser -> userStorageLifetime
    • storageLifetimeVisitor -> visitorStorageLifetime
    • ignoreLimitedAdvertisingTracking -> ignoreLimitedAdTracking
    • crashDetection -> detectCrashes
  • Some configurations must be implemented in another way:
    • offlineEncryptionMode must be replaced by an encoder set on SDK init.
    • visitorId must be set using PianoAnalytics.getInstance().customVisitorId = "custom-visitor-id" (used only if visitorIDType is set to VisitorIDType.CUSTOM)
  • You can't set custom User-Agent anymore (now fixed to Piano Analytics SDK <SDK_VERSION>).