This repo contains 3 sample apps that implement the Beacon Android SDK.
- Sample Kotlin - demos Login and Logout with the Beacon UI.
- Sample Customisation - illustrates how you can override the String and Colors of the Beacon UI and shows how to use Beacons in Secure mode.
- Sample Core - shows how you might use the Beacon Core module to load suggested articles and view article details.
- Beacon Core
- Beacon UI
- Change Log
The main SDK documentation is hosted on the Help Scout developers site.
- The minimum supported SDK is 21 (Android 5.0), and your app must be compiled with at least API version 27 (Android 8.1).
- The Beacon SDK only needs Internet permission which is defined in the Core module.
- Help Scout account to obtain your Beacon Id.
The Beacon Android SDK is distributed as AAR and available from JCenter, so simply add the following lines to your app’s build.gradle file.
dependencies {
implementation "com.helpscout:beacon-core:$beaconVersion"
implementation "com.helpscout:beacon-ui:$beaconVersion"
}Once you sync the Gradle project you'll be ready to initialize Beacon.
After following the steps above, your app is set up for integrating with the Beacon SDK. Before you can continue any further, you'll need to get hold of the ID of the Beacon that you'd like to integrate with.
You can find your Beacon ID by logging into Help Scout and navigating to the Beacon you'd like to use. Inside the Installation section you'll see an Android tab which highlights the Beacon ID and a code snippet.
Once you've located the Beacon ID, you are ready to initialise the library. If you will only display one Beacon, the Application.onCreate() method of your Application class
class is a great place to initialize the SDK. If you won't know the Beacon ID at Application start, or will be running multiple Beacons, you'll need to make sure of adding
the following call to the Beacon.Builder() before you launch BeaconActivity.
Beacon beacon = new Beacon.Builder()
.withBeaconId("76d18b11-41f4-4d34-9a8c-08679d4759e3")
.build();Beacon ID field is mandatory. Failing to provide it will throw an SDKInitException
when an interaction with the Beacon object is done.
Once you’ve initialized Beacon, you’re ready to interact with it. Whenever you want to invoke Beacon, use the code below to display the Beacon user interface.
BeaconActivity.open(context);There are three main components that construct the Beacon SDK that are split over two modules.
-
beacon-core
- Beacon Builder -
Beacon.Builder() - Public Data Layer -
BeaconRepository
- Beacon Builder -
-
beacon-ui
- Easiest way to integrate Beacon features into your app
It's possible to launch the Beacon SDK in developer mode. By doing so, you'll be able to read the HTTP requests and other actions that happen with the SDK realm.
In order to activate this mode, you have to tell the Beacon Builder like so:
Beacon beacon = Beacon.Builder()
.withBeaconId("cf2102b5-0f3c-4214-972e-2a1d33c7fadb")
.withLogsEnabled(true)
.build();Once this is done, head over to LogCat.
If all you are looking to do is to expose the knowledge database of articles, the Public API mode is your best bet.
We have provided you with a Repository (you can read more about this pattern here. You'll only need to include the core dependency.
The only requirement is to have created a Beacon with the Beacon.Builder as described above.
BeaconRepository repository = Beacon.getRepositoryInstance()This Repository allows you to fetch a few collections:
- Fetch all articles article by id:
List<BeaconArticle> articles = repository.getArticles() - Fetch an article by id:
BeaconArticle article = repository.getArticleById(articleId) - Search for an article:
List<BeaconArticle> articles = repository.searchArticles(query)
All the calls made to the BeaconRepository are synchronous. Meaning that you'll have to provide a threading
mechanism. Instead of being opinionated about it, we prefer to give you the option to use whatever mechanism works
best for you.
The sample-core project shows how to build your own User Interface