Getting started profiler

Contextual Profiler SDK offers a comprehensive and efficient solution for collecting valuable information about your users. With this powerful tool, you will be able to gather relevant data that will allow you to conduct in-depth analysis and gain a clear understanding of your users' behavior, preferences, and needs.

⚠️ Important Notice: This library does not support iOS devices.

Please be aware that this library is currently only available for Android. It will not work on iOS devices. Ensure that your project is intended for Android platforms before integrating this library.

Recommendations

FLUTTER: >= 3.3.0
ANDROID API LEVEL: 21 to 33 (we recommend 24 to 34)
MIN JAVA VERSION: jdk11
GRADLE DISTRIBUTION: gradle-7.5.1

Installation

Please read this entire section.

Android

Proguard

If you have any obsfucastion tool in your project, you'll need to exclude this package to work as intended in release builds.

Create a new file called proguard-rules.pro in /android/app with this content:

-keep class com.fivvy.profiler.** { *; }
-keep class * extends com.fivvy.profiler.** { *; }

-keepclassmembers class com.fivvy.profiler.** {
    *;
}

-keepattributes *Annotation*

Add the following settings in build.gradle within /android/app

    buildTypes {
        release {
            ...
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }

Gradle config

you MUST add this line to build.gradle (proyect)

allprojects {
    repositories {
        google()
        mavenCentral()
          maven {
            url "https://gitlab.com/api/v4/projects/58175283/packages/maven"
        }
    }
}

and in build.gradle (app)

    implementation 'com.fivvy:fivvy-lib:3.2.6@aar'

make sure you also have:

    implementation 'androidx.security:security-crypto-ktx:1.1.0-alpha04'
    implementation 'com.scottyab:rootbeer-lib:0.1.1'

Permissions

AndroidManifest

Necesary to add this xmlns:tools insde the tag manifest on AndroidManifest.xml insde android/app/src/main folder.

<manifest 
  xmlns:tools="http://schemas.android.com/tools"
>

Need to add these permissions in the AndroidManifes.xml file inside android/app/src/main before aplication tag.

<manifest>
  <!-- others aplications tags -->
  <uses-permission  android:name="android.permission.INTERNET" />
</manifest>

Integration in App

On android you must request permissions beforehand

Init of plugin

First of all, you will need to instantiated previously the ContextualProfiler plugin on the Widget where you will use the methods.

import 'package:profiler/plugin/contextual_profiler.dart';

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  // ADD THIS LINE
  final _profilerPlugin = ContextualProfiler();

  // Your Code
}

Send data to Fivvy's analytics service

This function will allow your app to send the information of each user to the Fivvy Analytic's API. You must add on some view or loading component that can send the data at least 1 time a day.

  Future<void> initContextualDataCollection() async {
    String response;

    ContextualCredential initConfig = ContextualCredential(
        customerId: customerId,
        apiPassword: apiSecret,
        apiUsername: apiKey,
        authApiUrl: authApiUrl,
        sendDataApiUrl: sendDataApiUrl
        )

    try {
      await _profilerPlugin.initContextualDataCollection(initConfig);
      response = 'Send data successfully';
    } on PlatformException {
      response = 'Something went wrong.';
    }

    if (!mounted) return;

    setState(() {
      this._response = response;
    });
  }

API

All the information about the package and how to use the functions.

Methods	Params value	Return value	Description
`initContextualDataCollection`	`InitConfig` {customerId: `String`, apiKey: `String`, apiSecret: `String`, appUsageDays: `int`, authApiUrl: `String`, sendDataApiUrl: `String`}	`Future<ContextualData>`	Initiates data collection, sending it to Fivvy's Analytics Data API.
`getDeviceInformation`	Empty	`Future<IHardwareAttributes>`	Returns the device hardware information of the customer.
`getAppsInstalled`	Empty	`Future<List<IInstalledApps>>`	Returns an IInstalledApps List for all the queries in `AndroidManifest.xml` that the user has installed on their phone.

Interfaces

Here you can find the interfaces that the SDK uses:

/// `initContextualCollectionData` parameter object interface
class InitConfig {
  String customerId;
  String apiKey;
  String apiSecret;
  int appUsageDays;
  String authApiUrl;
  String sendDataApiUrl;

  InitConfig({
    required this.customerId,
    required this.apiKey,
    required this.apiSecret,
    required this.appUsageDays,
    required this.authApiUrl,
    required this.sendDataApiUrl
  });
}

/// `getDeviceInformation` return interface
class IHardwareAttributes {
  String apiLevel;
  String deviceId;
  String device;
  String hardware;
  String brand;
  String manufacturer;
  String model;
  String product;
  String tags;
  String type;
  String base;
  String id;
  String host;
  String fingerprint;
  String incrementalVersion;
  String releaseVersion;
  String baseOs;
  String display;
  int batteryStatus;

  IHardwareAttributes({
    required this.apiLevel,
    required this.deviceId,
    required this.device,
    required this.hardware,
    required this.brand,
    required this.manufacturer,
    required this.model,
    required this.product,
    required this.tags,
    required this.type,
    required this.base,
    required this.id,
    required this.host,
    required this.fingerprint,
    required this.incrementalVersion,
    required this.releaseVersion,
    required this.baseOs,
    required this.display,
    required this.batteryStatus,
  });
}

/// `getAppsInstalled` return object interface
class IInstalledApps {
  String? appName;
  String packageName;
  String? category;
  String? installTime;
  String? lastUpdateTime;
  String? versionCode;
  String? versionName;

  IInstalledApps({
    this.appName,
    required this.packageName,
    this.category,
    this.installTime,
    this.lastUpdateTime,
    this.versionCode,
    this.versionName,
  });
}

Debug mode

Debug Mode Configuration

To enable and properly use the debug mode, follow these steps:

Requirements for Debug Mode

The project must have the BuildConfig class generated, which is standard in Flutter projects configured for Android. If your project does not generate BuildConfig, proceed to step 2.
If BuildConfig is not automatically generated or does not include the required property:
- Open the build.gradle file located at /android/app.
- Add the following configurations:
```
android {
    ...
    buildFeatures {
       buildConfig true
   }
}
```

⚠️ Important: The applicationId and namespace in your project must be identical. Debug mode will not work properly if these values are different.

General Information

⚠️ Important Notice: iOS Compatibility

This library is not compatible with iOS devices. It is specifically designed for Android platforms, and no support for iOS is provided. Please refrain from using this library in iOS-based projects, as it will not function as intended.

Appendix: advanced features (optional)

Android Permission Request

On android you must request permissions beforehand. This part is divided into two sections to show how to open the usage settings on Android using a custom modal dialog or directly without a modal.

AndroidManifest

Need to add these permissions in the AndroidManifest inside android/app/src/main folder.

<manifest>
  <uses-permission  android:name="android.permission.PACKAGE_USAGE_STATS"  tools:ignore="ProtectedPermissions" />
</manifest>

Get user permission to check the app's usage

This is an exclusive custom dialog that you can invoke in your app to get bring a easy way to request access usage permission from the user.

First you need to add a function to transform an image to a byte array.

Future<Uint8List> loadImageBytes(String assetPath) async {
    final ByteData data = await rootBundle.load(assetPath);
    return data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes);
}

then implement this method: 
Future<void> openAccessUsageSettings() async {
    String platformVersion;

    final Uint8List imageBytes = await loadImageBytes("assets/images/logo.png");


    final usageSetting = UsageSetting(
      language: "ES", // If selected, the default texts will be set on the modal for EN, ES, or PR.
      // If using the ln value, it is recommended not to use the parameters below as the ln sets default texts in the right language.
      appName: 'Fivvy', // string value with your app name
      imagePath: imageBytes, // this image should be in android/app/src/main/res/drawable/logo.png
      imageView: 1,// integer value, 0: no image; 1: default image, 2: app logo
      buttonRadius: 25.0,// float value, set button border radius
      modalRadius: 25.0,// float value, set modal border radius
      color: '#50C7FA',// hex color value, set color of dialog title, accept background color and cancel button text color
      appDescription: 'Activate the permission', // optional description text. Recommended length: 3 or 4 words
      modalText: 'Lorem ipsum text', // optional modal text. Recommended length: 3 or 4 words
      dialogTitle: "Dialog Title", // Title of the dialog displayed to the user before redirecting to the settings screen for permissions.
      dialogMessage1: "Dialog message 1", // Custom Message of the dialog displayed to the user before redirecting to the settings screen for permissions.
      dialogMessage2: "Dialog message 2", // Other custom Message of the dialog displayed to the user before redirecting to the settings screen for permissions.
      blacklist: null // (Optional) List of device manufacturers for which the usage settings should be avoided. On some devices, especially from certain manufacturers as Xiaomi, a system warning might be displayed when attempting to access the usage settings. To prevent this action on those devices, you can:

      //- Pass `null`: This will apply a default list of manufacturers known to have this issue.
      // - Provide a custom list of manufacturers as an array (`["manufacturer1", "manufacturer2"]`): This will prevent the settings from being accessed only on devices from those specific brands.
      //- Pass an empty array `[]`: This will allow the settings to be accessed on all devices without any restrictions.

    );
    try {
      await _profilerPlugin.openUsageAccessSettings(usageSetting);
      platformVersion = 'opened successfully';
    } on PlatformException {
      platformVersion = 'Failed to open Access Usage Settings.';
    }

    if (!mounted) return;

    setState(() {
      _response = platformVersion;
    });
}

also add to .yaml file the asset:

flutter:
  assets:
    - assets/images/logo.png

Another option

However, there is a separate function in case you want to create a custom dialog that best suits your application. Consider having the ContextualProfiler here as _profilerPlugin plugin instantiated previously.

  Future<void> openAccessUsageSettingsDirectly() async {
    String platformVersion;
    try {
      await _profilerPlugin.openUsageAccessSettingsDirectly(blacklist); // - blacklist (Optional) List of device manufacturers for which the usage settings should be avoided. On some devices, especially from certain manufacturers as Xiaomi, a system warning might be displayed when attempting to access the usage settings. To prevent this action on those devices, you can:

      //- Pass `null`: This will apply a default list of manufacturers known to have this issue.
      // - Provide a custom list of manufacturers as an array (`["manufacturer1", "manufacturer2"]`): This will prevent the settings from being accessed only on devices from those specific brands.
      //- Pass an empty array `[]`: This will allow the settings to be accessed on all devices without any restrictions.
      platformVersion = 'opened successfully';
    } on PlatformException {
      platformVersion = 'Failed to open Access Usage Settings.';
    }

    if (!mounted) return;

    setState(() {
      _response = platformVersion;
    });
  }

API

All the information about the package and how to use the functions.

Methods	Params value	Return value	Description
`getAppUsage`	`int` days. Represents the last days to get the usage of each app.	`Future<List<IAppUsage>>`	Returns an IAppUsage List for all the queries in `AndroidManifest.xml` that the user has installed on their phone, or null if the user doesn't grant usage access.
`openUsageAccessSettings`	`IUsageSetting`	`Future<bool>`	Opens settings view to grant app usage permission.

Interfaces

Here you can find the interfaces that the SDK uses:

/// `getAppUsage` return object interface
class IAppUsage {
  String appName;
  int usage;
  String packageName;

  IAppUsage({
    required this.appName,
    required this.usage,
    required this.packageName,
  });
}
/// `openUsageSettings` parameter object interface
class IUsageSetting {
  String? language;
  Uint8List? imagePath;
  int? imageView;
  double? buttonRadius;
  double? modalRadius;
  String? color;
  String? appName;
  String? appDescription;
  String? modalText;
  String? dialogTitle;
  String? dialogMessage1;
  String? dialogMessage2;
  List<String>? blacklist;

  IUsageSetting({
    this.language,
    this.imagePath,
    this.imageView,
    this.buttonRadius,
    this.modalRadius,
    this.color,
    this.appName,
    this.appDescription,
    this.modalText,
    this.dialogTitle,
    this.dialogMessage1,
    this.dialogMessage2,
    this.blacklist,
  });
}

Changelog

`3.2.6` - 16-05-2025

Changed

add params in openUsageAccessSettings

Terms of use

All content here is the property of Fivvy, it should not be used without their permission.

Getting started profiler

Recommendations

Installation

Android

Proguard

Gradle config

Permissions

AndroidManifest

Integration in App

Init of plugin

Send data to Fivvy's analytics service

API

All the information about the package and how to use the functions.

Interfaces

Debug mode

Debug Mode Configuration

Requirements for Debug Mode

General Information

Appendix: advanced features (optional)

Android Permission Request

AndroidManifest

Get user permission to check the app's usage

Another option

API

All the information about the package and how to use the functions.

Interfaces

Changelog

`3.2.6` - 16-05-2025

Changed

Terms of use

Libraries

profiler package

Getting started profiler

Recommendations

Installation

Android

Proguard

Gradle config

Permissions

AndroidManifest

Integration in App

Init of plugin

Send data to Fivvy's analytics service

API

All the information about the package and how to use the functions.

Interfaces

Debug mode

Debug Mode Configuration

Requirements for Debug Mode

General Information

Appendix: advanced features (optional)

Android Permission Request

AndroidManifest

Get user permission to check the app's usage

Another option

API

All the information about the package and how to use the functions.

Interfaces

Changelog

3.2.6 - 16-05-2025

Changed

Terms of use

Libraries

profiler package

`3.2.6` - 16-05-2025