Client Setup

On the app side, OneSpan App Shielding Insight is enabled by including the necessary XML elements in the main App Shielding configuration file and then running the Shielding Tool on the unprotected version of the app file. At a minimum, the configuration must have the following elements:

<?xml version="1.0" encoding="UTF-8"?>
<shield>
    <config>
        ...
        <insightServerURL v="https://my-agent-server.com/insight" />
        <insightServerPublicKey v="R6Ebzldq24J3M4SKFLdjavW4y4S0Ruh046z28LDQ62M=" />
        <insightClientPrivateKey v="m28J17YFOdeWGMnAKWRNC6xanbwV/J/CDszxSucDQAI=" />
    </config>
</shield>

The values for insightServerPublicKey and insightClientPrivateKey are generated by the agent executable. The insightServerURL is the endpoint where you have deployed the Insight Agent. Note that this URL must be an HTTPS URL, meaning the server that is hosting the Insight Agent must have SSL/TLS configured.

Additional Configurations

The following options can be added to the App Shielding config file to further control the behavior of the Insight Client:

Android Specifics

For Android apps, the AndroidManifest.xml file in the source code also needs the following permissions added:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Custom Data

You can optionally define your own custom data, as bytes, that is sent along with the Insight message. Custom data is available on a custom_data property at the envelope level when forwarded by the Insight Agent. Note that custom data is not saved in the Insight Cloud (and, therefore, not viewable in the Download Portal). Custom data also has an upper limit of 2 MiB.

Custom data is set in the application code using a setCustomData() method. See below for operating system-specific examples. The setCustomData() method can be called at any point when you want to start including it with the Insight data. If the app is restarted, it remembers the last call to setCustomData() before the app was shut down.

There is only one field for custom data. If you call setCustomData() again with a different argument, then the previous data is replaced.

Android Implementation

Add the ShieldSDK-insight Maven dependency to your Android project. This is found in the App Shielding package’s SDK/maven/ directory. For more information on importing App Shielding libraries, see App Shielding for Android Reference Documentation. Afterward, you can use the setCustomData() method in your Java code in the following manner:

import no.promon.shield.insight.Insight;
...

Insight.setCustomData("my custom data".getBytes());

iOS Implementation

Add the ShieldSDK.xcframework bundle from the Shield package to your iOS project. For more information on importing App Shielding libraries, see App Shielding for iOS Reference Documentation.

Afterward, you can use the setCustomData() method in your Swift code in the following manner:

import ShieldSDK
...

PRMShieldInsight.shared.setCustomData(Data("my custom data".utf8))

If you are using Objective-C instead of Swift, the process will look more like the following example:

#import <ShieldSDK/Shield.h>
...

NSData* myData=[@"my custom data" dataUsingEncoding:NSUTF8StringEncoding];
[[PRMShieldInsight sharedInsight] setCustomData:myData];