Android Integration

Steps for Android Integration:

Step 1: Update the build.gradle project level:

Step 1.1: Add mavenCentral() into build.gradle:

allprojects {
    repositories {
        mavenCentral()
    }
}

Step 1.2: Exclusive for Helios or Hestia variants, add jitpack.io into build.gradle:

allprojects {
    repositories {
      mavenCentral()
      maven{
            url "https://jitpack.io" //Exclusive for Helios or Hestia variants
        	 }
    }
}

Step 2: Add the following dependencies to the app module's build.gradle (app level):

implementation 'com.digitalreef.phoenix:<variant>:<version>'

Note 1: The variant used will be provided by Siprocal, if the variant name has not yet been provided, contact us.

Note 2: If you are using kotlin you will probably need to upgrade to version 1.9.0 or higher in your project.

Step 3: Go to the assets folder and into this one add siprocal-config.json (folder must be created at path --> android/app/src/main/assets)

Step 4: Create a class that extends from Application:

public class MyApp extends Application { 
  @Override
  public void onCreate(){
      super.onCreate();
      SiprocalSDK.init(this);
  }
}

class App: Application() {
  override fun onCreate() {
      super.onCreate()
      SiprocalSDK.init(this)
  }
}

Step 5: Update AndroidManifest.xml:

 <application
    ...
    android:name=".MyApp"
    android:allowBackup="false"
    android:fullBackupContent="@xml/backup_descriptor"
    android:usesCleartextTraffic="true"
    ... >
    ...
</application>

Step 6: Add ProGuard exception rules

Note: If you have minifyEnabled true, make sure to add the following ProGuard rules to ensure all SDK services work correctly.

Add the following lines to your proguard-rules.pro file:

-dontwarn org.slf4j.impl.StaticLoggerBinder

# Keep all classes that are marked as @Serializable
-keep @kotlinx.serialization.Serializable class * { *; }

# Keep all generated serializer companions
-keepclassmembers class * {
    kotlinx.serialization.KSerializer serializer(...);
}

You need add the following rules only If you are using the variants: helios or hestia

-dontwarn java.lang.management.ManagementFactory
-dontwarn java.lang.management.RuntimeMXBean
-dontwarn java.lang.reflect.AnnotatedType
-dontwarn org.slf4j.impl.StaticMDCBinder
-dontwarn org.slf4j.impl.StaticMarkerBinder

Step 7: Permissions Setup Instructions

Step 7.1: All variants

Siprocal SDK internally by default implements the following permissions:

<uses-permission  android:name="android.permission.POST_NOTIFICATIONS" /> <!--Required from Android 13 onwards to receive notifications-->
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/> <!--Required to capture Advertising Id-->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Specifically, the following permissions need to be requested from the user at runtime:

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

Step 7.2: Exclusive permissions for Helios or Hestia variants

Variants hestia and helios internally implements the following additional permissions:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION " />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<!-- Mandatory permissions for Android 12 and above.-->
<!-- Also, they should be asked in runtime. -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:minSdkVersion="31" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Specifically, the following permissions need to be requested from the user at runtime:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION " />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:minSdkVersion="31" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Alternatively, you can use the method _drpluginPlugin.requestPermissions() in your application’s flow, and the SDK will handle requesting the additional permissions described for Helios and Hestia. For more information you can review Methods for Dart

Step 7.3: Permissions Required for capture Location (Optional)

Note: Use this permission if it's required for you App.

Note: This permission must be requested from the user by the Host App at execution time.

To be able to collect the location the Siprocal SDK requires the following permissions:

  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

From Android 10 or higher, in order to be able to collect the location in background the following permission is required:

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

Step 7.4: Permissions Required for capture NFC Support and NFC Status (Optional)

Note: Use this permission only if it is required for your app, and ensure it is included in the manifest of the host app.

The SDK is capable of detecting whether a device supports NFC and the current status of NFC.

To collect NFC support and status information, the Siprocal SDK requires the following permissions:

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

Step 8: Customization

By default, the notification icon has a lightning bolt, but you should customize it by adding your preferred icon in the res/drawable directory.

The resource name must be siprocal_notif_default.png.

The image size should be 144x144 pixels with a transparent background.

For more information and customizations, visit the following link: Customization for Android

Step 9: Configure Siprocal Server for the Host App

Minimal configuration needs to be done on the Siprocal Server to connect to the host app via FCM. Provide the package name of the host app to SDK provider.

Available only for Android:

Sensitive Data (Optional)

If you want the SDK to collect sensitive data, add the following modules as needed:

Module	Sensitive Data	Dependency
AppServices	Installed Apps - Running Apps	implementation 'com.digitalreef.phoenix:app-services:<version>'
PhoneServices	IMEI1 - IMEI2 - Serial Number	implementation 'com.digitalreef.phoenix:phone-services:<version>'
TelephonyServices	Phone Number - IMSI - ICCID - Sim Data Slot	implementation 'com.digitalreef.phoenix:telephony-services:<version>'

Note: When including any of the modules, all sensitive data corresponding to that module will be captured.

implementation "com.digitalreef.phoenix:<variant>:<version>"  
implementation "com.digitalreef.phoenix:app-services:<version>"  
implementation "com.digitalreef.phoenix:phone-services:<version>"  
implementation "com.digitalreef.phoenix:telephony-services:<version>"

implementation("com.digitalreef.phoenix:<variant>:<version>")
implementation("com.digitalreef.phoenix:app-services:<version>")
implementation("com.digitalreef.phoenix:phone-services:<version>")
implementation("com.digitalreef.phoenix:telephony-services:<version>")

Add Permissions for Sensitive Data :

The data sensible requires permissions depending on the data that is collected, please add to the manifest as appropriate:

AppServices

You can use the following code in your manifest, inside tag:

<manifest>
<!--your code -->

    <queries>
        <intent>
            <action android:name="*" />
        </intent>
    </queries>

</manifest>

PhoneServices

Your can use for Android 9 and below:

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

For Android 10+ only is captured if the app in preloaded:

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

Note: This permission is only for preloaded variant

TelephonyServices

Your can use for Android 9 and below:

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

For Android 10+:

<uses-permission  android:name="android.permission.READ_PHONE_NUMBERS" />
<uses-permission  android:name="android.permission.READ_PHONE_STATE" />

For Preloaded App (Android 10+):

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

Note: This permission is only for preloaded variant

Initialization of Sensitive Data Modules

The included modules must be initialized at the same time as the SDK is initialized, as follows:

public class App extends Application { 
  @Override
  public void onCreate(){
      super.onCreate();
      SiprocalSDKSettings siprocalSDKSettings = new SiprocalSDKSettings.Builder()
                  .setAppServices(new AppServices())//only if use app-services module 
                  .setTelephonyServices(new TelephonyServices())//only if use telephony-services module 
                  .setPhoneServices(new PhoneServices())// only if use phone-services module 
                  .build();
      SiprocalSDK.init(this, siprocalSDKSettings);
  }
}

class App: Application() {
  override fun onCreate() {
      super.onCreate()
      val siprocalSDKSettings = SiprocalSDKSettings.Builder()
          .setAppServices(AppServices()) //only if use app-services module 
          .setTelephonyServices(TelephonyServices())//only if use telephony-services module 
          .setPhoneServices(PhoneServices())// only if use phone-services module 
          .build()
      SiprocalSDK.init(this, siprocalSDKSettings)
  }
}