RestComm – Client Android SDK Quick Start

This tutorial will show you how to integrate Restcomm Client Android SDK into your Apps to tap into the Restcomm telecom capabilities.

Prerequisites

• Restcomm Communications Platform
• Android Studio

1. Restcomm

Here you have three alternatives:

• Don’t perform a local installation and use the online demo installation at Amazon cloud (please note that this might be down from time to time as it is used for testing)
• Install the Restcomm Docker image locally. Download and install the Restcomm docker image as described at http://www.telestax.com/docker-image-for-mobicents-restcomm-7-3-0/. If you aren’t familiar with docker you can have a quick intro here https://www.docker.com/
• Install Restcomm from GitHub release bundle locally: http://docs.telestax.com/installing-restcomm-from-github/

2. Restcomm Client Android SDK

Once you have installed the  Restcomm platform (or you are using the Demo Amazon instance) you are ready to start taking advantage of Restcomm’s features from your Android Applications. Here’s what you need to do:

• Grab the latest Restcomm Client Android SDK release from GitHub: https://github.com/Mobicents/restcomm-android-sdk/releases. At the time of this writing it is v1.0.0-alpha and the bundle you need to download is restcomm-android-sdk-1.0.0-alpha.tar.bz2
• Extract it:
  

  $ tar -jxvf restcomm-android-sdk-1.0.0-alpha.tar.bz2

Use the existing sample Android App, ‘HelloWorld’

To illustrate the SDK, first we’ll be using one of the sample Apps provided in the bundle, called HelloWorld:

• Open Hello World sample Android Studio project from $ANDROID_SDK/Examples/restcomm-helloworld
• Open MainActivity.java source file within Hello World, search for string ‘CHANGEME’ and perform required changes in the Restcomm instance IP address. This will depend on which alternative you picked above for Restcomm: a. if you used the online demo installation at Amazon then you don’t need to update the IP address (i.e. Amazon instance IP is already used). b. if you used either the Docker image or the GitHub release bundle then you should use the local IP address that Restcomm uses when coming up:
  

  protected void onCreate(Bundle savedInstanceState) 
  {
      ....
      params = new HashMap<String, String>();
      // CHANGEME: update the IP address to your Restcomm instance
      params.put("pref_proxy_ip", "54.225.212.193");
      params.put("pref_proxy_port", "5080");
      params.put("pref_sip_user", "bob");
      params.put("pref_sip_password", "1234");
      // register on startup
      device.updateParams(params);
  }
  
  ...
  
  public void onClick(View view) {
      if (view.getId() == R.id.button_dial) {
          if (connection != null) {
              Log.e(TAG, "Error: already connected");
              return;
          }
      HashMap<String, String> connectParams = new HashMap<String, String>();
      // CHANGEME: update the IP address to your Restcomm instance
      connectParams.put("username", "sip:1235@54.225.212.193:5080");
      connection = device.connect(connectParams, this);
      if (connection == null) {
          Log.e(TAG, "Error: error connecting");
          return;
      }
      ....
  }

• Build and run Hello World (prefer a real device as the simulator tends to be slow on the media processing)
• Once the sample App starts up you can press Dial and behind the scenes number ‘1235’ will be called on the Restcomm instance and you will hear the associated announcement.
• From then on, you can try even more fun experiments, such as calling a different Restcomm number by changing the whole URI in the code from sip:1235@<ip address>:5080 to for example sip:1311@<ip address>:5080 which is the default Restcomm Application for conferencing:
  

  public void onClick(View view) 
  {
      if (view.getId() == R.id.button_dial) {
          if (connection != null) {
              Log.e(TAG, "Error: already connected");
              return;
          }
          HashMap<String, String> connectParams = new HashMap<String, String>();
          // CHANGEME: update the IP address to your Restcomm instance. Also, you can update the number 
          // from '1235' to any Restcomm application you wish to reach
          connectParams.put("username", "sip:1311@54.225.212.193:5080");
          connection = device.connect(connectParams, this);
          if (connection == null) {
              Log.e(TAG, "Error: error connecting");
              return;
          }
      }
      ....
  }

  
  Now the real fun begins: you can call the same number using the Android SDK from yet another Android device and start a conference between the two!

Create a new Android Studio App from scratch

Next, we ‘ll be going in more detail over the steps it takes to come up with an App similar to HelloWorld but starting from scratch to get a good idea what you need to do to incorporate it in an existing Android project:

• Create a new project in Android Studio. File > New > New Project:

  New Android Studio Project

• Pick a project name and a location and press Next.
• Leave the defaults (i.e. Target Android Devices) and hit Next:

  Target Android Devices

• Select ‘Blank Activity’ and hit Next:

  Add an activity

• You can customize your activity if you want in this screen but defaults work fine. When ready hit Finish:

  Customize the Activity

• Now project should be created and you should be automatically navigated to the Android Studio Designer. So remove the existing ‘Hello world!’ TextView and add two buttons, one for Dial and one for Hangup. Apart from the ‘text’ property of the buttons, don’t forget to also update the ‘id’ attributes accordingly so that you know how differentiate between them later in the code:

  Android Studio Designer

• Edit settings.gradle so that the Android SDK Java modules are included in the project but without copying the module projects anew (which is what Android Studio does by default when importing modules). This is how it should look after you update it (remember that here we assume that we are introducing this demo project inside the Examples in the SDK directory tree, if you don’t want to do that then you need to update the ‘project’ setting for both ‘sipua’ and ‘restcomm.android.client.sdk’ modules and set a full path to them):

  Edit settings.gradle

• Edit the ‘app’ module settings and add our SDK as a dependency from View > Open Module Settings:

  Update ‘app’ module settings

• Ok, now that we have all the settings ready the App should be able to build and run but with no actual functionality yet. For that we need to take advantage of the Android SDK. So first you need to import required Android Client packages and make your Activity the listener of Android Client events (such as incoming calls and messages) as well as OnClick events for the buttons:
  

  import org.mobicents.restcomm.android.client.sdk.RCClient;
  import org.mobicents.restcomm.android.client.sdk.RCConnection;
  import org.mobicents.restcomm.android.client.sdk.RCConnectionListener;
  import org.mobicents.restcomm.android.client.sdk.RCDevice;
  import org.mobicents.restcomm.android.client.sdk.RCDeviceListener;
  import org.mobicents.restcomm.android.client.sdk.RCPresenceEvent;
  
  public class MainActivity extends Activity implements RCDeviceListener, RCConnectionListener, OnClickListener {
  ...

• Once you do that you ‘ll have to implement the Android Client listener interface methods with empty stubs so that Java doesn’t complain (notice that for this example we are keeping things simple and not handling incoming events, but you could add that later):
  

  // RCDevice Listeners
      public void onStartListening(RCDevice device)
      {
      }
  
      public void onStopListening(RCDevice device)
      {
      }
  
      public void onStopListening(RCDevice device, int errorCode, String errorText)
      {
      }
  
      public boolean receivePresenceEvents(RCDevice device)
      {
          return false;
      }
  
      public void onPresenceChanged(RCDevice device, RCPresenceEvent presenceEvent)
      {
      }
  
      public void onIncomingConnection(RCDevice device, RCConnection connection)
      {
      }
  
      public void onIncomingMessage(RCDevice device, String message, HashMap<String, String> parameters)
      {
      }
  
      // RCConnection Listeners
      public void onConnecting(RCConnection connection)
      {
      }
  
      public void onConnected(RCConnection connection)
      {
      }
  
      public void onDisconnected(RCConnection connection)
      {
      }
      
      public void onDisconnected(RCConnection connection, int errorCode, String errorText) 
      {
      }
  
      public void onCancelled(RCConnection connection) 
      {
      }
  
      public void onDeclined(RCConnection connection) 
      {
      }

• Add the needed Android Client objects (i.e. RCDevice and RCConnection) in the Activity class as well as some convenience variables:
  

  public class MainActivity extends Activity implements RCDeviceListener, RCConnectionListener, View.OnClickListener {
      private RCDevice device;
      private RCConnection connection, pendingConnection;
      private HashMap<String, String> params;
      private static final String TAG = "MainActivity";
      ....

• In order to make the buttons we created available to the App and also initialise the Android Client you need to update the onCreate() method of your activity as follows:
  

  protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);
  
      // initialize UI
      btnDial = (Button)findViewById(R.id.button_dial);
      btnDial.setOnClickListener(this);
      btnHangup = (Button)findViewById(R.id.button_hangup);
      btnHangup.setOnClickListener(this);
  
      RCClient.initialize(getApplicationContext(), new RCClient.RCInitListener()
      {
          public void onInitialized()
          {
              Log.i(TAG, "RCClient initialized");
  
          }
  
          public void onError(Exception exception)
          {
              Log.e(TAG, "RCClient initialization error");
          }
      });
  
      // TODO: we don't support capability tokens yet so let's use an empty string
      device = RCClient.createDevice("", this);
      Intent intent = new Intent(getApplicationContext(), MainActivity.class);
      device.setIncomingIntent(intent);
  
      connection = null;
  
      params = new HashMap<String, String>();
      // CHANGEME: update the IP address to your Restcomm instance
      params.put("pref_proxy_ip", "54.225.212.193");
      params.put("pref_proxy_port", "5080");
      params.put("pref_sip_user", "bob");
      params.put("pref_sip_password", "1234");
      // register on startup
      device.updateParams(params);
  }

  
  Lines 6-9: retrieve the UI elements for later
  Lines 11-30: initialise the Android Client
  Lines 32-39: setup and update Android Client parameters
• Update the onClick Activity method to respond to button events -this is where the ids come into play that we updated back when we added the buttons in the Designer:
  

  public void onClick(View view) {
          if (view.getId() == R.id.button_dial) {
              if (connection != null) {
                  Log.e(TAG, "Error: already connected");
                  return;
              }
              HashMap<String, String> connectParams = new HashMap<String, String>();
              // CHANGEME: update the IP address to your Restcomm instance. Also, you can update the number
              // from '1235' to any Restcomm application you wish to reach
              connectParams.put("username", "sip:1235@54.225.212.193:5080");
              connection = device.connect(connectParams, this);
              if (connection == null) {
                  Log.e(TAG, "Error: error connecting");
                  return;
              }
              //device.updateParams(params);
          } else if (view.getId() == R.id.button_hangup) {
              if (connection == null) {
                  Log.e(TAG, "Error: not connected");
              }
              else {
                  connection.disconnect();
                  connection = null;
                  pendingConnection = null;
              }
          }
      }

• You are now ready to build and run your project! Press the Play button in Android Studio and wait for the App to load. It should look like this:

  Restcomm Android Demo

• Now press dial and your Appliation will instruct the Android Client to call the configured Restcomm instance and voila, you will hear the announcement!
• Finally, you can press Hang up to terminate the call whenever you like.

That’s it! Give it a try it and share your experience with the rest of the Restcomm community, or even better, jump in and get your hands dirty! Here are some additional resources:

• Roadmap: https://groups.google.com/forum/#!topic/restcomm/d88p771M9yE
• Reference Documentation: http://mobicents.github.io/restcomm-android-sdk/doc/
• Restcomm forum: https://groups.google.com/forum/#!forum/restcomm
• Stack Overflow: http://stackoverflow.com/search?q=restcomm&tab=newest
• You can also try out a more advanced sample Application, Messenger, by directly installing the .apk from Test Fairy: https://community.testfairy.com/join/zr937dgQ

The post RestComm – Client Android SDK Quick Start appeared first on Telestax Docs Online.