Fire OS

Documentation Index

Fetch the complete documentation index at: https://docs.joinmassive.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Technical Requirements

​

Permissions Needed

​

Integration Guide

​

Sample application

1. Download the latest sample using the link above.
2. Unarchive and open the project in Android Studio.
3. Copy the API token from the applications page.
4. Set the token value to the variable API_TOKEN at the end of MainActivity.kt.
5. Build and run a target sampleapp.

​

Dependency configuration

1. Add Massive maven repository to the dependency repositories used by the project. You can find the URL in the downloads page. It can be defined in different places depending on your project. Common places are: global settings.gradle.kts
   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
           maven {
             url = uri("MASSIVE_MAVEN_REPO_URL")
           }
       }
   }
   
   
   project build.gradle
   allprojects {
       repositories {
           google()
           mavenCentral()
           maven {
               url uri("MASSIVE_MAVEN_REPO_URL")
           }
       }
   }
   
   
2. In the build configuration file for your app module (build.gradle.kts / build.gradle), add the Massive SDK as a dependency:
   dependencies {
       implementation("com.joinmassive:sdk:1.+")
   }
   
   If you use a toml file for dependency configuration, add the following to the toml:
   [versions]
   massiveSdk = "massive_sdk_version_here"
   
   [libraries]
   massive-sdk = { group = "com.joinmassive", name = "sdk", version.ref = "massiveSdk"}
   
   Then, define SDK dependency in the gradle file as:
   dependencies {
       implementation(libs.massive.sdk)
   }
   

​

Integration to the app

​

1. Get the API token

​

2. Initialize MassiveClient

class MainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Initialize MassiveClient
        MassiveClient.init(API_TOKEN, this)
    }
}

​

3. Create client options

val massiveOptions = MassiveOptions(
    serviceType = MassiveServiceType.Foreground,
    notificationOptions = MassiveNotificationOptions(
        notificationTitle = getString(R.string.notification_title),
        notificationText = getString(R.string.notification_content),
        iconDrawable = com.joinmassive.sdk.R.drawable.massive_sdk_icon
    )
)

​

4. Request consent from the user

To remove ads and get free content, please let Massive use a small amount of your device's free resources and IP
address to download public web data from the internet.

This supports the development of Application and helps us to improve our services.

No personal information is collected except your IP address.

Your participation is optional, and you may opt out anytime by accessing Settings (see Massive's FAQ for details).

Pressing Accept indicates that you agree to Massive's license and privacy policy.

​

5. Start usage after consent

// Check if there is user consent to use Massive and show the dialog if we need to request it.
if (!consentHelper.isConsentGiven()) {
    consentHelper.showConsentDialog(
        onAccept = {
            // Start Massive if the user has given consent.
            MassiveClient.start(massiveOptions) { result ->
                result.onSuccess {
                    // Handle successful start.
                }.onFailure { exception ->
                    // Handle start failure.
                }
            }
        },
        onDecline = {}
    )
} else {
    // If the user has already given consent, start Massive directly.
    MassiveClient.start(massiveOptions) { result ->
        result.onSuccess {
            // Handle successful start.
        }.onFailure { exception ->
            // Handle start failure.
        }
    }
}

​

Changes in the new Massive SDK 1.0

1. Dependency configuration: The dependency configuration process has been streamlined. Instead of manually setting up a local Maven repository, you can now directly add the Massive Maven repository to your project’s Gradle configuration. This simplification reduces setup time and potential errors, ensuring a more efficient integration of the SDK.
2. Changed package name: The name of the Massive SDK package has changed from com.massive to com.joinmassive.
3. Changed client interface: The MassiveClient has shifted from using a singleton instance to utilizing static methods. This change simplifies interaction with the SDK, making it more straightforward to initialize and manage the client throughout the application lifecycle.
4. Options handling: The process of providing options has been moved from the init stage to the start method. This allows for more dynamic configuration, enabling modification of the service options at the time of starting the client rather than during initialization. This separation ensures a quicker initialization process and more flexible configuration management.
5. Changed behavior of stop: The behavior of the stop method has been enhanced. In the new version, calling stop not only stops the usage but also shuts down the service entirely. This ensures that all operations are cleanly terminated and the service is properly shut down, providing a more robust mechanism for managing the SDK’s lifecycle.
6. Remote service: The Massive SDK service now runs as a separate process, enhancing the stability and performance of the main application.

​

Migration from version 0.x

​

Dependency Configuration

• Old Version: Requires manually setting up a local Maven repository.
  mkdir project/repo
  unzip massive-sdk.zip -d project/repo
  
  repositories {
      maven {
          url = uri("/project/repo")
      }
  }
  
  dependencies {
        implementation("com.massive:sdk:0.+")
  }
  
• New Version: Directly add the Massive Maven repository to the dependency repositories.
  repositories {
    maven {
      url = uri("MASSIVE_MAVEN_REPO_URL")
    }
  }
  
  dependencies {
        implementation("com.joinmassive:sdk:1.+")
  }
  

​

Initialization

• Old Version:
  MassiveClient.getInstance(context) { client ->
      client.initAsync(MASSIVE_DEMO_API_TOKEN, massiveOptions, object : InitCallback {
          override fun onSuccess() {
              // Handle successful initialization.
          }
          override fun onFailure(message: String) {
              // Handle initialization failure.
          }
      })
  }
  
• New Version:
  MassiveClient.init(API_TOKEN, context)
  

​

Start and stop methods

• Old Version:
  client.start()
  ...
  client.stop()
  
• New Version:
  MassiveClient.start(massiveOptions) {
      it.onSuccess { // Handle Started state. }
      it.onFailure { // Handle error. }
  }
  ...
  MassiveClient.stop() {
      it.onSuccess { // Handle Stopped state. }
      it.onFailure { // Handle error. }
  }
  

​

State handling

• Old Version:
  // Async state handler.
  client.listener = object : MassiveClientListener {
      override fun onStateChange(newState: State) {
          // Handle changed state.
      }
  }
  ...
  // Current state.
  client.state
  
• New Version:
  // Handle state after the action.
  MassiveClient.start(massiveOptions) {
      it.onSuccess { // Handle Started state or query the current state. }
      it.onFailure { // Handle error. }
  }
  
  // Current state.
  when (MassiveClinet.state()) {
      MassiveClient.State.Starting -> {
      }
      MassiveClient.State.Started -> {
      }
      MassiveClient.State.Stopped -> {
      }
  }
  

​

Technical details

1. Android permissions Massive SDK defines the following permissions in the manifest file:
   • android.permission.INTERNET
   • android.permission.ACCESS_NETWORK_STATE
   • android.permission.FOREGROUND_SERVICE
   • android.permission.FOREGROUND_SERVICE_DATA_SYNC
   • android.permission.WAKE_LOCK
   These permissions will be automatically added to your app during the build.
2. Client initialization Interaction with the SDK always begins with initialization using MassiveClient.init, which requires your API token. This initialization step is crucial and should be performed only once during the application’s lifecycle. Subsequent calls to init will have no effect. Attempting to re-initialize the SDK with a different API token will result in a MassiveReinitException, ensuring that the SDK maintains a single consistent state throughout the app’s runtime. Since the SDK consists of client and service components, initialization can trigger synchronization of their states. To handle this scenario and achieve accurate state tracking, you can pass an additional callback to the init method. This callback will be called in the main thread after synchronization is complete.
3. User consent before starting the usage Before starting the usage for the first time (using the start() method), it is mandatory to obtain user consent for the terms of resource exchange. This aligns with user privacy and control principles. Ensure that your application includes a clear and understandable consent mechanism.
   if (isUserConsentGiven) {
       MassiveClient.start(massiveOptions) {}
   }
   
4. Starting and stopping the client Initialization of the MassiveClient with the init() method does not automatically launch the service or start the usage. It prepares the SDK for use but does not begin its operation. To ensure that the Massive is running, the start() method must be called after initialization and on each application relaunch. The start() method is designed to be idempotent, meaning it is safe to call multiple times. If the service is already started, subsequent calls to start will have no effect, preventing redundant operations. The stop() method is used to stop and kill the service, effectively halting all operations and ensuring that the service is properly terminated. After calling stop(), you can restart the client by calling the start() method again, and it is possible to provide different options for the restart. This flexibility allows you to change the configuration or operational mode of the SDK as needed.
5. Client options and service types Massive SDK can operate either as a Background or a Foreground service. The choice depends on your app’s requirements and how you want to manage the SDK’s resource usage.
   • Foreground Service: Allow Massive to run more and less likely killed by the system but more visible with a customizable notification ensuring the user is aware of the service’s operation. Running as a Foreground Service increases earning potential.
   • Background Service: Less intrusive, running silently without user interaction.
6. Customizing Foreground Service Notification When running as a foreground service, Massive SDK allows customization of the notification displayed to the user. You can set the title, text, and icon of the notification:
   val options = MassiveOptions(
       serviceType = MassiveServiceType.Foreground,
   
       notificationOptions = MassiveNotificationOptions(
           notificationTitle = "Your Title",
           notificationText = "Your Text",
           iconDrawable = R.drawable.your_icon
       )
   )
   
   Massive library contains a pre-defined drawable icon resource com.joinmassive.sdk.R.drawable.massive_sdk_icon, but you can also provide your own.
7. Usage tracking The Massive SDK includes functionality for tracking and retrieving current traffic usage statistics. This allows you to monitor the SDK’s data usage, providing insights into its network activity. The usage method in the MassiveClient class fetches and returns the current traffic usage in bytes. Please check the sample application for an example of how to use the method to retrieve and display the traffic usage statistics.
8. SDK remote service The latest version of the Massive SDK uses a remote service that is launched as a separate process. This service handles the core operations of the SDK independently of the main application process, providing better performance and stability.
9. ProGuard rules Massive SDK AAR embeds required Android ProGuard rules which are applied automatically if you are using the R8 compiler. If you, however, don’t use R8 you have to apply the rules below:

# Keep the public SDK entities
-keep class com.joinmassive.sdk.** { *; }
-keep interface com.joinmassive.sdk.** { *; }
-keep enum com.joinmassive.sdk.** { *; }

-dontwarn org.jetbrains.annotations.**
-keep class kotlin.Metadata { *; }

# Keep OkHttp3 and Moshi classes
-keep class com.squareup.okhttp3.** { *; }
-keep interface com.squareup.okhttp3.** { *; }
-keep class com.squareup.moshi.** { *; }
-keep interface com.squareup.moshi.** { *; }

-keepattributes Exceptions,InnerClasses,Signature,Deprecated,*Annotation*,EnclosingMethod