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
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
- SSH:
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
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
- Open your project-level settings.gradle file and replace/add the repositoriesMode as below
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/'}
- Open your project-level
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/'}
- Open your project-level
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/'}
- Open your project-level
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()
);
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.