Bit6 for Android

GitHub version

Developer Guide sections: Intro & Auth, WebRTC Calling, IP Messaging, UI Components

Additional resources: API Reference, Code Samples

Getting Started

Prerequisites

Add Bit6 SDK

Add Bit6 SDK Maven repository in your project build.gradle file

allprojects {
    repositories {
        jcenter()
            maven { url "https://raw.githubusercontent.com/bit6/bit6-android-sdk/master/releases/" }
    }
}

Add Bit6 SDK dependency in your module build.gradle. Bit6 UI Library is an optional module with common UI components for handling incoming and ongoing calls, message lists etc.

dependencies {
    // Required Bit6 SDK module
    compile "com.bit6.sdk:bit6-sdk:0.9.8"
    // Optional Bit6 UI components
    // compile "com.bit6.ui:bit6-ui:0.9.8"
}

If you add dependency for Bit6-UI library then no need to add Bit6-SDK, SDK is already in UI.

Application Class

import com.bit6.sdk.Bit6;
import com.bit6.sdk.LifecycleHelper;

public class App extends Application {
    // Override onCreate method to init the SDK
    public void onCreate() {
        super.onCreate();
        // Initialize Bit6 SDK
        Bit6 bit6 = Bit6.getInstance();
        bit6.init(getApplicationContext(), "MY_API_KEY");
        // Bit6 will be notified about lifecycle events for app activities
        registerActivityLifecycleCallbacks(new LifecycleHelper(bit6));
    }
}

Manifest.xml

Assuming your.package.name is the package name for your application, you need to do the following:

Permissions

Specify the required permissions:

<!-- Internet access - Allows applications to connect to the network -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Incoming call handling - Allows to keep the phone from sleeping or screen from dimming -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- Incoming call handling - Access to the vibration effects -->
<uses-permission android:name="android.permission.VIBRATE" />
<!-- Voice/Video calling - Allows an application to record audio -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<!-- Voice/Video calling - Allows an application to modify global audio settings -->
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<!-- Voice/Video calling, photo/video messages - To access camera services -->
<uses-permission android:name="android.permission.CAMERA" />
<!-- Photo/Video messages - Allows an application to write to external storage. -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!-- Location messages - To access location services -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- GCM push notifications -->
<permission
    android:name="your.package.name.permission.C2D_MESSAGE"
    android:protectionLevel="signature" />

<uses-permission android:name="your.package.name.permission.C2D_MESSAGE" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

Application

Modify <application> element:

<application>
  <!-- Required for applications which use Google Play Services. -->
  <meta-data
      android:name="com.google.android.gms.version"
      android:value="@integer/google_play_services_version" />

  <!-- Bit6 Content Provider -->
  <provider
      android:name="com.bit6.sdk.db.Bit6ContentProvider"
      android:authorities="your.package.name"
      android:exported="false" />

  <!-- Bit6 receives GCM push notifications -->
  <receiver
      android:name="com.bit6.sdk.push.GcmBroadcastReceiver"
      android:permission="com.google.android.c2dm.permission.SEND" >
      <intent-filter>
          <action android:name="com.google.android.c2dm.intent.RECEIVE" />
          <category android:name="your.package.name" />
      </intent-filter>
  </receiver>

  <!-- Bit6 handles GCM push notifications -->
  <service android:name="com.bit6.sdk.push.PushIntentService" />

  <!-- Your custom receiver for incoming calls -->
  <receiver android:name=".IncomingCallReceiver" android:enabled="true">
      <intent-filter>
          <action android:name="your.package.name.BIT6_INCOMING_CALL" />
      </intent-filter>
  </receiver>

  <!-- Your custom receiver for incoming messages -->
  <receiver android:name=".IncomingMessageReceiver" android:enabled="true">
      <intent-filter>
          <action android:name="your.package.name.BIT6_INCOMING_MESSAGE" />
      </intent-filter>
  </receiver>

</application>

(Optional) ADM Push Notifications

To support push notifications on Amazon devices you need to modify Manifest.xml

Add xmlns:amazon="http://schemas.amazon.com/apk/res/android" into <manifest> element.

Specify the required permissions:

<!-- ADM Push Messaging -->
<permission
    android:name="your.package.name.permission.RECEIVE_ADM_MESSAGE"
    android:protectionLevel="signature" />

<uses-permission android:name="your.package.name.permission.RECEIVE_ADM_MESSAGE" />
<uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />

Modify <application> element:

<!-- ADM push support -->
<service
    android:name="com.bit6.sdk.push.AdmMessageHandler"
    android:exported="false" />
<amazon:enable-feature android:name="com.amazon.device.messaging"
    android:required="false" />

<!-- Bit6 receives ADM push notifications -->
<receiver android:name="com.bit6.sdk.push.AdmMessageHandler$Receiver"
    android:permission="com.amazon.device.messaging.permission.SEND">
    <intent-filter>
        <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
        <action android:name="com.amazon.device.messaging.intent.RECEIVE" />
        <category android:name="your.package.name" />
    </intent-filter>
</receiver>

Authentication

Each user in the system has one or more identities - user id, username, email, facebook id, google account, phone number etc. Identities are required for user authentication, managing contacts, identifying user's network. An identity is represented by a URI.

Bit6 supports various authentication mechanisms described in the following sections.

The session capabilities are accessed via SessionClient.

SessionClient sessionClient = bit6.getSessionClient();

Check if the user is authenticated:

if (sessionClient.isAuthenticated()) {
    Log.v(TAG, "Authenticated")
} else {
    Log.v(TAG, "Not Authenticated ")
}

Logout:

sessionClient.logout();

Managed

Username

A username is case-insensitive and must consist of alphanumeric characters, e.g. usr:john or usr:test123.

Create a new user account with a username identity and a password:

Address identity = Address.fromParts(Address.KIND_USERNAME, "john");

sessionClient.signup(identity, pass, new ResultHandler() {
    @Override
    public void onResult(boolean success, String msg) {
        if (success) {
            Log.v(TAG, "success " + msg);
        } else {
            Log.v(TAG, "error " + msg);
        }
    }
});

Login into an existing account using an Identity and a password.

Address identity = Address.fromParts(Address.KIND_USERNAME, "john");

sessionClient.login(identity, pass, new ResultHandler() {
    @Override
    public void onResult(boolean success, String msg) {
        if (success) {
            Log.v(TAG, "success " + msg);
        } else {
            Log.v(TAG, "error " + msg);
        }
    }
});

Anonymous

Authenticate as an anonymous user:

sessionClient.anonymous(resultHandler);

Third-Party

Bit6 integrates with various OAuth1 and OAuth2 providers for simplified user authentication. Check the sample apps for details. As an example, we will describe Facebook authentication process.

Sign in with Facebook

Step 1. Create a Facebook App. Copy its App ID and Secret into Bit6 Dashboard.

Step 2. Follow all the instructions described in Facebook Login documentation.

Step 3. Change the callback function for the loginButton to the following:

// Callback registration
loginButton.registerCallback(callbackManager, new FacebookCallback<LoginResult>() {
    @Override
    public void onSuccess(LoginResult loginResult) {
        // OAuth2 access token
        AccessToken token = loginResult.getAccessToken();
        // Send the token to Bit6
        bit6.getSessionClient().oauth("facebook", token.getToken(), new ResultHandler() {
            @Override
            public void onResult(boolean success, String msg) {
                if (success) {
                    Log.v(TAG, "success " + msg);
                } else {
                    Log.v(TAG, "error " + msg);
                }
            }
        });
    }

    @Override
    public void onCancel() {}

    @Override
    public void onError(FacebookException exception) {}
});

Delegated

You can start a session using external authentication using your own app server or a backend-as-a-service provider.

Here's a code sample for Parse.com client-side integration.

final Map<String, String> map = new HashMap<>();
ParseCloud.callFunctionInBackground("bit6_auth", map, new FunctionCallback<String>() {
    @Override
    public void done(String s, ParseException e) {
        SessionClient sessionClient = bit6.getSessionClient();
        sessionClient.external(s, new ResultHandler() {
            @Override
            public void onResult(boolean success, String msg) {

            }
        });
    }
});