An Android library that allows Connect partners to integrate issue creation, notification, and chat in a single button.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.idea
dist
examples/microconnect-sample-plainview
gradle/wrapper
library
.gitignore
.gitmodules
LICENSE
README.md
build.gradle
gradle.properties
gradlew
gradlew.bat
proguard-rules.pro
settings.gradle

README.md

Boomtown microConnect for Android (v.1.2.0)

Minimum Requirements

  • Android 4.4 (API Level 19)
  • Android Studio, v2.3.0 or higher recommended
  • Gradle 3 or higher recommended

Overview

microConnect-android contains Android libraries for Connect partners:

  1. BTConnectHelp, Allows partners to integrate issue creation, notification, and chat in a single BTConnectHelpButton button.
  2. BTConnectPresenceService, Allows partners to integrate with onsite intelligence agents.

Getting Started

  1. Clone this repository and include as a library project in your Android project.
  2. In Android Studio, open File -> New -> Import Module
  3. Choose the "Source Directory" by browsing to the file path/location of this clone'd repo.
  4. The module name "microConnect-android" should be auto-filled once you choose this library's file path.
  5. Click Finish.

or -

  1. Download the AAR file from github.
  2. From within Android Studio, open File -> New -> New Module
  3. Choose Import .JAR/.AAR Package, click Next
  4. Enter the filename with full path - use "..." to browse to the file location where you downloaded microConnect-android-release-1.2.0.aar
  5. The "Subproject name" should be auto-filled to "microConnect-android-release-1.2.0" once you choose this AAR file path.
  6. Click Finish

API Key Generation

  1. Log onto the Admin Portal (https://admin.goboomtown.com)
  2. Click "Orgs" in the left menu
  3. Find your organization in the list
  4. Double-click your org. to show the "Edit Partner" panel
  5. Click "API Settings" near the button of the panel
  6. Select Sandbox or Live, depending on the state of development
  7. Click "Re-Generate"
  8. Copy the access token and private-key, as provided in the pop-up dialog

Obtaining Member Information

For chat to work, microConnect-android requires you specify the member and user information of the person using your app. This information can be obtained as follows:

  1. Log onto the Admin Portal (https://admin.goboomtown.com)
  2. Click Orgs in the left menu
  3. Find and double-click your organization to show the Edit Partner window
  4. Click Customers along the top of the Edit Partner window
  5. Find and double-click the appropriate member from the list to show the Edit Customer window
  6. The Id field of the Member Info section contains the value to use for BTConnectHelpButton#membersId
  7. Click Locations along the top of the Edit Customer window
  8. Find and double-click the appropriate location for the user of your app to show the Edit Customer Location window
  9. The Id field of the Location Information section contains the value to use for BTConnectHelpButton#membersLocationId
  10. Click Discard & Close in the lower right to return to the Edit Customer window
  11. Click Users along the top of the Edit Customer window
  12. Find and double-click the user of your app to show the Edit Customer User window
  13. The Id field of the Customer User Info section contains the value to use for BTConnectHelpButton#membersUsersId

BTConnectHelp

Appearance

A BTConnectHelpButton can be added to your app using an XML layout file or programmatically, as shown in this screenshot from one of the included example apps.

![screenshot example initial view]a screenshot of initial view provided by this component

Tapping the BTConnectHelpButton will take your user to the Help view.

![screenshot help view]a screenshot of the help view provided by this component

From the Help view, the user may tap the buttons for chat, web, e-mail, or phone support. If the user taps "Chat With Us," an issue will be created for him/her, and he/she will be taken to a chat room associated with that issue.

![screenshot chat view]a screenshot of the chat view provided by this component

Usage

Note: An example Android application that uses this library may be found in the Example/BoomtownSample folder of this repository.

Sample XML Layout

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       xmlns:app="http://schemas.android.com/apk/res-auto"
       android:paddingBottom="@dimen/activity_vertical_margin"
       android:paddingLeft="@dimen/activity_horizontal_margin"
       android:paddingRight="@dimen/activity_horizontal_margin"
       android:paddingTop="@dimen/activity_vertical_margin"
       tools:context="com.goboomtown.boomtowntest.MainActivity">
   
       <com.goboomtown.microconnect.btconnecthelp.view.BTConnectHelpButton
           android:id="@+id/helpButton"
           android:layout_width="300dp"
           android:layout_height="300dp"
           android:layout_centerVertical="true"
           android:layout_centerHorizontal="true"
           android:background="@android:color/transparent"
           android:padding="20dp"
           app:exampleColor="#33b5e5"
           app:exampleDimension="24sp"
           app:exampleString="" />
   
       <FrameLayout
           xmlns:android="http://schemas.android.com/apk/res/android"
           xmlns:app="http://schemas.android.com/apk/res-auto"
           android:id="@+id/fragment_container"
           android:layout_width="match_parent"
           android:layout_height="match_parent"
           android:visibility="gone" />
   
   </RelativeLayout>

Sample Java code

mHelpButton         = (BTConnectHelpButton) findViewById(R.id.helpButton);
mFragmentContainer  = (FrameLayout)         findViewById(R.id.fragment_container);

mHelpButton.setListener(this);

mHelpButton.memberID 			= "WA3QMJ";
mHelpButton.memberUserID 		= "WA3QMJ-5XK"; //@"WA3QMJ-2QE";
mHelpButton.memberLocationID 	= "WA3QMJ-FYH"; //@"WA3QMJ-JVE";

mHelpButton.supportWebsiteURL 	= Uri.parse("http://example.com");
mHelpButton.supportEmailAddress  = "support@example.com";
mHelpButton.supportPhoneNumber 	= "1-888-555-2368";

mHelpButton.setCredentials("31211E2CC0A30F98ABBD","0a46f159dc5a846d3fa7cf7024adb2248a8bc8ed");

Connect! Intelligent Agent (mDNS) Broadcasts Using BTConnectHelpButton

The BTConnectHelpButton provides a convenient way to connect to Boomtown onsite intelligence agents. This provides a mechanism for broadcasting mDNS data. This can be done with a call to BTConnectHelpButton#advertiseServiceWithPublicData(Map, Map) method.

Map<String, String> myPubData = new HashMap<String, String>();
myPubData.put("public", "fooData");
Map<String, String> myPrivData = new HashMap<String, String>();
myPrivData.put("private", "someEncryptedData");

mHelpButton.advertiseServiceWithPublicData(myPubData, myPrivData);

The lifecycle of advertiseServiceWithPublicData() will be managed by the BTConnectHelpButton class. To manage the lifecycle yourself you can invoke BTConnectHelpButton#stopAdvertiseServiceWithPublicData().

Two methods in BTConnectHelpButtonListener provide for insight into the broadcast of mDNS data:

  1. BTConnectHelpButtonListener#helpButtonDidAdvertiseService()
  2. BTConnectHelpButtonListener#helpButtonDidFailToAdvertiseService()

BTConnectPresenceService

This library provides a service class for connecting to Boomtown onsite intelligence agents. There are no visible parts of this library, as it all works in the background, but you can build visual elements that interact with the service. This is another way to use the mDNS broadcast functionality in this library is through the exposed BTConnectPresenceService.

Usage

BTConnectPresenceService is a (singleton) class with public methods for starting and stopping its service. It provides a DNS-SD broadcast service. You will need a Boomtown API Key (described above) to use this library component.

The BTConnectPresenceService service can broadcast custom data as desired by the user by using the BTConnectPresenceService#addCustomPayloadData(String,String) methosd. This custom payload data is encrypted by default, using a SHA256HMAC-encryption algorithm with the API secret as the salt. Custom payload data can also be sent unencrypted with the BTConnectPresenceService#addCustomPayloadData(String, String, false) method.

One important aspect of using BTConnectPresenceService is to manage its lifecycle as you manage your application's lifecycle (onCreate/onResume/onPause/onStop/etc). Examples are provided in this library.

Note: An example Android application that uses the BTConnectPresenceService may be found in the Example/BoomtownSample folder of this repository.

Sample Java code

protected void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	setContentView(R.layout.activity_main);
        mBTPresenceSvc = com.goboomtown.btconnecthelp.service.BTConnectPresenceService.getInstance(this,
                new BTConnectPresenceService.ServiceAdvertisementListener() {
            public void didAdvertiseService() {
                Log.i(TAG, "service advertised successfully");
            }

            public void didFailToAdvertiseService() {
                Log.i(TAG, "error when advertising service");
            }
        });
}

@Override
protected void onResume() {
	super.onResume();
	mBTPresenceSvc.addCustomPayloadData("test", "public-data", false);
	mBTPresenceSvc.addCustomPayloadData("private", "private-encrypted-data");
	mBTPresenceSvc.start();
}

@Override
protected void onPause() {
	super.onPause();
	mBTPresenceSvc.tearDown();
	Log.v(TAG, "onPause complete");
}

Building Library from Sources

The steps to build this library from source are:

  1. Verify a working Gradle v3+ installation.
  2. git clone [this-project]
  3. cd /[this-project]
  4. Issue the following command
gradle build -x javadoc -x lint

Acknowledgements

microConnect-android uses Smack (http://www.igniterealtime.org/projects/smack/), and we are grateful for the contributions of the open source community.