WiseTrack SDK for Android

The WiseTrack SDK is a powerful analytics tool for tracking user interactions, events, and application metrics in Android applications. It provides a simple interface to initialize tracking, log events, manage SDK settings, and retrieve analytics data such as Advertising ID (ADID) and referrer information.

Table of Contents

• Features
• Permissions
• Requirements
• Installation
• Dependencies for Features
• Setup
• Usage
  • Initialization
  • Starting and Stopping Tracking
  • Logging Events
  • Managing SDK Settings
  • Retrieving Analytics Data
  • Uninstall Detection and Setting Push Notification Tokens
  • Setting FCM Token
  • Cleaning Up
• Example
• Troubleshooting
• License

Features

• Track user interactions and custom events (e.g., user actions, revenue events).
• Support for multiple app stores (e.g., Google Play, CafeBazaar, Myket).
• Configurable environments (Sandbox, Production) and SDK settings.
• Retrieve Advertising ID (ADID) and referrer information.
• Integration with Firebase Installation for firebase install id.
• Support for Open Advertising ID (OAID) and Huawei Ads Identifier.
• Referrer tracking for Google Play and CafeBazaar.
• Robust logging with customizable log levels.
• Automatic tracking with configurable delays.

Requirements

• Android API Level: 21 (Lollipop) or higher
• Kotlin: 1.9.0 or higher
• Gradle: Android Gradle Plugin >= 7.1.0 and Gradle 7.3 for full compatibility with Java 17.
• Dependencies: See the Dependencies for Features section for required and optional dependencies.

Permissions

• To give the WiseTrack SDK access to device information, you need to declare which permissions your app requires. To do this, add permissions to your AndroidManifest.xml file:

  • Add the following permissions to get access to online features:

      <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

  • If your app doesn't target the Google Play Store, add the following permission to access the device's network state:

      <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
      <uses-permission android:name="android.permission.READ_PHONE_STATE" />

Installation

1. Add the WiseTrack SDK to your project:

• Add the dependency to your app/build.gradle:

  implementation 'io.wisetrack.sdk:core:2.0.0' // Replace with the latest version

• Sync your project with Gradle.

2. Add feature-specific dependencies: Depending on the features you want to enable (e.g., OAID, referrer tracking), add the corresponding dependencies as described in the Dependencies for Features section.

Dependencies for Features

The WiseTrack SDK automatically utilizes certain features if their corresponding dependencies are included in your project. Below is a list of features and the required dependencies:

• WebView Bridge: Enables support for WebView if you use in your application. Check more info at Webbridge Docs

  implementation 'io.wisetrack.sdk:webbridge:2.0.0' // Replace with the latest version

• Open Advertising ID (OAID): Enables support for oaidEnabled in WTInitialConfig to use OAID as an alternative to ADID for Chinese phones that has not GooglePlay Service.

  implementation 'io.wisetrack.sdk:oaid:2.0.0' // Replace with the latest version

• Referrer Tracking: Enables referrerEnabled in WTInitialConfig and getReferrer() for tracking install sources.

  • check Google Play referrer latest version here
  • check Cafe Bazaar referrer latest version here

  implementation 'io.wisetrack.sdk:referrer:2.0.0' // Replace with the latest version
  implementation 'com.android.installreferrer:installreferrer:2.2' // For Google Play referrer
  implementation 'com.github.cafebazaar:referrersdk:1.0.2' // For CafeBazaar referrer

• Google Advertising ID (ADID): Enables getADID() for retrieving the Google Advertising ID.

  implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'

• Huawei Ads Identifier: Enables ADID retrieval on Huawei devices. add repository:

  maven { url 'https://developer.huawei.com/repo/' }

  and this dependency:

  implementation 'com.huawei.hms:ads-identifier:3.4.62.300'

• Firebase Installation ID (FID): Enables firebase installation id for finding unique id for user device.

  1. Required Dependency

     implementation 'com.google.firebase:firebase-installations:17.2.0'

  2. To use Firebase services like Installations, you must register your app with Firebase and complete the setup:
  • Register your Android app on the Firebase Console:
  • Add your package name (e.g., com.example.app)
  • Download the google-services.json file
  • Add the google-services.json file in the android/app/ directory of your project
  • Update the root-level build.gradle (android/build.gradle):

    buildscript {
      dependencies {
        classpath 'com.google.gms:google-services:4.4.1' // Or latest version
      }
    }

  • Apply the Google Services plugin in your app-level build.gradle (android/app/build.gradle):

    apply plugin: 'com.google.gms.google-services'

• AppSet ID: Provides additional device identification for analytics.

  implementation 'com.google.android.gms:play-services-appset:16.1.0'

Note: Ensure you add only the dependencies for the features you need. For example, if you don't use Huawei devices, you can skip huawei-hms-ads-identifier. Check the Setup section for configuring these features in WTInitialConfig.

Setup

Before using the WiseTrack SDK, you need to initialize it with a configuration object ( WTInitialConfig). This typically happens in your Application class or main Activity.

Creating WTInitialConfig

The WTInitialConfig object defines the SDK's behavior, including the app token, store name, environment, and tracking settings.

import io.wisetrack.sdk.core.core.WTInitialConfig
import io.wisetrack.sdk.core.core.WTStoreName
import io.wisetrack.sdk.core.core.WTUserEnvironment
import io.wisetrack.sdk.core.models.WTLogLevel

val config = WTInitialConfig(
    appToken = "YOUR_APP_TOKEN", // Provided by WiseTrack
    storeName = WTStoreName.PlayStore, // Or CafeBazaar, Myket, etc.
    environment = WTUserEnvironment.PRODUCTION, // Or SANDBOX for testing
    trackingWaitingTime = 1, // Delay in seconds before tracking starts
    startTrackerAutomatically = true, // Automatically start tracking
    oaidEnabled = true, // Enable Open Advertising ID (requires wisetrack-oaid)
    logLevel = WTLogLevel.DEBUG, // Set logging level (DEBUG, INFO, etc.)
    referrerEnabled = true // Enable referrer tracking (requires wisetrack-referrer)
)

Initializing the SDK

Initialize the SDK in your Application class or onCreate of your main Activity:

import io.wisetrack.sdk.core.WiseTrack

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        WiseTrack.initialize(context, initConfig)
    }
}

Register your Application class in AndroidManifest.xml:

<application android:name=".MyApplication"...></application>

Usage

The WiseTrack class provides several public methods for interacting with the SDK. Below is a detailed guide to each method.

Initialization

• initialize(context: Context, initialConfig: WTInitialConfig): Initializes the SDK with the provided configuration and your application context.

  WiseTrack.initialize(context, initConfig)

  • Call this method once during application startup.
  • Ensure initialConfig includes a valid appToken.

Starting and Stopping Tracking

• startTracking(): Starts tracking user activity and events.

  WiseTrack.startTracking()

  • Call this if startTrackerAutomatically is false in WTInitialConfig.
  • The SDK retries up to 3 times if not initialized, with a 3-second delay between attempts.

• stopTracking(): Stops all tracking operations.

  WiseTrack.stopTracking()

  • Use this to pause tracking, e.g., when the user opts out of analytics.

Logging Events

• logEvent(event: WTEvent): Logs a custom event, such as user actions or revenue transactions.

  import io.wisetrack.sdk.core.core.WTEvent
  import io.wisetrack.sdk.core.core.EventParam
  import io.wisetrack.sdk.core.core.RevenueCurrency
  
  // Default event
  val defaultEvent = WTEvent.defaultEvent(
      name = "button_clicked",
      params = mapOf("button_id" to EventParam("start_button"))
  )
  WiseTrack.logEvent(defaultEvent)
  
  // Revenue event
  val revenueEvent = WTEvent.revenueEvent(
      name = "purchase",
      currency = RevenueCurrency.USD,
      amount = 9.99,
      params = mapOf("item" to EventParam("premium_subscription"))
  )
  WiseTrack.logEvent(revenueEvent)

  Note: Event parameter keys and values have a maximum limit of 50 characters.

  • Use WTEvent.defaultEvent for user actions or system events.
  • Use WTEvent.revenueEvent for monetary transactions.

Managing SDK Settings

• setEnabled(enabled: Boolean): Enables or disables the SDK.

  WiseTrack.setEnabled(true) // Enable SDK
  WiseTrack.setEnabled(false) // Disable SDK

  • Ignored if the SDK is not enabled in the configuration or requires a forced update.

• setLogLevel(level: WTLogLevel): Sets the logging level for SDK logs.

  WiseTrack.setLogLevel(WTLogLevel.INFO)

  • Options: DEBUG, INFO, WARNING, ERROR, NONE.
  • Use DEBUG during development, INFO or higher for production.

• clearDataAndStop(): Clears all stored data and stops tracking (for testing or resetting).

  WiseTrack.clearDataAndStop()

  • Use with caution, as this deletes all analytics data.

Retrieving Analytics Data

• getADID(): String?: Retrieves the Advertising ID (ADID), if available.

  val adid = WiseTrack.getADID()
  println("Advertising ID: $adid")

  • Returns null if the ADID is not available (requires play-services-ads-identifier or huawei-hms-ads-identifier).

• getReferrer(): String?: Retrieves the referrer information, if available.

  val referrer = WiseTrack.getReferrer()
  println("Referrer: $referrer")

  • Returns null if referrer tracking is disabled or unavailable (requires wisetrack-referrer, android-installreferrer, or cafebazaar-referrersdk).

Uninstall Detection and Setting Push Notification Tokens

• WiseTrack.ensureInitialized(context: ApplicationContext): Ensures that the WiseTrack SDK is initialized before use.
• WiseTrack.isWiseTrackNotificationPayload(payload: Map<String, String>): Checks if the payload is a WiseTrack notification.
• WiseTrack.setFCMToken(token: String): Sets the Firebase Cloud Messaging (FCM) token for push notifications.

Configuration

1. Set up Firebase in your project and add Firebase Messaging dependency
   Follow the official Firebase documentation to configure FCM in your Android app:
   👉 Firebase Cloud Messaging Setup Guide

2. Create a Firebase Messaging Service Implement a service class that extends FirebaseMessagingService to handle FCM tokens and incoming messages.

   class MyFirebaseMessagingService : FirebaseMessagingService() {
   
       override fun onMessageReceived(remoteMessage: RemoteMessage) {
           super.onMessageReceived(remoteMessage)
   
           WiseTrack.ensureInitialized(applicationContext)
           if (WiseTrack.isWiseTrackNotificationPayload(remoteMessage.data)) {
               // This is a WiseTrack silent notification and will be handled by the SDK.
               return
           }
           // Handle your app's custom notifications here if needed
       }
   
       override fun onNewToken(token: String) {
           super.onNewToken(token)
           // Call two next method when new fcm token received
           WiseTrack.ensureInitialized(applicationContext)
           WiseTrack.setFCMToken(token)
       }
   }

   or receive token manually after WiseTrack initialization:

   FirebaseMessaging.getInstance().token.addOnCompleteListener(
       OnCompleteListener { task ->
           if (task.isSuccessful) {
            val token = task.result
            WiseTrack.setFCMToken(token)
        }
   })

3. Register the Service in your AndroidManifest.xml

   <service
       android:name=".MyFirebaseMessagingService"
       android:exported="false">
       <intent-filter>
           <action android:name="com.google.firebase.MESSAGING_EVENT" />
       </intent-filter>
   </service>

Cleaning Up

• destroy(): Cleans up resources and stops tracking.

  WiseTrack.destroy()

  • Call this when the application is terminated or the SDK is no longer needed.

Example

Below is a complete example demonstrating how to use the WiseTrack SDK in an Android application.

import android.app.Application
import io.wisetrack.sdk.core.WiseTrack
import io.wisetrack.sdk.core.core.WTInitialConfig
import io.wisetrack.sdk.core.core.WTStoreName
import io.wisetrack.sdk.core.core.WTUserEnvironment
import io.wisetrack.sdk.core.core.WTEvent
import io.wisetrack.sdk.core.core.EventParam
import io.wisetrack.sdk.core.models.WTLogLevel

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize WiseTrack
        val config = WTInitialConfig(
            appToken = "YOUR_APP_TOKEN",
            storeName = WTStoreName.PlayStore,
            environment = WTUserEnvironment.PRODUCTION,
            trackingWaitingTime = 5,
            startTrackerAutomatically = true,
            oaidEnabled = true,
            logLevel = WTLogLevel.DEBUG,
            referrerEnabled = true
        )
        WiseTrack.initialize(this, config)

        // Log a custom event
        val event = WTEvent.defaultEvent(
            name = "app_started",
            params = mapOf("version" to EventParam("1.0.0"))
        )
        WiseTrack.logEvent(event)

        // Set FCM token
        WiseTrack.setFCMToken("YOUR_FCM_TOKEN")
    }
}

Troubleshooting

• SDK Not Initialized: Ensure initialize is called with a valid WTInitialConfig before using other methods.
• No ADID/Referrer: Verify that the required dependencies (play-services-ads-identifier, wisetrack-referrer, etc.) are included and that oaidEnabled or referrerEnabled is set in WTInitialConfig. Check device permissions.
• Logs Not Visible: Set logLevel to DEBUG or INFO to see detailed logs.
• Tracking Not Starting: Check if startTrackerAutomatically is false and call startTracking manually.
• Network Errors: Ensure the device has internet access and the correct WTSDKEnvironment is set in WTInitialConfig.

For further assistance, contact the WiseTrack support team at support@wisetrack.io.

License

The WiseTrack Flutter Plugin is licensed under the WiseTrack SDK License Agreement. See the LICENSE file for details.