Sternum iOS SDK

This repository contains the files of the Sternum iOS SDK, a versatile and flexible tool for implementing Relay applications and adding observability and traceability into iOS devices using C, C++ or Objective-C.

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

Import the SDK

1. Create a directory called libs in your component root directory.
2. Take the provided libSternumSDK.a and include/ and place it in the libs directory.
3. Open your component in Xcode ([component].xcodeproj) in the Xcode IDE. Use a right click to add existing files to the project and select the libs/ directory. When adding the libs/ directory to the project, make sure to select all of the relevant targets to avoid compilation errors.

Using the API

Include the SDK

Add the following import to use the component within your code:

• Objective-C:
  

  #import "sternum_sdk.h"

• C/C++:

  #include "sternum_sdk.h"

Initialize the SDK

You can initialize the SDK in two ways: using the legacy API or the new, recommended API.

Legacy API

Note: 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.

sternum_sdk_initialize("gateway.sternum.cloud", false, 1234123412341234, true, 0x2000);

New API (Recommended)

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

Step 1: Define callbacks (optional)

If you want to be notified about transmission events or errors, define C callbacks. If you don't need callbacks, you can skip this step — all callbacks are optional. Check sternum_transmission_callbacks_t for the complete structure description.

void transmission_started_callback(void) {
    NSLog(@"[SDK] Transmission started.");
}
 
void transmission_finished_callback(size_t packets_count, size_t bytes_count) {
    NSLog(@"[SDK] Transmission completed: %zu packets (%zu bytes) sent.", packets_count, bytes_count);
}
 
void packets_lost_callback(size_t packets_count, size_t bytes_count) {
    NSLog(@"[SDK] Packet loss detected: %zu packets (%zu bytes) lost.", packets_count, bytes_count);
}
 
void error_callback(int error_code, const char *error_message) {
    NSLog(@"[SDK] Error %d: %s", error_code, error_message);
}

Step 2: Fill the settings structure and initialize the SDK

Refer to sternum_ios_sdk_settings_t for the complete settings structure description.

sternum_ios_sdk_settings_t sdk_settings;
init_sternum_ios_settings(&sdk_settings);
 
sdk_settings.sternum_url = "gateway.sternum.cloud";
sdk_settings.firmware_version = "iOS_Example_v0.1.1";
sdk_settings.access_token = access_token;
sdk_settings.is_production = true;
sdk_settings.max_cache_size_bytes = 65000;
sdk_settings.relay_override_device_id = false;
 
// Optional callbacks
sdk_settings.transmission_callbacks.transmission_started = transmission_started_callback;
sdk_settings.transmission_callbacks.transmission_finished = transmission_finished_callback;
sdk_settings.transmission_callbacks.packets_lost = packets_lost_callback;
sdk_settings.transmission_callbacks.error = error_callback;
 
result = sternum_ios_sdk_initialize(&sdk_settings);

Send traces

STERNUM_ADS_TRACE(TRACE_OS_INFORMATION, 
                  ARGUMENT_STRING(ARG_ROLE_NAME, 3, "iOS"), 
                  ARGUMENT_FLOAT(ARG_ROLE_VERSION, 
                                 [[[UIDevice currentDevice] systemVersion] doubleValue]));

Relaying device data

sternum_sdk_relay_device_data(DEVICE_TYPE_A, rawData, sizeof(rawData));

Please refer to sternum_sdk.h and sternum_trace_api.h for complete API documentation.