Sternum Android SDK

This repository contains the files of the Sternum Android SDK, a versatile and flexible tool for implementing Relay applications and adding observability and traceability into Android devices using Java and C/C++.

For introduction and integration information, refer to the Online documentation.

How to import the SDK

Add SDK library to the project

Add the sternum-sdk-[release/debug].aar file under the app/libs directory in the target's project.

Declare SDK dependency

Add a dependencies in target's build.gradle file:

• Including release:

  dependencies {
      implementation files('libs/sternum-sdk-release.aar')
  }

• Debug/release specific configuration:

  dependencies {
      debugImplementation files('libs/sternum-sdk-debug.aar')
      releaseImplementation files('libs/sternum-sdk-release.aar')
  }

For more information refer to https://stackoverflow.com/questions/16682847/how-to-manually-include-external-aar-package-using-gradle-for-android.

Using the API

The Sternum Android SDK offers two interfaces: Java API (com.sternum.cloud.SternumSDK) and the native API (sternum_sdk.h).

Import SDK

To use the component within your code, add the following import:

import com.sternum.cloud.SternumSDK;
import com.sternum.cloud.protocol.tracing.Argument;
 
// Trace definition file which is obtained from SDK Configurator application.
// The package/path is specific to your project.
import com.example.example.TraceEventType;
 
// Argument definition file which is obtained from SDK Configurator application.
// The package/path is specific to your project.
import com.example.example.ArgumentRoleType;

Initialize the SDK

❗ Important: The SDK can only be initialized from the Java API.

If you plan to use the SDK native API (with or without the Java API), link your native component with sternum_sdk_static.a. Note that sternum_sdk_static.a implements JNI_OnLoad. If you encounter linking issues, please reach out to Sternum support. Then, invoke the initialization routine with loadNative=false.

Legacy API

Deprecated: This method is deprecated and kept for backward compatibility. It is recommended to switch to the new initialization API to benefit from additional features like user-defined callbacks.

If you plan to use native API, invoke the initialization routine as follows:

SternumSDK sternumSDK = SternumSDK.getInstance();
sternumSDK.initialize(getApplicationContext(), "gateway.sternum.cloud", 
                      true, new BigInteger("1234123412341234"), 
                      SternumSDK.DeploymentPhase.PRODUCTION, 0x2000, false);

If you plan to use only the Java API, invoke the initialization routine as follows:

SternumSDK sternumSDK = SternumSDK.getInstance();
sternumSDK.initialize(getApplicationContext(), "gateway.sternum.cloud", 
                      true, new BigInteger("1234123412341234"), 
                      SternumSDK.DeploymentPhase.PRODUCTION, 0x2000, true);

New API (Recommended)

Recommended: Use the new flexible initialization method, which supports optional user-defined callbacks.

1. Obtain the SDK Instance: Use SternumSDK.getInstance() to get the singleton instance of the SDK.
2. Configure com.sternum.cloud.SternumSDKSettings.
3. Set com.sternum.cloud.SternumTransmissionCallbacks (optional):
   • transmissionStarted: Triggered when a transmission starts.
   • transmissionFinished: Triggered when a transmission finishes, providing the number of packets and bytes transmitted.
   • packetsLost: Triggered when packets are lost, providing the number of lost packets and bytes.
   • error: Triggered when an error occurs, providing the error code and message.
4. Initialize the SDK: Call initialize with the application context and the configured settings.

Example Code:

// Obtain the SternumSDK singleton instance
SternumSDK sternumSDK = SternumSDK.getInstance();
 
// Create and configure an instance of SternumSDKSettings
sternumSDKSettings = new SternumSDKSettings();
sternumSDKSettings.sternumURL = "your.gateway.com";             // Set the Sternum URL
sternumSDKSettings.firmwareVersion = "your.firmware.version";   // Set the firmware version
sternumSDKSettings.relayOverrideDeviceID = true;                // Enable relay override for device ID if needed
sternumSDKSettings.accessToken = new BigInteger("1234567890");  // Set the access token
sternumSDKSettings.isProduction = false;                        // Specify the environment (production or development)
sternumSDKSettings.maxCacheSizeBytes = 10000;                   // Set the maximum cache size in bytes
sternumSDKSettings.loadNative = true;                           // Set to false if you intend to use native API
 
// Setup callbacks for monitoring SDK behavior, if needed
sternumSDKSettings.callbacks.transmissionStarted = () -> {
    // This callback is triggered when a transmission starts
};
 
sternumSDKSettings.callbacks.transmissionFinished = (long packets, long bytes) -> {
    // This callback is triggered when a transmission finishes
};
 
sternumSDKSettings.callbacks.packetsLost = (long packets, long bytes) -> {
    // This callback is triggered when packets are lost
};
 
sternumSDKSettings.callbacks.error = (int errorCode, String error) -> {
    // This callback is triggered when an error occurs
};
 
// Initialize the Sternum SDK with the configured settings
sternumSDK.initialize(mAppContext, mSternumSDKSettings);

Sending traces

sternumSDK = SternumSDK.getInstance();  
sternumSDK.trace(TraceEventType.TRACE_OS_INFORMATION, 
                 new Argument(ArgumentRoleType.ARG_ROLE_NAME, "Android"), 
                 new Argument(ArgumentRoleType.ARG_ROLE_VERSION, Build.VERSION.SDK_INT));

Relaying device data

sternumSDK = SternumSDK.getInstance();  
sternumSDK.relayDeviceData(SternumSDK.DeviceType.DEVICE_TYPE_A, deviceReceivedData);