Getting started fivvy-ionic-plugin

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 Library functions for more information.

Recommendations

• IONIC VERSION: Actually tested on Ionic 7
• CAPACITOR VERSION: 3.9 or higher
• ANDROID API LEVEL: 21 a 33
• MIN JAVA VERSION: jdk11 (we recommend jdk17)

Installation

Please read this entire section.

npm

npm install fivvy-ionic-plugin 

yarn

yarn add fivvy-ionic-plugin 

Remember to update the new Android Plugin with capacitor

npx cap sync

the terminal will log the name of the plugin

Example

√ Updating Android plugins in 9.74ms
[info] Found 5 Capacitor plugins for android:
       @capacitor/[email protected]
       @capacitor/[email protected]
       @capacitor/[email protected]
       @capacitor/[email protected]
       fivvy-ionic-plugin @0.1.17  <--

Android

Permissions

AndroidManifest

Necessary to add this xmlns:tools inside the tag manifest in the AndroidManifest inside android/app/src/main folder.

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

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

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

<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>

Integration in App

On android you must request permissions beforehand

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: string): Promise<number[]> {
  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 as ArrayBuffer;
      const byteArray = new Uint8Array(arrayBuffer);
      resolve(Array.from(byteArray));
    };
    reader.onerror = reject;
    reader.readAsArrayBuffer(blob);
  });
}

Step 2: Use the Plugin with Custom Parameters

Include the method in your Ionic component and use it to open the usage settings WITHOUT a custom dialog.

import { Plugins } from '@capacitor/core';
const { ContextualProfiler } = Plugins;

async function showUsageSettings() {
  try {
    await ContextualProfiler.createOpenUsageSettingsDirectlyUseCase();
  } catch (e) {
    console.error('Error opening usage settings', e);
  }
}

Include the method in your Ionic component and use it to open the usage settings WITH a custom dialog.

import { Plugins } from '@capacitor/core';
const { ContextualProfiler } = Plugins;

async function showUsageSettingsDialog() {
  try {
    // Make sure the path to your image is correct. Note If the image does not open, check that the image is in the build/dist folder to be accessible
    const imagePath = await convertImageToByteArray('assets/example.png');
   // ln could be ES, EN, PT at the moment
    await ContextualProfiler.createOpenUsageSettingsUseCase({
      ln: 'ES',
      appName: 'AppDemo',
      appDescription: 'Some Description',
      modalText: 'Some guide text',
      imagePath: imagePath,
      dialogTitle: 'Custom Usage Information Title',
      dialogMessage1: 'Custom message 1 about usage permissions.',
      dialogMessage2: 'Custom message 2 about privacy and data collection.'
    });
  } catch (e) {
    console.error('Error opening usage settings', e);
  }
}

Send data to Fivvy's analytics service

Example of use

import { ContextualProfiler } from 'fivvy-ionic-plugin ';

const { initContextualDataCollection } = ContextualProfiler;

const sendData = async () => {
  const res = await initContextualDataCollection({
    customerId: "ionic-user-2", // Represents an identifier of the current user
    apiKey: ENV.API_KEY, // ApiKey of Fivvy's API - ENVIRONMENT VARIABLE
    apiSecret: ENV.API_SECRET, // ApiSecret of Fivvy's API - ENVIRONMENT VARIABLE
    appUsageDays: 30, // Integer that represents the last days to recollect the app usage information of the user
    authApiUrl: ENV.AUTH_API_URL, // URL of the Fivvy's Auth API - ENVIRONMENT VARIABLE
    sendDataApiUrl: ENV.SEND_DATA_API_URL, // URL of the Fivvy's Analytics Data API - ENVIRONMENT VARIABLE
  });
  console.log("response: ", res); // RESPONSE IS CONTEXTUAL DATA OBJECT
};

Module Functions

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. | | 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 | {ln: String, appName: String, appDescription: String, modalText: String, imagePath: number[], dialogTitle: String, dialogMessage1: String, dialogMessage2: String} | Boolean | Open settings view to grant app usage permission. |

Interfaces

Here you can find the interfaces 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;
    publicIP: string
  }

  \`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;
  }

Example

You can find an example app/showcase here

Getting the installed apps

Recovery of applications installed on the user's device.

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

Terms of use

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