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 iOS 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:

Parameters

callCode:(NSString *)
The room name to join or the Gruveo @handle to call.
videoCall:(BOOL)
Determines if the camera should initially be turned on (video call) as opposed to off (voice-only call).
onViewController:(UIViewController *)
The view controller for presenting the Gruveo call screen after initializing the call.
callCreationCompletion:(void(^)(CallInitError))
The block that will be called after call initialization (or its failure). The block is passed a CallInitError enum value for checking the init status. See below for details.

The CallInitError Enum

The callCreationCompletion block above is called with one of the following values:

  • CallInitErrorNone - everything went fine
  • CallInitErrorInvalidCode - the callCode value contains invalid characters
  • CallInitErrorMissingClientID - the client ID hasn't been set
  • CallInitErrorNetworkUnreachable - the device is offline
  • CallInitErrorMicrophoneAccessDenied - previously denied access to microphone.

SDK Methods

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

Helpers

+(NSString *)generateRandomCode
Returns a random connection code (room name). Useful for generating a random room name for establishing a call between two or more participants.

SDK Authentication

+(void)authorize:(NSString)token
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

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

  • GruveoCallRecordingLayoutMaximized – maximize the currently active speaker
  • GruveoCallRecordingLayoutTiled – display all participants’ pictures in tiles of approximately the same size.
+(void)toggleRoomLock:(BOOL)enable
Sets the room’s lock state. Pass YES in the enable parameter to lock the room or pass NO to unlock it. This functionality is only available when the call is ongoing.

Call State

+(BOOL)isCallActive
Returns a boolean indicating if there is an ongoing established call.

SDK Events

GruveoCallManager calls the following delegate functions to pass information from the SDK to the app.

-(void)requestToSignApiAuthToken:(NSString *)token
This delegate 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.
-(void)callEstablished
Called once the call between at least 2 participants is established.
-(void)recordingStateChanged
This delegate function is called whenever the call recording state changes, e.g. one of the call participants begins call recording.
-(void)recordingFilename:(NSString *)filename
This delegate function is called 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.
-(void)callEnd:(GruveoCallEndReason)reason
This delegate function is called when the call ends. The reason parameter is used for indicating the reason why the call ended and may have one of the following values:

  • GruveoCallEndReasonBusy - the call room is locked
  • GruveoCallEndReasonHandleBusy - the callee is busy with another call
  • GruveoCallEndReasonHandleUnreachable - the callee is unreachable
  • GruveoCallEndReasonHandleNonExist - the Gruveo handle doesn't exist
  • GruveoCallEndReasonFreeDemoEnded - the 5-minute call limit has been reached (when using the demo client ID)
  • GruveoCallEndReasonRoomLimitReached - the room limit of 12 participants has been reached
  • GruveoCallEndReasonNoConnection - lost connection
  • GruveoCallEndReasonInvalidCredentials - invalid token signature provided
  • GruveoCallEndReasonInternalError - internal error
  • GruveoCallEndReasonOtherParty - the call ended due to the other party hanging up
  • GruveoCallEndReasonUser - the call ended due to the user hanging up.

Revision History

October 8, 2018

  • Added the generateRandomCode helper method to GruveoCallManager.
  • Added a version of the toggleRecording method with the layout parameter.
  • Added the recordingFilename event.

November 6, 2017

  • Added the new GruveoCallEndReasonOtherParty value to the GruveoCallEndReason enum.