SDK Reference

This is legacy documentation. We are no longer onboarding new Gruveo for Developers customers.

This page provides a reference for the Gruveo SDK for Android and lists the methods and events exposed by the SDK.

Initialization

Once all of the prerequisites are in place, the initialization of a Gruveo screen looks as follows:

Constructor Parameters

callCode(code:String)
The room name to join or the Gruveo @handle to call.
clientId(clientId:String)
Your client ID that you get as part of your API credentials.
eventsListener(listener:Gruveo.EventsListener)
A listener that will be used for processing the events sent from the SDK to your application.
videoCall(video:Boolean)
Optional - determines if the camera should initially be turned on (video call) as opposed to off (voice-only call). Defaults to true.
requestCode(code:Int)
Optional - used for retrieving call information (e.g. call duration) after the call in onActivityResult. code is an identifying integer used as the second parameter in startActivityForResult(intent, requestCode).
otherExtras(bundle:Bundle)
Optional - a bundle with miscellaneous extras passed to the call activity. Possible values:

  • Gruveo.GRV_EXTRA_VIBRATE_IN_CHAT (boolean) - whether to vibrate upon receiving incoming text chat messages
  • Gruveo.GRV_EXTRA_DISABLE_CHAT (boolean) - whether to disable the text chat functionality completely.

Return Value

The constructor returns one of the following values:

  • Gruveo.GRV_INIT_OK - everything went fine
  • Gruveo.GRV_INIT_MISSING_CALL_CODE - the callCode value hasn't been set
  • Gruveo.GRV_INIT_INVALID_CALL_CODE - the callCode value contains invalid characters
  • Gruveo.GRV_INIT_MISSING_CLIENT_ID - the clientId value hasn't been set
  • Gruveo.GRV_INIT_OFFLINE - the device is offline.

SDK Methods

The methods listed below let you send commands to the SDK.

Helpers

Gruveo.generateRandomCode():String
Returns a random connection code (room name). Useful for generating a random room name for establishing a call between two or more participants.
Gruveo.isCodeValid(code:String)
Checks if code is a valid room name or Gruveo handle.

SDK Authentication

Gruveo.authorize(token:String)
Supplies the HMAC of a previously provided random token back to the SDK as part of the SDK authentication scheme. See Authentication for details.

Call Controls

Gruveo.endCall()
Ends the current call.
Gruveo.toggleVideo(enable:Boolean)
Sets the state of the camera. Pass true in the enable parameter to turn the camera on; pass false to turn it off.
Gruveo.switchCamera(useFront:Boolean)
Toggles between the device's front and rear cameras. Pass true in the useFront parameter to activate the front camera, or false to activate the rear one.
Gruveo.toggleAudio(enable:Boolean)
Sets the state of the microphone. Pass true in the enable parameter to unmute the mic or pass false to mute it.
Gruveo.toggleRecording(enable:Boolean)
Starts or stops call recording. Pass true in the enable parameter to start call recording or false to stop it. Recordings done with this method use the default "maximized" layout. Toggling call recording is only available when the call is ongoing. Check out Call Recording for call recording prerequisites and more information.
Gruveo.toggleRecording(enable:Boolean, layout:Int)
Starts or stops call recording with the ability to specify the recording layout when the recording is started. Pass true in the enable parameter to start call recording or false to stop it. The following layout values are supported:

  • Gruveo.GRV_LAYOUT_MAXIMIZED – maximize the currently active speaker
  • Gruveo.GRV_LAYOUT_TILED – display all participants’ pictures in tiles of approximately the same size.
Gruveo.toggleRoomLock(enable: Boolean)
Sets the room’s lock state. Pass true in the enable parameter to lock the room or pass false to unlock it. This functionality is only available when the call is ongoing.

Call State

Gruveo.isCallActive():Boolean
Returns a boolean indicating if there is an ongoing established call.

SDK Events

The Gruveo.EventsListener interface is used for sending information from the SDK to the app. The interface contains the following functions. RequestToSignApiAuthToken is called on a background thread, others from the main thread.

fun callInit(videoCall:Boolean, code:String)
Called when the call screen is created, even if the user is still only waiting for other participants. The videoCall variable indicates if the call was started as a video or voice-only one. code contains the room name or handle called.
fun requestToSignApiAuthToken(token:String)
This function is called when the SDK requests you to sign a random token as part the SDK authentication scheme. The token parameter contains the token value to sign. Please see Authentication for details.
fun callEstablished(code:String)
Called once the call between at least 2 participants is established. CallInit is guaranteed to be called before this function.
fun callEnd(data:Intent, isInForeground:Boolean)
This function is called when the call ends. The data parameter is used for passing extras with call information (see below). isInForeground indicates if the app was in the foreground when the call ended.
fun recordingStateChanged(us:Boolean, them:Boolean)
This event is fired whenever the call recording state changes, e.g. one of the call participants begins call recording. The us value indicates if we are currently recording the call (true for recording and false for not recording). them indicates if one of the other call participants is recording.
fun recordingFilename(filename:String)
This event is fired shortly after call recording is started locally and reports the filename under which the recording will be uploaded to the S3 bucket or FTP/SFTP. The filename parameter contains the filename of the recording.

Retrieving Ended Call Information

After a call ends, you can retrieve information about it (e.g. call duration) in two different ways:

  • Through the callEnd(data:Intent, isInForeground:Boolean) callback function of the Gruveo.EventsListener interface, which also tells you if the app was in the foreground when the call ended.
  • Through onActivityResult(), which will contain the call information only if you provided a requestCode during the call initialization.

Both approaches will return the same extras. onActivityResult() should be used if you want to use the call information and display it to the user, for example the call duration. Unfortunately, onActivityResult() is not triggered if the app is in the background as the call ends. If you want a more reliable way (and, for example, to be able to log the extras somewhere), you should be using the onCallEnd() callback, which is guaranteed to be executed after the call, before onActivityResult().

Regardless of the approach, the following call information can be retrieved from data:

data.getSerializableExtra(Gruveo.GRV_RES_CALL_END_REASON):CallEndReason
The reason for call ending. The possible values are:

  • Gruveo.BUSY - the call room is locked
  • Gruveo.HANDLE_BUSY - the callee is busy with another call
  • Gruveo.HANDLE_UNREACHABLE - the callee is unreachable
  • Gruveo.HANDLE_NONEXIST - the Gruveo handle doesn't exist
  • Gruveo.FREE_DEMO_ENDED - the 5-minute call limit has been reached (when using the demo client ID)
  • Gruveo.ROOM_LIMIT_REACHED - the room limit of 12 participants has been reached
  • Gruveo.NO_CONNECTION - lost connection
  • Gruveo.INVALID_CREDENTIALS - invalid token signature provided
  • Gruveo.OTHER_PARTY - the call ended due to the other party hanging up
  • Gruveo.USER - the call ended due to the user hanging up.
data.getStringExtra(Gruveo.GRV_RES_CALL_CODE)
The room name or Gruveo handle that was used for the call.
data.getIntExtra(Gruveo.GRV_RES_CALL_DURATION, 0)
The call duration in seconds, or 0 if the call was not established.
data.getIntExtra(Gruveo.GRV_RES_MESSAGES_SENT, 0)
The number of text chat messages sent to other users.

Revision History

August 15, 2018

  • Added a version of the Gruveo.toggleRecording() method with the layout parameter.

July 16, 2018

  • Added the recordingFilename event.

November 6, 2017

  • Renamed Gruveo.GRV_RES_CALL_ERROR and CallErrorType to Gruveo.GRV_RES_CALL_END_REASON and CallEndReason, respectively.
  • Removed the Gruveo.NONE value from CallEndReason.
  • Added the Gruveo.OTHER_PARTY and Gruveo.USER values to CallEndReason.

October 23, 2017

  • Added the new Gruveo.GRV_EXTRA_DISABLE_CHAT parameter in otherExtras.