SilentLog SDK — Technical reference

What the SDK does

The SDK runs inside your existing app. Once an account is connected and tracking has started, it records location and motion signals, classifies them into stays, walking and vehicle travel, and uploads them to SilentLog Analytics. Your app can request one day of that data at a time. There is no separate app for the end user to install.

It is distributed as an .xcframework on iOS and an .aar on Android.

Integration flow

The sequence is the same on both platforms; the methods differ. Step 5 is not optional — behavioural data is empty until an account is connected.

API surface

iOS and Android are listed separately on purpose. Initialisation and the accuracy setting do not merely differ in naming — they differ in meaning.

iOS

• Initialise

  - (void)setClientId:(NSString *)clientId clientSecret:(NSString *)clientSecret;

  Call in didFinishLaunchingWithOptions. From version 2.1.0, connecting an account with an invalid client ID disables that client ID inside the SDK: every server-backed method stops and tracking halts.

• Request permissions

  - (void)requestLocationAuth;
- (void)requestMotionActivityAuth;

  Both are required on iOS. Call both even when authorisation has already been granted.

• Connect an account

  - (void)connectApi:(NSString *)accountId gender:(NSInteger)gender birthday:(NSDate *)birthday completion:(void(^)(SilentLogConnectResult result, NSString *userId))completion;

  Until this succeeds, behavioural data is returned as nil. A 404 appears in the SDK log on first account creation; that is expected.

• Start and stop tracking

  - (void)startTracking;
- (void)stopTracking;

  Start from applicationDidBecomeActive, or sceneDidBecomeActive if you use the UIScene lifecycle.

• Accuracy and battery trade-off

  - (void)setTrackingPriortyType:(NSInteger)type;

  On iOS the level is a distance filter. 0 — 10 m. 1 — 100 m, and location services stop when a stay is detected (default). 2 or higher — 100–1000 m, stopping on a detected stay. The method name is spelled as shown.

• Read one day of data

  - (void)getDataFor:(NSDate *)targetDate withCompletion:(void(^)(id responseObject))completion;

  Returns an NSDictionary. See the call-rate constraint below.

Android

• Initialise

  fun build(context: Context, listener: SilentLogOperationListener, clientId: String, clientSecret: String)

  Call from onCreate of a class extending Application, and implement SilentLogOperationListener on that same class. An unexpected credential format raises IllegalArgumentException. The invalid-client-ID behaviour described for iOS applies here too.

• Request permissions

  (platform permission flow, then register the result with the SDK)

  Android does not use a motion-activity permission. Request location permission from your Activity and register the result with the SDK. From Android 11 this needs two separate prompts: foreground location, then background location.

• Connect an account

  connectApi(username: String?, gender: Int?, birthday: Date?, privateKeyMap: Map<String, Any?>? = null, onCompleted: (result: ConnectResult, userId: String?) -> Unit)

  Same precondition as iOS: without a connected account, behavioural data is empty.

• Start and stop tracking

  fun startTracking()
fun stopTracking()

  Call from a lifecycle point such as onStart.

• Accuracy and battery trade-off

  fun setTrackingPriorityType(type: Int)

  On Android the level is an interval, not a distance. 0 — 2 seconds. 1 or higher — 10 seconds. Both stop location services when a stay is detected. The default is 1.

• Read one day of data

  fun getDataFor(targetDate: Date): Single<String>

  Returns a JSON string. See the call-rate constraint below.

Data model

One day of behaviour is returned as a Daily. Field-level definitions are in the manual supplied with the SDK.

• Daily — one calendar day for one user.
• Segment — groups activities as move or place. move holds wlk and trp; place holds sty.
• Activity — sty (stay), wlk (walking), trp (vehicle travel).
• TrackPoint — the location points attached to an activity.
• ActivityTag — string tags attached to an activity. Store objects as JSON. A tag named predict holds a server-side classification.

Platform requirements

iOS

Both location and motion activity authorisation are required. Behaviour classification is tuned for how people carry and use an iPhone; iPad usage patterns differ, so the same classification quality should not be assumed there.

Android

Supports Android 14 and Android Gradle Plugin 8. Gradle and ProGuard configuration both changed for that, and the sample app is the reference. Device-level battery optimisation settings affect background collection.

Add these permissions to AndroidManifest.xml:

You also add three classes to the project: one extending Application, a geofence Service, and a background-launch Service. The sample app contains a reference implementation of each.

Constraints and known behaviour

1. Collection is not guaranteed

   Some device and network states prevent collection or upload — for example a device with no SIM, or with mobile data disabled. On iOS, background collection can be incomplete if the host app is force-quit or left unopened for long periods; we ask integrators to guide their users accordingly.

2. An account must be connected first

   connectApi has to succeed before any behavioural data exists. If the account, gender or birthday is absent, the record is treated internally as unregistered, and the Analytics API returns gender and birthday as empty strings.

3. Invalid credentials are terminal

   From version 2.1.0, connecting an account with an invalid client ID makes that client ID unusable inside the SDK. Every server-backed method stops and location collection halts. Validate credentials before you ship.

4. Daily data has a call-rate limit

   Do not call getDataFor on a timer. Roughly 100 or more calls per user per day counts as excessive. Each call makes one to two server requests, so heavy use also raises the user's data and battery consumption.

5. Stored location points have a daily cap

   The SDK caps how many location points it stores per day. The current figure is supplied with the manual.

6. Multi-device use has defined behaviour

   From version 2.0.1, when a user moves to a new device the old device's data is read once. If the old device uploads afterwards, it overwrites. Device changes and reinstalls are supported; continuous parallel use of two devices is not recommended.

7. Store review needs preparation

   App Store review expects the listing to state that the app collects location continuously in the background and may affect battery life, and may ask for a screen recording showing the behaviour as described.

Optional features

These are available on request rather than by default. Contact us for scope and terms.

• Campaign delivery — content triggered by location or beacon conditions, registered in the SilentLog Analytics console. Opt-in per account; accounts start as not participating. Your app implements the presentation.
• Step callbacks — a callback every N steps, with the threshold configurable.
• Pass-through processing — forward a payload and its type, together with the SilentLog user ID, to a server you nominate.
• Dedicated environment — the API endpoint the SDK talks to can be changed.

Frequently asked

Does the end user have to do anything after granting permissions?

Not in normal use, but not in every condition either. The permissions must stay enabled, and OS or device power-management settings can suspend background collection. On iOS, the app being force-quit or unopened for long periods reduces what is collected.

Can we control battery consumption?

Partly. The accuracy level changes how often the SDK asks for location, which is the main lever. Actual consumption still depends on the device, the OS version, network conditions and how much the user moves.

What happens when a user changes device or reinstalls?

From version 2.0.1, the new device reads the old device's data once, then reads locally. An upload from the old device after that point overwrites.

Is campaign delivery enabled by default?

No. It is opt-in per account and accounts start as not participating.

Can it run against a dedicated environment?

A dedicated environment is available. The hosting model and data handling are agreed separately.

Getting access

The SDK binaries, the full manual and a sample app are provided under agreement. Pricing is listed on the pricing page.

Related: SilentLog SDK (Japanese overview)  /  SilentLog Analytics MCP — Technical reference  /  Pricing