Siprocal-SDK

Introduction

SIPROCAL's SDK is delivered as a Maven dependency.

🚧

Important:

SIPROCAL's SDK includes a configuration file called siprocal-config.json, which configures the SDK
behavior for a specific integration. This file will be provided by your SIPROCAL contact and should
be placed in the assets folder of the project.

The current version of the Siprocal SDK is 5.4.1

Step 1: Update build.gradle/settings.gradle.kts for Maven repository

Update the build.gradle or settings.gradle.kts file depending on the type of project you are using.

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

allprojects {
    repositories {
        mavenCentral()
    }
}

dependencyResolutionManagement {
            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"
        }
    }
}

dependencyResolutionManagement {
            repositories {
              	mavenCentral()
                maven {
                	url = uri("https://jitpack.io")
                }
            }
    }

Step 2: Gradle dependencies

Step 2.1: Gradle dependencies

Add the following dependencies to the app module's build.gradle:

implementation 'com.digitalreef.phoenix:<variant>:<version>' //for Groovy

implementation("com.digitalreef.phoenix:<variant>:<version>") //for Kotlin KTS

⚠️ About the variant:

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

Step 2.2: 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 3: Permissions Setup Instructions

Step 3.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 3.2: Exclusive permissions for Helios and 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 following method in your application’s flow, and the SDK will handle requesting the additional permissions described for Helios and Hestia:

SiprocalSDK.requestPermissionForGL(context);

SiprocalSDk.requestPermissionForGL(context)

Step 3.3: Permissions Required for capture Location (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.

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 3.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 4: SDK Initialization from the Application Class

The SDK should be initialized from the onCreate() method of the Application class in your app.

🚧

Important:

The SDK must always be initialized. If you need to turn it off or on, you must use the method we already provide in the following documentation Advanced Settings

Note: If you don't have the Application Class, you can get more info about this in the following link: Android Reference

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

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

Parameters of init() method:

Application : Reference to the application class (this).

Step 5: Validate if your app use Splash Screen

⚠️ If you are using Splash Screen:

If you app use a Splash Screen you need add the Splash Support, for that please check the Splash Support documentation: Splash Support Documentation

Step 6: Validate if you already use FCM in your project

⚠️ If you are using FCM:

Note: If you app use FCM you need add support for FCM Siprocal, for that please check the Firebase Integration section:

Firebase Integration

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

Step 8: Call to Action for Open Apps and Install from Play Store

⚠️ If you are using these CTA:

Note: If you app use CTA Open Apps and Install from Play Store you need add support for AppServices module.

If you need to add the AppServices module, please refer to the relevant documentation at the following link:

Sensitiva Data Documentation

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.