Package com.zello.sdk

Class Zello

java.lang.Object
com.zello.sdk.Zello
public class Zello extends Object

The Zello singleton acts as the primary point of interacting to the Zello SDK.

To get an instance of the object call getInstance(). Before using this class, call the configure(Context) or configure(String, Context) method. For specific usage, see the sample projects.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    beginMessage()
    Starts sending a voice message to the currently selected user or channel.
    void
    cancelSignIn()
    Cancels the currently running sign in process.
    void
    configure(android.content.Context context)
    Configures the Zello SDK.
    void
    configure(String packageName, android.content.Context context)
    Configures the Zello SDK.
    void
    configure(String packageName, android.content.Context context, Events event)
    Configures the Zello SDK and subscribes for Zello SDK Events.
    void
    connectChannel(String channel)
    Connects the user to a channel.
    void
    disconnectChannel(String channel)
    Disconnects the user from a channel.
    void
    endMessage()
    Stops sending a voice message.
    void
    enterPowerSavingMode()
    Limits communication between the Zello Work app and the server to optimize power and data consumption.
    void
    getAppState(AppState state)
    Gets info about the current application state.
    Audio
    getAudio()
    Gets an instance of the Audio class that is used to control Zello audio settings.
    Contacts
    getContacts()
    Gets the list of users and channels in the contact list of the current user.
    static Zello
    getInstance()
    Gets the instance of Zello singleton object.
    void
    getMessageIn(MessageIn message)
    Gets info about the current active incoming voice message.
    void
    getMessageOut(MessageOut message)
    Gets info about the current active outgoing voice message.
    void
    getSelectedContact(Contact contact)
    Gets info about the currently selected contact.
    boolean
    isLastMessageReplayAvailable()
    Determines if there is a message available to replay.
    void
    leavePowerSavingMode()
    Resumes full communication between the Zello Work app and the server.
    void
    lock(String applicationName, String packageName)
    Locks the default Zello Work app UI to prevent users from accessing it.
    void
    muteContact(Contact contact, boolean mute)
    Mutes or unmutes a contact.
    void
    openMainScreen()
    Opens the main screen of the Zello Work app.
    void
    replayLastIncomingMessage()
    Replays the last played voice message.
    void
    requestLocationPermission()
    Opens a dialog that requests the location permission needed by the Zello Work app to function properly.
    void
    requestLocationPermission(android.app.Activity activity)
    Opens a dialog that requests the location permission needed by the Zello Work app to function properly.
    void
    requestVitalPermissions()
    Opens a dialog that requests all of the vital run time permissions needed by the Zello Work app to function properly.
    void
    requestVitalPermissions(android.app.Activity activity)
    Opens a dialog that requests all of the vital run time permissions needed by the Zello Work app to function properly.
    void
    selectContact(String title, Tab[] tabs, Tab activeTab, Theme theme)
    Opens an activity, which lets the user select a user or channel to talk to.
    void
    selectContact(String title, Tab[] tabs, Tab activeTab, Theme theme, android.app.Activity activity)
    Opens an activity, which lets the user select a user or channel to talk to, from another activity.
    void
    setAutoConnectChannels(boolean connect)
    Specifies whether newly added channels should connect automatically.
    void
    setAutoRun(boolean enable)
    Specifies whether the Zello Work app should be launched on the start of the OS.
    void
    setExternalId(String id)
    Sets an optional external id tag used by Zello Work Server Recording.
    void
    setHeadsetActive(boolean active)
    Tell the host app that it doesn't need to handle the headset hook events.
    void
    setSelectedChannelOrGroup(String name)
    Selects a contact (channel or group) to send messages to.
    void
    setSelectedContact(Contact contact)
    Selects a contact (user or channel) to send messages to.
    void
    setSelectedUserOrGateway(String name)
    Selects a contact (user or gateway) to send messages to.
    void
    setShowBluetoothAccessoriesNotifications(boolean show)
    Asks the host app to suppress UI notifications when Bluetooth PTT buttons connect or disconnect.
    void
    setStatus(Status status)
    Sets the current user's availability status.
    void
    setStatusMessage(String message)
    Sets the current user's custom status message text.
    void
    showMicrophonePermissionDialog()
    Opens a popup dialog that tells the user that they cannot send voice messages until the permission to record audio has been granted.
    void
    showMicrophonePermissionDialog(android.app.Activity activity)
    Opens a popup dialog that tells the user that they cannot send voice messages until the permission to record audio has been granted.
    void
    showPttButtonsScreen(android.app.Activity activity)
    Opens the PTT buttons settings screen.
    boolean
    signIn(String network, String username, String password)
    Signs the user into the network with the passed in login credentials.
    boolean
    signIn(String network, String username, String password, boolean perishable)
    Signs is the user into the network with the passed in login credentials.
    void
    signOut()
    Signs out currently signed in user.
    void
    subscribeToEvents(Events event)
    Subscribes for Zello SDK Events.
    void
    unconfigure()
    Disconnects the SDK from Zello Work app and unsubscribes all Events handlers.
    void
    unlock()
    Unlocks the default Zello Work app UI.
    void
    unsubscribeFromEvents(Events event)
    Unsubscribes from Zello SDK Events.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • getInstance

      @NonNull public static Zello getInstance()
      Gets the instance of Zello singleton object.
      Returns:
      Zello singleton instance.

    • configure

      public void configure(@Nullable android.content.Context context)
      Configures the Zello SDK.

      You must call configure(String, Context) or configure(String, Context, Events) before using any other SDK methods. In most cases, the Application.onCreate() method is the best place to do this.

      This method will chose the name of a package to connect to automatically.

      Parameters:
      context - The context for the app.
      See Also:

    • configure

      public void configure(@Nullable String packageName, @Nullable android.content.Context context)
      Configures the Zello SDK.

      You must call configure(String, Context) or configure(String, Context, Events) before using any other SDK methods. In most cases, the Application.onCreate() method is the best place to do this.

      If the APK was downloaded from zellowork.com, packageName should be "net.loudtalks". If the APK was downloaded from Android Client SDK on GitHub, packageName should be "com.pttsdk". If the APK was downloaded from Google Play, packageName should be "com.loudtalks". To have a the package name chosen automatically, pass in a null packageName.

      Parameters:
      packageName - The package name of the Zello Work app.
      context - The context for the app.
      See Also:

    • configure

      public void configure(@Nullable String packageName, @Nullable android.content.Context context, @Nullable Events event)
      Configures the Zello SDK and subscribes for Zello SDK Events.

      You must call configure(String, Context) or configure(String, Context, Events) before using any other SDK methods. In most cases, the Application.onCreate() method is the best place to do this.

      If the APK was downloaded from zellowork.com, packageName should be "net.loudtalks". If you are using a standalone version of the apk use "com.pttsdk".

      Parameters:
      packageName - The package name of the Zello Work app.
      context - The context for the app.
      event - Events handler
      See Also:

    • enterPowerSavingMode

      public void enterPowerSavingMode()
      Limits communication between the Zello Work app and the server to optimize power and data consumption.

      Call this method when the Zello UI is not visible to minimize app power and data use. When in power saving mode, the app won't receive non-essential status updates. Call leavePowerSavingMode to resume status updates when the Zello UI is back on the screen.

      See Also:

    • leavePowerSavingMode

      public void leavePowerSavingMode()
      Resumes full communication between the Zello Work app and the server.
      See Also:

    • unconfigure

      public void unconfigure()
      Disconnects the SDK from Zello Work app and unsubscribes all Events handlers.
      See Also:

    • subscribeToEvents

      public void subscribeToEvents(@NonNull Events event)
      Subscribes for Zello SDK Events.
      Parameters:
      event - Events handler.
      See Also:

    • unsubscribeFromEvents

      public void unsubscribeFromEvents(@NonNull Events event)
      Unsubscribes from Zello SDK Events.
      Parameters:
      event - Events handler.
      See Also:

    • requestVitalPermissions

      public void requestVitalPermissions()
      Opens a dialog that requests all of the vital run time permissions needed by the Zello Work app to function properly.

      This method is only necessary for Android devices running 6.0 (API 23) and above. This method requests run time permissions for the microphone, phone, and external storage.

      If these permissions have already been granted, this method has no effect. In addition, if the device is running Android 5.1 (API 22) or less, this method has no effect.

      Use this method when you don't have an activity on the screen (ex. from a service).

      See Also:

    • requestVitalPermissions

      public void requestVitalPermissions(@Nullable android.app.Activity activity)
      Opens a dialog that requests all of the vital run time permissions needed by the Zello Work app to function properly.

      This method is only necessary for Android devices running 6.0 (API 23) and above. This method requests run time permissions for the microphone, phone, and external storage.

      If these permissions have already been granted, this method has no effect. In addition, if the device is running Android 5.1 (API 22) or less, this method has no effect.

      Use this method to open the permissions UI from an existing activity.

      Parameters:
      activity - Caller activity.
      See Also:

    • requestLocationPermission

      public void requestLocationPermission()
      Opens a dialog that requests the location permission needed by the Zello Work app to function properly.

      This method is only necessary for Android devices running 6.0 (API 23) and above. This method requests run time permissions for the microphone, phone, and external storage.

      If these permissions have already been granted, this method has no effect. In addition, if the device is running Android 5.1 (API 22) or less, this method has no effect.

      Use this method when you don't have an activity on the screen (ex. from a service).

      See Also:

    • requestLocationPermission

      public void requestLocationPermission(@Nullable android.app.Activity activity)
      Opens a dialog that requests the location permission needed by the Zello Work app to function properly.

      This method is only necessary for Android devices running 6.0 (API 23) and above. This method requests run time permissions for the microphone, phone, and external storage.

      If these permissions have already been granted, this method has no effect. In addition, if the device is running Android 5.1 (API 22) or less, this method has no effect.

      Use this method to open the permissions UI from an existing activity.

      Parameters:
      activity - Caller activity.
      See Also:

    • showMicrophonePermissionDialog

      public void showMicrophonePermissionDialog()
      Opens a popup dialog that tells the user that they cannot send voice messages until the permission to record audio has been granted.

      This method is only necessary for Android devices running 6.0 (API 23) and above.

      The most appropriate place to call this method is when onMicrophonePermissionNotGranted() is called on the Events interface.

      If the microphone permission has already been granted, this method has no effect. In addition, if the device is running Android 5.1 (API 22) or less, this method has no effect.

      Use this method when you don't have an activity on the screen (ex. from a service).

      See Also:

    • showMicrophonePermissionDialog

      public void showMicrophonePermissionDialog(@Nullable android.app.Activity activity)
      Opens a popup dialog that tells the user that they cannot send voice messages until the permission to record audio has been granted.

      This method is only necessary for Android devices running 6.0 (API 23) and above.

      The most appropriate place to call this method is when onMicrophonePermissionNotGranted() is called on the Events interface.

      If the microphone permission has already been granted, this method has no effect. In addition, if the device is running Android 5.1 (API 22) or less, this method has no effect.

      Use this method to open the permissions UI from an existing activity.

      Parameters:
      activity - Caller activity.
      See Also:

    • selectContact

      public void selectContact(@Nullable String title, @Nullable Tab[] tabs, @Nullable Tab activeTab, @Nullable Theme theme)
      Opens an activity, which lets the user select a user or channel to talk to.

      The Zello SDK provides a built-in UI for contact selection that is available when the user is signed in. You can customize the title of the activity (leave null for default), the tabs available, initial tab, and specify a dark or light theme.

      Use this method when you don't have an activity on the screen (ex. from a service).

      Parameters:
      title - Activity title. Can be null.
      tabs - Set of displayed tabs.
      activeTab - Initially active tab.
      theme - Visual theme for activity.
      See Also:

    • selectContact

      public void selectContact(@Nullable String title, @Nullable Tab[] tabs, @Nullable Tab activeTab, @Nullable Theme theme, @Nullable android.app.Activity activity)
      Opens an activity, which lets the user select a user or channel to talk to, from another activity.

      The Zello SDK provides a built-in UI for contact selection that is available when the user is signed in. You can customize the title of the activity (leave null for default), the tabs available, initial tab, and specify a dark or light theme.

      Use this method to open a contact selection UI from an existing activity.

      Parameters:
      title - Activity title. Can be null.
      tabs - Set of displayed tabs.
      activeTab - Initially active tab.
      theme - Visual theme for activity.
      activity - Caller activity.
      See Also:

    • beginMessage

      public void beginMessage()
      Starts sending a voice message to the currently selected user or channel.

      This method is asynchronous. When the message status changes, onMessageStateChanged() is called on the Events interface.

      If the microphone permission is not granted, onMicrophonePermissionNotGranted() is called on the Events interface.

      See Also:

    • endMessage

      public void endMessage()
      Stops sending a voice message.

      This method has no effect if there is no active outgoing message.

      This method is asynchronous. When the message status changes, onMessageStateChanged() is called on the Events interface.

      See Also:

    • replayLastIncomingMessage

      public void replayLastIncomingMessage()
      Replays the last played voice message.

      There is no expiration for messages that can be played using this method. The last played message is only changed by overriding it with a new message, signing out or deleting the contact that sent the message.

      This method has no effect if there was no last played voice message or if there is an active outgoing message.

      This method is asynchronous. When the message status changes, onMessageStateChanged() is called on the Events interface.

      See Also:

    • isLastMessageReplayAvailable

      public boolean isLastMessageReplayAvailable()
      Determines if there is a message available to replay.

      Use this method to determine whether or not your UI should display a button to replay the last incoming message. There are two events that may trigger a change in the last message availability: Events.onMessageStateChanged() when a live incoming voice message is received or when the contact that sent the last incoming message is deleted. Events.onAppStateChanged() when the user signs out.

      Returns:
      boolean indicating whether there is a message to replay.
      See Also:

    • connectChannel

      public void connectChannel(@Nullable String channel)
      Connects the user to a channel.

      This method is asynchronous. When the channel is connected, onContactsChanged() is called on the Events interface.

      Parameters:
      channel - The name of the channel to connect to.
      See Also:

    • disconnectChannel

      public void disconnectChannel(@Nullable String channel)
      Disconnects the user from a channel.

      This method is asynchronous. When the channel is disconnected, onContactsChanged() is called on the Events interface.

      Parameters:
      channel - The name of the channel to disconnect from.
      See Also:

    • muteContact

      public void muteContact(@Nullable Contact contact, boolean mute)
      Mutes or unmutes a contact.
      Parameters:
      contact - The contact to mute or unmute.
      mute - Whether the contact should be muted or not.

    • signIn

      public boolean signIn(@Nullable String network, @Nullable String username, @Nullable String password)
      Signs the user into the network with the passed in login credentials.

      See signIn(String, String, String, Boolean) for more details.

      Parameters:
      network - The network name or URL.
      username - The username to authenticate.
      password - The password for the username.
      Returns:
      Indicates whether a sign in was initiated or not.
      See Also:

    • signIn

      public boolean signIn(@Nullable String network, @Nullable String username, @Nullable String password, boolean perishable)
      Signs is the user into the network with the passed in login credentials.

      When connecting to an account hosted at zellowork.com, you can use the network name for network. When connecting to a standalone server, use the full server domain name or IP.

      The standard sign in behavior is to save login credentials so that the next time the app is started it signs in automatically. Set perishable to true to sign in without saving login credentials.

      This method is asynchronous. When sign in fails or succeeds, onAppStateChanged() is called on the Events interface.

      To cancel the sign in process, use the cancelSignIn() method.

      Parameters:
      network - The network name or URL.
      username - The username to authenticate.
      password - The password for the username.
      perishable - Whether or not the authentication information should be saved.
      Returns:
      boolean indicating whether a sign in was initiated or not.
      See Also:

    • signOut

      public void signOut()
      Signs out currently signed in user.

      This method does not remove saved user credentials.

      This method is asynchronous. When the sign out succeeds, onAppStateChanged() is called on the Events interface.

      See Also:

    • cancelSignIn

      public void cancelSignIn()
      Cancels the currently running sign in process.

      This method won't have an effect if the user is already signed in.

      See Also:

    • lock

      public void lock(@Nullable String applicationName, @Nullable String packageName)
      Locks the default Zello Work app UI to prevent users from accessing it.

      In this locked state, the Zello Work app, when accessed by user, only displays an information screen with the name of your app that can be clicked to open the main activity. This does NOT interfere with the sending and receiving of messages through the SDK.

      This method is useful when you implement a fully custom UI in your app and want to prevent users from accidentally accessing the standard Zello Work UI.

      Parameters:
      applicationName - The name of your application.
      packageName - The package name of your application.
      See Also:

    • unlock

      public void unlock()
      Unlocks the default Zello Work app UI.
      See Also:

    • setStatus

      public void setStatus(@NonNull Status status)
      Sets the current user's availability status.
      Parameters:
      status - The status to set.
      See Also:

    • setStatusMessage

      public void setStatusMessage(@Nullable String message)
      Sets the current user's custom status message text.
      Parameters:
      message - The custom message text to display in user's status.
      See Also:

    • openMainScreen

      public void openMainScreen()
      Opens the main screen of the Zello Work app.

    • showPttButtonsScreen

      public void showPttButtonsScreen(@Nullable android.app.Activity activity)
      Opens the PTT buttons settings screen.
      Parameters:
      activity - Nullable, Caller activity.

    • getMessageIn

      public void getMessageIn(@Nullable MessageIn message)
      Gets info about the current active incoming voice message.

      This method updates the provided instance of the MessageIn object with the current data. The object does not update automatically, so call this method every time you need to get the current info about an active incoming voice message.

      Parameters:
      message - The object to copy data to.
      See Also:

    • getMessageOut

      public void getMessageOut(@Nullable MessageOut message)
      Gets info about the current active outgoing voice message.

      This method updates the provided instance of the MessageOut object with the current data. The object does not update automatically, so call this method every time you need to get the current info about an active outgoing voice message.

      Parameters:
      message - The object to copy data to.
      See Also:

    • getAppState

      public void getAppState(@Nullable AppState state)
      Gets info about the current application state.

      This method updates the provided instance of the AppState object with the current data. The object does not update automatically, so call this method every time you need to get the current info about Zello Work app and Zello SDK state.

      Parameters:
      state - The object to copy data to.
      See Also:

    • getSelectedContact

      public void getSelectedContact(@Nullable Contact contact)
      Gets info about the currently selected contact.

      This method updates the provided instance of the Contact object with the current data. The object does not update automatically, so call this method every time you need to get the info about currently selected contact.

      Parameters:
      contact - The object to copy data to.
      See Also:

    • getContacts

      @Nullable public Contacts getContacts()
      Gets the list of users and channels in the contact list of the current user.

      The returned list includes users, channels and their statuses. It does not update automatically, so use this method to get a fresh copy of the list when needed.

      When the list is updated in any way, onContactsChanged() is called on the Events interface. Possible reasons for the contact list being updated include changes of online status of users, channels connecting and disconnecting and modifications made to the contact list through web console or API.

      Returns:
      The contact list for the currently signed in user.
      See Also:

    • getAudio

      @Nullable public Audio getAudio()
      Gets an instance of the Audio class that is used to control Zello audio settings.
      Returns:
      The audio instance.
      See Also:

    • setAutoRun

      public void setAutoRun(boolean enable)
      Specifies whether the Zello Work app should be launched on the start of the OS.

      Configured autorun behavior persists between app launches.

      Parameters:
      enable - The boolean to enable this feature or not. By default, this value is true.
      See Also:

    • setAutoConnectChannels

      public void setAutoConnectChannels(boolean connect)
      Specifies whether newly added channels should connect automatically.

      Zello remembers whether the channel was connected by the user. The default behavior when user signs in for the first time or added to a new channel via web console or the API is to connect to that channel. Set connect to false to prevent this behavior. Call this method before signIn to make sure no channels are connected automatically on first sign in.

      This method doesn't affect the channels previously connected or disconnected by the user or the Zello SDK.

      Parameters:
      connect - Enables autoconnect.
      See Also:

    • setExternalId

      public void setExternalId(@Nullable String id)
      Sets an optional external id tag used by Zello Work Server Recording.

      When set, the provided id is included in the metadata of all messages sent by Zello and can be accessed using the Zello Work server API to query recordings metadata.

      This method has no effect unless the Zello Work Server Recording feature is turned on for the current network.

      Parameters:
      id - Nullable; String indicating the external id.
      See Also:

    • setSelectedContact

      public void setSelectedContact(@Nullable Contact contact)
      Selects a contact (user or channel) to send messages to.

      Use a Contact object from the list returned by Zello.getContacts() method as an argument.

      Parameters:
      contact - Nullable; a contact to select. A null value deselects the current contact.
      See Also:

    • setSelectedUserOrGateway

      public void setSelectedUserOrGateway(@Nullable String name)
      Selects a contact (user or gateway) to send messages to.

      Use a Contact object from the list returned by Zello.getContacts() method as an argument.

      Parameters:
      name - Nullable; The name of the user or gateway to select. A null value deselects the current contact.
      See Also:

    • setSelectedChannelOrGroup

      public void setSelectedChannelOrGroup(@Nullable String name)
      Selects a contact (channel or group) to send messages to.

      Use a Contact object from the list returned by Zello.getContacts() method as an argument.

      Parameters:
      name - Nullable; The name of the channel or group or contact to select. A null value deselects the current contact.
      See Also:

    • setShowBluetoothAccessoriesNotifications

      public void setShowBluetoothAccessoriesNotifications(boolean show)
      Asks the host app to suppress UI notifications when Bluetooth PTT buttons connect or disconnect.

      When set, the application will not show popup notifications every time a button connects or disconnects.

      Parameters:
      show - Show Bluetooth PTT buttons' related notifications.

    • setHeadsetActive

      public void setHeadsetActive(boolean active)
      Tell the host app that it doesn't need to handle the headset hook events.

      When set, makes the host function as if the headset PTT button did not exist.

      Parameters:
      active - True when the headset object is handling the events