Getting started [email protected]

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.

See the full API for more methods.

Recommendations

• CORDOVA ^12.0.1
• ANDROID API LEVEL: 21 to 33
• MIN JAVA VERSION: jdk8
• GRADLE DISTRIBUTION: gradle-7.5

Installation

Please read this entire section.

cordova plugin add cordova-plugin-contextual-profiler

Android

Permissions

Proyect Level build.gradle

make sure you have the Maven repository URL on your project-level build.gradle file:

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

App build.gradle

and the implementation dependency on your app-level build.gradle file:

dependencies {
    (...)
    implementation 'com.fivvy:fivvy-lib:1.1.1@aar'

}

AndroidManifest

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

<manifest 
  <!-- Others manifest properties -->
  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" />
  <uses-permission  android:name="android.permission.PACKAGE_USAGE_STATS"  tools:ignore="ProtectedPermissions" />

  <!-- List of apps that you want to check on customer device -->
  <queries>
    <!-- List of package's [Max 100] -->
    <package android:name="com.whatsapp"/> <!-- WhatsApp Messenger -->
    <package android:name="com.facebook.katana"/> <!-- Facebook -->
    <package android:name="com.mercadopago.android"/> <!-- Mercado Pago -->
    
  </queries>

  <application>
    <!-- ... -->
  </application>
</manifest>

Integration in App

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.

Using the Plugin to Open Usage Settings with Custom Dialog

To open the usage settings with a custom dialog and an image from the assets folder, follow these steps:

Step 1: Create a Method to Convert Image to Byte Array

Create a method to read an image from the assets folder and convert it to a byte array.

  async function convertImageToByteArray(imagePath) {
    try {
      const response = await fetch(imagePath);
      const blob = await response.blob();
  
      return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.onloadend = () => {
          const arrayBuffer = reader.result;
          const byteArray = new Uint8Array(arrayBuffer);
          resolve(Array.from(byteArray));
        };
        reader.onerror = reject;
        reader.readAsArrayBuffer(blob);
      });
    } catch (error) {
      console.error("Error converting image to byte array: ", error);
    }
  }

Get user permission to check the app's usage

  async function testOpenUsageSettings() {
    const lang = "ES";    // lang could be ES, EN, PR at the moment
    const appName = "appname"; // string value with your app name
    const appDescription = "app description"; // optional description text. Recommended length: 3 or 4 words
    const imagePath = await convertImageToByteArray('/img/logo.png'); // Make sure the path to your image is correct.
    const modalText = "modal text"; // optional modal text. Recommended length: 3 or 4 words
    const title = "titulo"; // Title of the dialog displayed to the user before redirecting to the settings screen for permissions.
    const message1 = "mensaje 1";  // Custom Message of the dialog displayed to the user before redirecting to the settings screen for permissions.
    const message2 = "mensaje 2";// Other custom Message of the dialog displayed to the user before redirecting to the settings screen for permissions.

    if (imagePath && imagePath.length > 0) {
        cordova.plugins.ContextualProfilerPlugin.openUsageSettings(lang, appName, appDescription, imagePath, modalText, title, message1, message2, function(result) {
            console.log('Success: ' + result);
            document.getElementById('openUsageSettingsResult').innerText = 'Success: ' + result;
        }, function(error) {
            console.log('Error: ' + error);
            document.getElementById('openUsageSettingsResult').innerText = 'Error: ' + error;
        });
    } else {
        document.getElementById('openUsageSettingsResult').innerText = 'Image path array is empty or not valid.';
    }
}

Opening Usage Settings Directly

If you prefer to open the usage settings directly without a custom dialog, follow these steps:

Use the Plugin Directly

Include the method in your component and use it to open the usage settings directly.

function testOpenUsageSettingsDirectly() {
   cordova.plugins.ContextualProfilerPlugin.openUsageSettingsDirectly(function(result) {
       console.log('Success: ' + result);
       document.getElementById('openUsageSettingsDirectlyResult').innerText = 'Success: ' + result;
   }, function(error) {
       console.log('Error: ' + error);
       document.getElementById('openUsageSettingsDirectlyResult').innerText = 'Error: ' + error;
   });
}

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.

document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
    console.log('Running cordova-' + cordova.platformId + '@' + cordova.version);
    document.getElementById('deviceready').classList.add('ready');
}
const customerId = 'customer-id-01';
const days = 30;
const COMPANY_NAME = 'FIVVY-TEST';
const API_KEY = '333_asdNOTvK67Du';
const API_SECRET = 'asdzqpSSO5h7aiL';
const AUTH_API_URL = 'https://api.fivvyforbusiness.com/b2b-auth/auth/v1/users/login';
const SEND_DATA_API_URL = 'https://api.fivvyforbusiness.com/b2b-intake/intake/v2/context';

function testSendData() {
    cordova.plugins.ContextualProfilerPlugin.initContextualDataCollection(customerId, API_KEY, API_SECRET, AUTH_API_URL,SEND_DATA_API_URL,days,function(result) {
        console.log('Success: ' + result);
    }, function(error) {
        console.log('Error: ' + error);
    });
}
document.getElementById('sendData').addEventListener('click', testSendData);

API

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

| Methods | Params value | Return value | Description | |--- |--- |--- |--- | | initContextualDataCollection | (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. | | 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. | Returns null if the user doesnt brings access to the App Usage or an IAppUsage Array for the all used aplications. | | getAppsInstalled | Empty | Promise<IInstalledApps[]> | Returns an IInstalledApps Array for all the queries in AndroidManifest that user had install in his phone. | | openUsageAccessSettings | Empty | Boolean | Open settings view to grant app usage permission. |

Interfaces

Here you can find the interaces that sdk uses

`initContextualCollectionData param object interface`
 InitConfig {
    customerId: string,
    apiUsername: string,
    apiPassword: string,
    appUsageDays: number,
    authApiUrl: string,
    sendDataApiUrl: string
 }
`getDeviceInformation return interface` 
IHardwareAttributes {
    api_level: string;
    device_id: 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;
    incremental_version: string;
    release_version: string;
    base_os: string;
    display: string;
    battery_status: number;
  }

  `getAppUsage return object interface`
  IAppUsage {
    appName: string;
    usage: number;
    packageName: string;
  }
  `getAppsInstalled return object interface`
  IInstalledApps {
    appName?: string;
    packageName: string;
    category?: string;
    icon?: string;
    installTime?: string;
    lastUpdateTime?: string;
    versionCode?: string;
    versionName?: string;
  }
  

Terms of use

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