Android (Java)

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.

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.

Maven

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

implementation 'io.piano:analytics:3.x.x' // replace 3.x.x with the version you target

Manually

1. Clone the Android SDK from our Github repository:

   • SSH: git@github.com:at-internet/piano-analytics-android.git
   • HTTPS: https://github.com/at-internet/piano-analytics-android.git

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 'https://developer.huawei.com/repo/'}

   • For Gradle plugin 7.0

     • Open your project-level build.gradle file
     • Add the Maven repository as below under buildscript > repositories
       • maven {url 'https://developer.huawei.com/repo/'}
     • Open your project-level settings.gradle file
     • Add the Maven repository as below under dependencyResolutionManagement > repositories
       • maven {url 'https://developer.huawei.com/repo/'}

   • 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 'https://developer.huawei.com/repo/'}

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 instantiate a tracker before using it.

You should pass the application context as a parameter.

PianoAnalytics pa = PianoAnalytics.getInstance(getApplicationContext());

Configuration

In order to setup your tracking, you need to set the configuration of the library:

func PianoAnalytics.setConfiguration(config);

Here is the minimal configuration required:

pa.setConfiguration(new Configuration.Builder()
  .withCollectDomain("<xxxxxxx>.pa-cd.com")
  .withSite(123456789)
  .build()
);

note

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:

Category	Name	ConfigurationBuilder function	Description	Type	Value
Global	collectDomain	withCollectDomain	Collection domain	string	https://<xxxxxxx>.pa-cd.com
Global	site	withSite	Site id	int	123456789
Global	path	withPath	Request path	string	event
Global	customUserAgent	withCustomUserAgent	Custom user agent	string	My User Agent
Global	crashDetection	enableCrashDetection	Enable (true) or not (false) automatic crash detection	boolean	true (default), false
Global	sessionBackgroundDuration	withSessionBackgroundDuration	Backgound delay before considering a session as over (seconds)	int	30
Privacy	ignoreLimitedAdvertisingTracking	enableIgnoreLimitedAdvertisingTracking	Whether the SDK should ignore (true) or not (false) the end-user choice to limit ad tracking.	boolean	true, false (default)
Privacy	sendEventWhenOptout	enableSendEventWhenOptout	Do you want to send events when optout?	boolean	true (default), false
Privacy	privacyDefaultMode	withPrivacyDefaultMode	Privacy mode by default	string	optin (default)
Storage	offlineEncryptionMode	withOfflineEncryptionMode	Offline feature encryption mode.	string	none, ifCompatible (default), force
Storage	offlineStorageMode	withOfflineStorageMode	Offline feature storage mode. always will always store data, you need to send data yourself required automatically manage offline storage depending on network conditions, never will never store data	string	always, required (default), never
Storage	offlineSendInterval	withOfflineSendInterval	Offline feature interval between sent requests	int	500
Storage	storageLifetimePrivacy	withStorageLifetimePrivacy	Lifetime Storage Privacy value	int	395 (days)
Storage	storageLifetimeUser	withStorageLifetimeUser	Lifetime Storage User value	int	395 (days)
Storage	storageLifetimeVisitor	withStorageLifetimeVisitor	Lifetime Storage Visitor value	int	395 (days)
Storage	visitorStorageMode	withVisitorStorageMode	Relative or fixed cookie lifetime value for visitor	string	fixed (default), relative
Visitor Policy	visitorIdType	withVisitorIdType	Visitor ID type	Configuration.VisitorIDType	Configuration.VisitorIDType.UUID (default), Configuration.VisitorIDType.ANDROID_ID, Configuration.VisitorIDType.ADVERTISING_ID, Configuration.VisitorIDType.GOOGLE_ADVERTISING_ID, Configuration.VisitorIDType.HUAWEI_OPEN_ADVERTISING_ID, Configuration.VisitorIDType.CUSTOM
Visitor Policy	visitorId	withVisitorID	Custom visitor ID	string	39001HUFEKK977894

Changelog

You can find the Android changelog directly on GitHub.