Transition guide for the Chirp Connect Android SDK (v2 to v3)

Overall changes

  • The SDK can now work completely offline if you have a licence file.
  • Chirp with associated data has been removed and is no longer available.
  • The Chirp is now called a payload and it is represented by a byte[] which can have a dynamic length with a maximum length defined by your protocol.

Interface changes

All old dependencies were removed and a new dependency com.squareup.okhttp3:okhttp:3.9.0 was added.

compile 'io.chirp.connect:chirp-connect:3.3.2-release@aar'
compile 'com.squareup.okhttp3:okhttp:3.9.0'

Package imports are updated. New minimal dependencies required look like this:

import io.chirp.connect.ChirpConnect;
import io.chirp.connect.interfaces.ConnectEventListener;
import io.chirp.connect.interfaces.ConnectLicenceListener;
import io.chirp.connect.models.ChirpError;
import io.chirp.connect.models.ConnectState;

SDK initialisation has been change as well.

ChirpConnect chirpConnect = new ChirpConnect(this, APP_KEY, APP_SECRET);
ChirpError setLicenceError = chirpConnect.setLicence(networkLicence);
if (setLicenceError.getCode() > 0) {
  Log.e("ChirpError:", setLicenceError.getMessage());
}

Or you can use the dynamic licence loading if you want to be able to control the licence from the Admin Centre.

chirpConnect.getLicence(new ConnectLicenceListener() {

  @Override
  public void onSuccess(String networkLicence) {
    Log.d("getLicence", "onSuccess");
    ChirpError setLicenceError = chirpConnect.setLicence(networkLicence);
    if (setLicenceError.getCode() > 0) {
      Log.e("ChirpError:", setLicenceError.getMessage());
    }
  }

  @Override
  public void onError(ChirpError chirpError) {
    Log.e("getLicence", chirpError.getMessage());
  }
});

The callback interface has changed as well. The interface is now called ConnectEventListener and have the following implementation:

chirpConnect.setListener(new ConnectEventListener() {

  @Override
  public void onSent(byte[] payload) {
    Log.v("chirpConnectDemoApp", "This is called when a payload has been sent " + payload);
  }

  @Override
  public void onSending(byte[] payload) {
    Log.v("chirpConnectDemoApp", "This is called when a payload is being sent " + payload);
  }

  @Override
  public void onReceived(byte[] payload) {
    Log.v("chirpConnectDemoApp", "This is called when a payload has been received " + payload);
  }

  @Override
  public void onReceiving() {
    Log.v("chirpConnectDemoApp", "This is called when the SDK is expecting a payload to be received");
  }

  @Override
  public void onStateChanged(byte oldState, byte newState) {
    Log.v("chirpConnectDemoApp", "This is called when the SDK state has changed " + oldState + " -> " + newState);
  }

  @Override
  public void onSystemVolumeChanged(int old, int current) {
    Log.d("chirpConnectDemoApp", "This is called when the Android system volume has changed " + old + " -> " + current);
  }

});

To start and stop audio processing loop you should call the same .start() and .stop() method except now it needs to be called on the new chirpConnect instance.

chirpConnect.start();    //to start audio processing
chirpConnect.stop();    //to stop audio processing

The .chirp() method that sends the data is now called .send() and you have to pass a byte array instead of a string. The size of the payload can be dynamic which will make your chirp shorter for smaller payloads however there is a maximum size that you can send and it is defined by your licence. The maximum payload length is returned by the .getMaxPayloadLength() method.

long maxLength = chirpConnect.getMaxPayloadLength();
byte[] payload = chirpConnect.randomPayload(maxLength);
chirpConnect.send(payload);

In order to make sure the SDK will be closed, we need to call the close method to empty the memory and to delete the instance when the activity is destroyed.

@Override
public void onDestroy() {
  super.onDestroy();
  chirpConnect.stop();
  try {
    chirpConnect.close();
  } catch (IOException e) {
    e.printStackTrace();
  }
}

For convenience here are two functions that converts a string to byte-array and a byte-array to string.

public static byte[] stringToByteArray(String s) {
	return s.getBytes(StandardCharsets.US_ASCII);
}
public static String bytesToString(byte[] byteArray) {
  return new String(byteArray, StandardCharsets.US_ASCII)
}

Create a chirp with JSON data is not longer available in the SDK. Alternatively, if you need to map a payload to a JSON Object you can use a cloud service such as Firebase. See firebase.google.com for more details.