Getting started Fivvy contextual-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

• REACT NATIVE VERSION: >= 0.69.0 (we recommend 0.72.X or above)
• ANDROID API LEVEL: 21 a 34 (We recommend 34)
• MIN JAVA VERSION: jdk11 (we recommend jdk17)

Installation

Please read this entire section.

npm

npm install @fivvy/contextual-profiler

yarn

yarn add @fivvy/contextual-profiler

Android

Proguard

If you have any obfucastion 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)

1
2allprojects {
3    repositories {
4        google()
5        mavenCentral()
6          maven {
7            url "https://gitlab.com/api/v4/projects/58175283/packages/maven"
8        }
9    }
10}

and in build.gradle (app)

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

make sure you also have:

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

Permissions

AndroidManifest

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

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

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

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

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.

Every time this useEffect run, the data will be send to the Fyvvy's API.

1  useEffect(() => {
2    const contextualConfigObj = {
3      customerId: customerId, // Represents an identifier of the current user
4      apiKey: API_KEY, // ApiKey of Fivvy's API
5      apiSecret: API_SECRET, // ApiSecrey of Fivvy's API
6      appUsageDays: DAYS, // Integer that represents the last days to recollect the app usage information of the user. Recommended default value: 30
7      authApiUrl: AUTH_API_URL, // URL of the Fivvy's Auth API: https://api.fivvyforbusiness.com/b2b-auth/auth/v1/users/login
8      sendDataApiUrl: SEND_DATA_API_URL // URL of the Fivvy's Analytics Data API: https://api.fivvyforbusiness.com/b2b-intake/intake/v2/context
9    }
10    await initContextualDataCollection(contextualConfigObj);
11},[])

API

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

Methods	Params value	Return value	Description
initContextualDataCollection	InitConfig { customerId: String, apiKey: String, apiSecret: String, appUsageDays: Int, authApiUrl: String, sendDataApiUrl: String}	ContextualData	Initiates data collection, sending it to the Fivvy's Analytics Data API.
getDeviceInformation	Empty	Promise<IHardwareAttributes>	Returns the device hardware information of the customer.
getAppsInstalled	Empty	Promise<IInstalledApps[]>	Returns an IInstalledApps Array for all the queries in AndroidManifest that user had install in his phone.

Interfaces

Here you can find the interaces that sdk uses

1`initContextualCollectionData param object interface`
2 InitConfig {
3    customerId: string,
4    apiUsername: string,
5    apiPassword: string,
6    appUsageDays: number,
7    authApiUrl: string,
8    sendDataApiUrl: string
9 }
10`getDeviceInformation return interface`
11IHardwareAttributes {
12    api_level: string;
13    device_id: string;
14    device: string;
15    hardware: string;
16    brand: string;
17    manufacturer: string;
18    model: string;
19    product: string;
20    tags: string;
21    type: string;
22    base: string;
23    id: string;
24    host: string;
25    fingerprint: string;
26    incremental_version: string;
27    release_version: string;
28    base_os: string;
29    display: string;
30    battery_status: number;
31  }
32  `getAppsInstalled return object interface`
33  IInstalledApps {
34    appName?: string;
35    packageName: string;
36    category?: string;
37    installTime?: string;
38    lastUpdateTime?: string;
39    versionCode?: string;
40    versionName?: string;
41  }

Example

Getting the installed apps

Recovery of applications installed on the user's device.

1getAppsInstalled().then(data =>  console.log('Installed apps:', data));
2//  expected output
3  Installed Apps: [{"appName": "WhatsApp", "category": "Social", "installTime": "2023.02.15 20:07:35", "lastUpdateTime": "2023.08.16 14:52:12", "packageName": "com.whatsapp", "versionCode": "231676002", "versionName": "2.23.16.76"}]
4

Debug mode

Debug Mode Configuration

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

Requirements for Debug Mode

1. The project must have the BuildConfig class generated, which is standard in React Native projects configured for Android. If your project does not generate BuildConfig, proceed to step 2.

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:

     1android {
     2    ...
     3    buildFeatures {
     4       buildConfig true
     5   }
     6}

⚠️ 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 to check the app's usage. We recommend creating a logic with AsyncStorage to remember if the user doesn't want to give access to this permission.

Permissions

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

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

Get User Permission to Check App Usage

We have a pre-made modal with instructions that can be used for this purpose. Here is an example of how to implement it:

1import { getAppUsage, openUsageAccessSettings } from 'contextual-profiler';
2
3 openUsageAccessSettings({
4      ln: "EN", // If selected, the default texts will be set on the modal for EN, ES, or PR.
5      // If using the ln value, it is recommended not to use the parameters below as the ln sets default texts in the right language.
6      appDescription: 'Activate the permission', // optional description text. Recommended length: 3 or 4 words
7      appName: 'Fivvy', // string value with your app name
8      imagePath: 'logo',// this image should be in android/app/src/main/res/drawable/logo.png
9      imageView: 1,// integer value, 0: no image; 1: default image, 2: app logo
10      buttonRadius: 25.0,// float value, set button border radius
11      modalRadius: 25.0,// float value, set modal border radius
12      color: '#50C7FA',// hex color value, set color of dialog title, accept background color and cancel button text color
13      modalText: 'Lorem ipsum text', // optional modal text. Recommended length: 3 or 4 words
14      dialogTitle: "Dialog Title", // Title of the dialog displayed to the user before redirecting to the settings screen for permissions.
15      dialogMessage1: "Dialog message 1", // Custom Message of the dialog displayed to the user before redirecting to the settings screen for permissions.
16      dialogMessage2: "Dialog message 2", // Other custom Message of the dialog displayed to the user before redirecting to the settings screen for permissions.
17      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:
18
19      //- Pass `null`: This will apply a default list of manufacturers known to have this issue.
20      // - 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.
21      //- Pass an empty array `[]`: This will allow the settings to be accessed on all devices without any restrictions.
22
23    });

Direct Access to Settings

If you prefer not to display any modal and want to go directly to the settings screen, you can use

1openUsageAccessSettingsDirectly(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:
2
3      //- Pass `null`: This will apply a default list of manufacturers known to have this issue.
4      // - 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.
5      //- Pass an empty array `[]`: This will allow the settings to be accessed on all devices without any restrictions.

blacklist Parameter

The blacklist parameter is an array of strings containing the names of device manufacturers for which you want to disable a certain function. If the device is from a manufacturer listed in this array, the function will not perform any action.

blacklist Behavior:

• Array with specific manufacturers: If the array contains manufacturer names, the function will be disabled on devices from those brands. Example:

1blacklist: ["xiaomi", "huawei"]

• Empty Array: The feature will work on any manufacturer device. Example:

1  blacklist: []

• Null value: The feature will use a default blacklist, here are the default blacklisted manufacturers: ["xiaomi", "huawei", "oppo", "vivo", "realme", "lenovo", "meizu", "oneplus", "zte", "nubia"]

1 blacklist: null

Here's a full list of manufacturers names in Android: Android manufacturer names

Device manufacturer

This fucntion will return the current device manufacturer, this could be useful if you need to implement more complex logic in your app regarding the device manufacturer.

1getDeviceManufacturer().then((data) => {
2      console.log(data.manufacturer);
3    })

API

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

Methods	Params value	Return value	Description
getAppUsage	Int days. Represent the last days to get the usage of each app.	Promise<IAppUsage[]>	Returns an IAppUsage Array for all the queries in AndroidManifest that user had install in his phone or null if user doesn’t bring usage access.
openUsageAccessSettings	UsageSettings {ln: string, appDescription: string, appName: string, imagePath: string, imageView: number, buttonRadius: Float, modalRadius: Float, color: string, modalText: string, dialogTitle: string, dialogMessage1: string, dialogMessage2: string, blacklist: Array[]	null }	Boolean
openUsageAccessSettingsDirectly	blacklist: Array[]	null	Open settings view without pre-built modal to grant app usage permission.
getManufacturer	Empty	Promise<{ manufacturer: string }	Get the device manufacturer

Interfaces

Here you can find the interaces that sdk uses

1  `getAppUsage return object interface`
2  IAppUsage {
3    appName: string;
4    usage: number;
5    packageName: string;
6  }
7  `openUsageAccessSettings params object`
8  UsageSettings {
9    ln: string,
10    appDescription: string,
11    appName: string,
12    imagePath: string,
13    imageView: number,
14    buttonRadius: Float,
15    modalRadius: Float,
16    color: string,
17    modalText: string,
18    dialogTitle: string,
19    dialogMessage1: string,
20    dialogMessage2: string,
21    blacklist: [] | null,
22  }

Changelog

[3.2.6] - 15-05-2025

Changed

• update manifest default

Terms of use

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