Getting Started (v5)

The Apps Panel Android SDK is made to work with the Apps Panel Back Office. It provides a set of tools making your development easier and permitting to access all the features developed by Apps Panel.

The following information explain how to get started by implementing the SDK in your app.

Add the SDK

First, to use the Apps Panel SDK, your application min SDK version must be set to API 25 minimum.

defaultConfig {
        minSdkVersion 25
				...
}

In order to find the Apps Panel SDK dependency, you need to add the maven repository in the build.gradle file of the project.

allprojects {
    repositories {
        //...
        maven {
            url 'https://repository.appspanel.com/repository/apnl-public-android-sdk/'
            credentials {
                username 'guest'
                password 'CNONt0CkRzgqLpaEN92p'
            }
        }
    }
}

The second step consist in adding the dependency in the build.gradle of your application.

dependencies {
  //...
  implementation 'com.appspanel.android:sdk:5.6.0'
}

Configuration

In your Application class ou can configure the SDK by two way :

First way you have to pass your configuration at the installmethod. Call it by overriding protected void attachBaseContext(Context base) in your Application class as following :

class MainApplication : Application() {
  
    val appsPanelConfiguration = APLocalConfiguration(
         "AppName",
         "AppKey",
	       "PrivateKey
    )

    override fun attachBaseContext(base: Context) {
        super.attachBaseContext(base)
        APSDK.install(this@MainApplication, appsPanelConfiguration, this)
    }
  
}

A second way consist in extending your Application class by APApplication as below :

class MyApplication : APApplication() {
  
  override fun getAppsPanelConfiguration(): APLocalConfiguration {
        return APLocalConfiguration(
            "AppName",
            "AppKey",
            "PrivateKey"
        )
    }
  
}

As parameter of APLocalConfiguration you must provide these elements:

AppName : the name of your app on the Apps Panel Back Office
AppKey : the key corresponding to your app on the Apps Panel Back Office
PrivateKey : the private key to secure your app

Best practice

A proper way to initialize the SDK is to use gradle parameters to manage several environments. In your build.gradle file add the third attributes as below :

buildTypes {
    debug {
        //...
        //SDK conf
        buildConfigField "String", "AP_SDK_NAME", "\"my-project-dev\""
        buildConfigField "String", "AP_SDK_KEY", "\"abcdefghijklmnopqr\""
        buildConfigField "String", "AP_SDK_PRIVATE", "\"123456789ABCDE\""
    }
    //...
}

And replace the Apps Panel SDK parameters :

var appsPanelConfiguration = APLocalConfiguration(
            BuildConfig.AP_SDK_NAME,
            BuildConfig.AP_SDK_KEY,
            BuildConfig.AP_SDK_PRIVATE)

Custom SDK and API base URL

According to project specifications you may need to custom your SDK base url or API base url. In this case you can spefcify base url as param of your local configuration like below :

var appsPanelConfiguration = APLocalConfiguration(
  appName = BuildConfig.APSDK_ENV,
  appKey = BuildConfig.APSDK_KEY,
  appSecret = BuildConfig.APSDK_PRIVATE,
  baseURL = "https://api-domain.fr",
  sdkBaseURL = "https://sdk-domain.fr",
)

or specify it later like below :

localConf.baseURL = "https://api-domain.fr";
//or/and
localConf.sdkBaseURL = "https://sdk-domain.fr";

Custom SDK Headers

As of 5.4 you can also add custom headers to be added in each request :

APLocalConfiguration(
  appName = BuildConfig.APSDK_ENV,
  appKey = BuildConfig.APSDK_ENV,
  appSecret = BuildConfig.APSDK_PRIVATE,
  customSdkHeaders = hashMapOf(
    "header" to "value",
  ),
)

or later as well

localConf.customSdkHeaders = hashMapOf()

(note that you probably want to add your headers as soon as possible so that all requests use them, so with the first option)

Auto Backup (v5.6+)

As of 5.6, the SDK makes use of EncryptedSharedPreferences to store some values. This file must be excluded from auto backups (which are enabled by default on apps targetting API level 23+)

https://developer.android.com/identity/data/autobackup

You have two options

1. Entirely disable Auto Backups

If you do not need to backup anything with Auto Backups, this is the simplest option

<manifest ... >
    ...
    <application android:allowBackup="false" ... >
        ...
    </application>
</manifest>

2. Exclude the encrypted file(s) from the backup

If you still want to backup some files, you need to explicitly exclude the files in the backup rules

<manifest ... >
  ...
  <application
    android:allowBackup="true"
    android:fullBackupContent="@xml/backup_rules_legacy"
    android:dataExtractionRules="@xml/backup_rules_v31"
    ... >
  </application
</manifest>

The SDK creates SharedPreferences files with different names based on the applicationId, so you need to add a line for each one of them if you have different ones (for instance one for each environment)

It takes applicationId and adds _sdk_encrypted to it

With an app which applicationId would be com.example.{env} with dev, qa, and com.example with prod, you would get the following:

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <include domain="sharedpref" path="." />
    <exclude domain="sharedpref" path="com.example.dev_sdk_encrypted.xml" />
    <exclude domain="sharedpref" path="com.example.qa_sdk_encrypted.xml" />
    <exclude domain="sharedpref" path="com.example.sdk_encrypted.xml" />
</full-backup-content>

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        <include domain="sharedpref" path="." />
        <exclude domain="sharedpref" path="com.example.dev_sdk_encrypted.xml" />
        <exclude domain="sharedpref" path="com.example.qa_sdk_encrypted.xml" />
        <exclude domain="sharedpref" path="com.example_sdk_encrypted.xml" />
    </cloud-backup>

    <device-transfer>
        <include domain="sharedpref" path="." />
        <exclude domain="sharedpref" path="com.example.dev_sdk_encrypted.xml" />
        <exclude domain="sharedpref" path="com.example.qa_sdk_encrypted.xml" />
        <exclude domain="sharedpref" path="com.example_sdk_encrypted.xml" />
    </device-transfer>
</data-extraction-rules>

This presumes that you don't want/need to backup anything other than shared preferences. The default behaviour is to backup almost everything, specifying these rules completely override this default behaviour.

If you still want to include the default folders for backup, you need to explicitely include them in these rules.

That's all folks

Congratulations, the SDK is now integrated, now you should be able to compile your application 🙌