Android
Getting started with Everlink
Guide focus: Setting up Everlink’s Android SDK to enable ultrasonic proximity verification.
This guide has been split into 2 parts: Set Up and Usage.
Set Up: Please follow the steps below to get started:
- Add Everlink SDK to your app in Android Studio
- Add the required permissions
- Creating an instance of the Everlink class and setting up its listeners
1) Add EverLink SDK to your app
Before you can use Everlink you must add the Everlink SDK to your app, alongside another dependency (see example in the code below).
First on Gradle file settings.gradle (Project) add the Everlink Maven repository:
// Other codes...
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
repositories {
google()
mavenCentral()
jcenter()
maven {
url "https://repo.everlink.co/repository/maven-releases/"
}
}
}
rootProject.name = "EverlinkDemo"
include ':app'
// Other codes...
Now in Gradle file build.gradle (Module: app) add the following dependencies and sync your app. After this the Everlink SDK will be successfully added to your project. (The Apache math library is needed for the calculations required in the processing of the detected audio.)
dependencies {
// Other codes...
implementation 'com.everlink:broadcast:3.0.0'
implementation 'org.apache.commons:commons-math3:3.6.1'
// Other codes...
}
2) Permissions
Next you need to add the required permissions to the AndroidManifest.xml file:
<Manifest>
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<Application>
// Other codes...
</Application>
</Manifest>
3) Import the Everlink class
In order to start using Everlink - so that you can receive and send tokens over audio - import the EverLink class, and set its listeners.
Changing the package at the top to the correct package of your project, and string myAppID to your key, which we will provide to you:
package co.everlink.test;
import com.everlink.broadcast.Everlink;
import com.everlink.broadcast.exceptions.EverlinkError
public class MainActivity extends AppCompatActivity {
private static final int REQUEST_MICROPHONE = 800;
private Everlink everlink;
private final String myAppID = "12345";
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
//check permissions
if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.RECORD_AUDIO)
!= PackageManager.PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(this, new String[]{
android.Manifest.permission.RECORD_AUDIO}, REQUEST_MICROPHONE);
}
//set up Everlink class
everlink = new Everlink(getApplicationContext(), this, myAppID);
everlink.setAudioListener(new Everlink.audioListener() {
@Override
public void onAudiocodeReceived(String token) {
// you can now identify via the returned token what location/device was heard
Log.d("Everlink test", token);
}
@Override
public void onMyTokenGenerated(String oldToken, String newToken) {
//a new token generated, to save in your database
Log.d("Everlink test",newToken);
Log.d("Everlink test",oldToken);
}
});
}
}
Congrats, you’ve now set-up Everlink! Now onto usage.
Usage: After the client app is set up, you are ready to begin verifying and identifying devices, you can now:
- Generate user identifying tokens
- Detect codes
- Send codes
The EverLink class has a number of listeners and methods that you can use to send and receive audio codes. We do all audio code generation, token checks and returns, and stop listening on code detection automatically.
1) Create token
If you wish to manually generate a new user token call: createNewToken(startDate);
newToken.setOnClickListener(new View.OnClickListener() {
final String startDate = "";
public void onClick(View v) {
try {
everlink.createNewToken(startDate);
} catch (EverlinkError err) {
Log.d("Everlink error fired",err.getMessage());
}
}
});
Function createNewToken(startDate) takes a validity start date in the form 'YYYY-MM-DD’. The token will be valid for two weeks after this date. If no validity date is provided then it will be the current date. Once a device token is expired it will automatically refresh.
We will return the identifying token via the onMyTokenGenerated listener which we implemented above in step 3 on the previous section.
everlink.setAudioListener(new Everlink.audioListener() {
// Other codes...
@Override
public void onMyTokenGenerated(String oldToken, String newToken) {
//a new token generated, to save in your database
sendEverlinkTokenToBackend(newToken);
}
});
This Everlink unique identifying token should be send to your backend and saved to your database and associated with a user. This will allow us to broadcast this users’s identifier over ultrasound and allow other devices to detect whether they are in proximity with this user.
On your backend you might have some code like this:
“UPDATE employees SET everlink_token = newToken WHERE employee_id = ID”;
Downloading Tokens
To download the audio code associated with a token so it can later be played or detected offline, call function saveSounds() passing it an array of tokens:
saveTokens.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
//Save an array of tokens and their corresponding audiocodes.
String[] tokensArray = {
"exampleToken12345",
"exampleToken12346",
"exampleToken12347"
};
everlink.saveSounds(tokensArray);
}
});
Call clearSounds() to delete all downloaded tokens and their corresponding audiocodes:
clearTokens.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
everlink.clearSounds();
}
});
For situations where it is possible to download your users' tokens prior to detecting, we strongly recommend that you do. This will reduce latency and make the verification faster and more reliable.
2) Detect Code
When you want to detect an audio code simply call: startDetecting();
// Other codes...
startDetectingButton.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
try {
//to start listening for a code call:
everlink.startDetecting();
} catch (EverlinkError err) {
Log.d("Everlink error fired",err.getMessage());
}
}
});
stopDetectingButton.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
//to stop listening call:
everlink.stopDetecting();
}
});
// Other codes...
Which will cause the device to start listening for an audio code, on successful detection we will return the identifying token of the heard device via the onAudioCodeReceived listener.
everlink.setAudioListener(new Everlink.audioListener() {
@Override
public void onAudiocodeReceived(String token) {
// you can now identify via the returned token what location/device was heard
sendEverlinkTokenToBackend(token);
}
// Other codes...
});
You can now search your database using the returned Everlink unique identifying token to find the detected user. You might have some code like this:
"SELECT * FROM employees WHERE everlink_token = token";
3) Send Code
When you want to start emitting an audiocode simply call: startEmitting();
// Other codes...
startPlayingButton.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
try {
//set the output audio volume
boolean useLoudspeaker = true;
everlink.playVolume(0.9, useLoudspeaker);
//to start emitting this device's audiocode call:
everlink.startEmitting();
} catch (EverlinkError err) {
Log.d("Everlink error fired",err.getMessage());
}
}
});
// Other codes...
stopPlayingButton.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
//to stop emitting call:
everlink.stopEmitting();
}
});
// Other codes...
You can alternatively pass a token as an argument and its audiocode will play, as shown below:
// Other codes...
playTokenButton.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
try {
//set the output audio volume
boolean useLoudspeaker = true;
everlink.playVolume(0.9, useLoudspeaker);
//to start emitting an audiocode call:
everlink.startEmittingToken("exampleToken12345");
} catch (EverlinkError err) {
Log.d("Everlink error fired",err.getMessage());
}
}
});
// Other codes...
Function playVolume(volume, loudspeaker) allows you to set the volume and whether the audio should default to the loudspeaker.
We can detect if headphones are in use, and route the audio to the device’s loud speaker. Though users might experience a short pause in any audio they are listening to, while the audiocode is played, before we automatically resume playing what they were listening to before the interruption.