T​rill​B​it

Proximity Intelligence by Sound

Developer Guideline
Overview
Trillbit proprietary technology uses advanced ultrasonic data communication
protocol to send data over sound waves. Our SDK transforms any device with
a speaker into a transmitter and any device with a microphone into a receiver.
Sound waves create a secure nearby proxy for data transmission, our
technology is eliminating the need for complex, expensive, and
power-consuming wireless technologies.

Setup

Install Trillbit SDK

Trillbit SDK is available as an AAR. Copy the trill-data-sdk.aar file to your
app/libs directory. Add the following to the dependencies block of your
Module build.gradle
Gradle script To add the trill-data-sdk dependency, open build.gradle file of
your application module and add trill-data-sdk dependency as follows.

dependencies {
​compile 'com.trillbit.datasdk:trill-data-sdk@aar'
}

Page 2
To instruct Gradle where to find the local aar file, add flatDir section to the
repositories block. (You’ll need to add a repositories block if one does not
already exist).

repositories {
flatDir {
dirs 'libs'
}
}

Requirements
Minimum SDK Version: Android 4.1 (API level 16)
Recommended target SDK version: Android 9.0 (API level 28)
Gradle Plugin version : 2.2.0 (​ or later)
Gradle wrapper version: 2.14.1 ​(or later)
Android Studio: 2.2

Manifest file changes

Since the introduction of the Gradle based build system in Android, Manifest
file settings from Android library project’s AAR file are automatically merged
into your application’s APK.
So you are not required to make any changes in your application’s manifest
file. All required permissions, Activities and Receiver entries will be
automatically imported from trill-sdk AAR file into your application build.

Page 3
Please refer to A​ ppendix​ for the list of permissions, Activities, and receivers
that trill-sdk uses.
For more details on Manifest merging and Manifest file conflict resolution,
refer to this ​Android developer documentation​.

Integrating Trill SDK

Setup
Add ABI filter
Trillbit SDK uses native code (.so) files and ships with native code shared
object library files for following ABI’s:
● armeabi
● armeabi-v7a
● arm64-v8a
● x86
● x86_64
● mips
As you might not need to support all ABI’s in your app, please add an ABI filter
in your app modules build.gradle file.
To add an ABI filter, open the build.gradle file for your app module and add
ndk abiFilters in android-> defaultConfig section.
Eg:​ If you need to support only armeabi-v7a and x86 architectures, add
abiFilters only for these two ABI’s as shown below:

android {
defaultConfig {
​ndk {
abiFilters "armeabi-v7a", "x86"
}
}
}

Page 4
If you are not sure about which ABI’s to support, please add default ABI
support for x86 and arm-v7a arch as shown below.

Instantiate Trill Data SDK

Beginning in version 6.0 (API level 23), Android allows users to toggle apps
permissions at run time. Also by default, some permissions will be disabled
when the app starts up for the first time.
The RECORD_AUDIO permission, which is fundamental in the use of Trill,
Therefore, it is important to check your app has RECORD_AUDIO permissions
every time it is brought to the foreground.

private void s​ etup() {

trillSDK =​ n
​ ew ​TrillSDK(​this​, "​ KEY"​, "​ SECRET"​);
trillSDK​.init(TrillSDK.SDKType.​SENDER​, ​new T
​ rillCallbacks() {
@
​ Override
p
​ ublic void o
​ nError(int code, String errMessage) {
​super​.onError(errMessage);
}
@
​ Override
p
​ ublic void o
​ nInfo(int code, String logs) {
​super​.onInfo(logs);
}
@
​ Override
p
​ ublic void o
​ nDataReceived(String Payload) {
​super​.onDataReceived(payload);
}
});}

Page 5
Trill SDK setup function should be called after Permissions block

@Override
protected void o
​ nResume() {
s​ uper​.onResume();
String [] neededPermissions = {
Manifest.permission.​RECORD_AUDIO​,
Manifest.permission.​MODIFY_AUDIO_SETTINGS​,
Manifest.permission.​INTERNET​,
Manifest.permission.​ACCESS_NETWORK_STATE
​};

i​ f ​( ContextCompat.​checkSelfPermission (​t​ his​, Manifest.permission.​RECORD_AUDIO )​ !=

PackageManager.​PERMISSION_GRANTED ​) {
ActivityCompat.​requestPermissions ​
( t​ his​, neededPermissions, ​1 ​) ;
} ​else ​{
setup();
}
}

@Override
public void ​onRequestPermissionsResult(​int ​requestCode, ​@NonNull ​String[]
permissions, @​ NonNull i​ nt​[] grantResults) {
s​ uper​.onRequestPermissionsResult(requestCode, permissions, grantResults);
setup();
}

Trill SDK Methods

We recommend using the Android lifecycle methods, onResume() and
onPause() to detect permissions and to trigger start and stop listening for POS.
See the following.Handling lifecycle event for pos

Page 6
● start​()
Start listening to User authentication on POS Device. The method returns nothing.

● stop​()
Stop listening to User authentication on POS Device. The method returns nothing.

● startAuthentication​(String UserID, int sdkModes, int repeat_count, int

repeat_mode)
Start the authentication process on the User side, UserID would be a string of 19
Characters.

sdkModes​: ​TrillSDK.SDKModes.FAR / TrillSDK.SDKModes.NEAR

repeat_mode: T
​ rillSDK.SDKModes.FINITE / TrillSDK.SDKModes.INFINITE
repeat_count: no of times to repeat the authentication process in case of
failure. The param works only if repeat mode is set to finite.
● stopAuthentication​()
The method is used to stop the authentication process initiated from the
application side. Stopping authentication while sdk is switching between
playing and receiving isn’t possible, In that case an error callback is
returned to application side.
● init​(int sdkType, TrillCallbacks trillCallbacks)
The method Initializes the Trill SDK Library, Also attaching SDK callback to Trill SDK
library.

SDK Type: T
​ rillSDK.SDKType.SENDER / TrillSDK.SDKType.RECEIVER
The method Initializes the Trill SDK Library, Also attaching SDK callback to Trill SDK
library.

SDK Type: T
​ rillSDK.SDKType.SENDER / TrillSDK.SDKType.RECEIVER

Page 7
 ● isWiredHeadsetConnected​():
The method returns interger value. The headphones could be wired or
wireless both.
Response could be:
AudioDeviceInfo.​TYPE_WIRED_HEADSET

AudioDeviceInfo.​TYPE_WIRED_HEADPHONES

AudioDeviceInfo.​TYPE_BLUETOOTH_A2DP

AudioDeviceInfo.​TYPE_BLUETOOTH_SCO

Callbacks

● onSDKReady​(int status)
The callback is triggered as soon as SDK is Initialized.

● onError​(int code, String errMessage)

Callback reporting for Trill SDK. The callback received an error code with an error
message.

● onInfo​(int code, String logs)

Callback reporting any info logs from Trill SDK. The callback received an info code
with an info message.

● onDataReceived​(String Payload)
Callback reporting user verified. The status received here will always be
STATUS_SUCCESS with UserID of 19 characters.

Page 8
APK Split
To optimize your apps final APK size, we strongly recommend you to use APK
split functionality provided by the gradle build system.
If you are supporting multiple ABIs in your app, then you can split your app
APK per ABI and effectively reduce the APK size.
Please refer Android developer documentation for more details about ABI
APK splits here :
https://developer.android.com/studio/build/configure-apk-splits.html#conf
igure-abi-split

Appendix
Manifest file permissions
Following permissions are used by trill-sdk.

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

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

In case of any issue with automatic manifest merging, please add above
permissions in your application’s Manifest file.

Troubleshooting
Dex Error : Enable Multidexing

Page 9
If adding third-party sdk libraries to your project causes dex error. Enable
multidex support for your app. Refer following link to enable multidex support
in the app.
https://developer.android.com/tools/building/multidex.html

Manifest merge conflict

In case of any issues during automatic Manifest file merging, please refer
Android developer documentation on Manifest merge​.

Page 10
Error Responses
Error Code Error Message Description

400 SDK Already Running Trying to init sdk multiple times.

402 SDK Type Sender doesn't supports called Trying to call start() or stop() method
method, check documents from sender type sdk.

401 Missing Microphone Permission Microphone permission is not taken

from the application side.

403 SDK Type Receiver doesn't supports called Trying to call start() or stop() method
method, check documents from sender type sdk.

404 SDK Expired The error is triggered in case sdk has

expired. Contact d​ evelopers@trillbit.com
in case your sdk has expired.

501 Unable to authenticate sdk For the first time sdk need to authorise
with trillbit server. The error comes
when sdk is unable to verify, Especially in
case of no internet.

406 Unsupported Payload Length Payload length ranges between 6 - 36,

any other length > 36 or < 6 will throw
this error.

512 Unable to stop authentication The error is triggered while stopping

authentication in between the process of
switching between playing and receiving
ack/nack

513 Authentication not running The error is trigger when application

tries to stop authentication but sdk is in
idle mode.

514 Wired or Wireless handset is connected The error is trigger from multiple
methods. The error states User device is
connected to BLE or wired handset or
speaker.

515 Unable to start recording. The error is triggered from receiver flow
when reorder is trying to start but due to
unavailability of resources the process is
in halt.

516 Unable to start processing audio The error is triggered from receiver flow
when processing thread is trying to start
but due to unavailability of resources the
process is in halt.

Page 11
517 Recorder Specific Error (All Recorder error
for debugging purpose )
The error is triggered from the recorder
for both sender and receiver. Error
message will have the exact recorder
error. The error callback is for debugging
purpose

Info Response
Response for Message Description

Receiver Unable to verify user In case when, the receiver side is unable to
decode the payload.

Sender Unable to verify, Trying Again In Case when, the sender side is unable to
verify the current transaction.

Sender Unable to verify, Session Timeout In Case when, the sender side is unable to
verify within the whole session.

Sender User Verified The sender side is verified

Sender Last Transaction Time [ time in
milliseconds ] Completed in [ no of
attempt ] attempt. Complete
Transaction Time : [ time in
milliseconds ]
Triggers after sender is verified, the message
returns no of attempts, Last Transaction time
and Complete Transaction time

Page 12