Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Beacon Android SDK Samples

This repository contains two sample apps that showcase how to integrate the Beacon Android SDK.

  • Sample Kotlin - A simple and concise demo that shows how to install, initialise, and two different ways to open your Help Scout Beacon.
  • Sample Customisation - Java based sample illustrates some of the key features you can use to customise the Beacon SDK to add additional data about the user and how to override certain Beacon settings.

Beacon SDK version Maven Central

Release notes and changelog

You can subscribe to receive release updates by following these steps:

  1. At the top right-hand corner, click on "Watch"
  2. Choose "Custom"
  3. Check the "Releases" option


  • minSdkVersion: 21
  • compileSdkVersion:31
  • Java 11 language feature support
  • Android X as of version SDK 2.0.0
  • A Beacon Id created on Help Scout

Supported platform and language versions

  • Android 11.0 to 13.0 (as noted above the "minSdkVersion: 21 (Android 5.0)" for greater compatiblity however we only offer support for issues on Android 11.0 to 13.0)
  • Kotlin 1.6
  • Java 11
  • Koin 3.2.0


The Beacon Android SDK is distributed as AAR and available from Maven Central, so add the following lines to your app's build.gradle file.


repositories {

dependencies {
  implementation 'com.helpscout:beacon:<beaconVersion>'

Kotlin DSL

repositories {

dependencies {

Once you sync the Gradle project, you'll be ready to initialize Beacon.

Initialize Beacon

After following the steps above, your app is ready to integrate with the Beacon SDK. Before you can continue any further, you'll need to get a hold of the ID of the Beacon that you'd like to use.

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 that highlights the Beacon ID and a code snippet.

Once you've located the Beacon ID, you are ready to initialize the library. If you 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 run 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()

Beacon ID field is mandatory. Failing to provide it throws an SDKInitException when interacting with the Beacon object.

Opening Beacon

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.;

Developer options

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.

To activate this mode, you have to tell the Beacon Builder like so:

Beacon beacon = Beacon.Builder()

To verify, take a peek in your Logcat.



For issues or questions, contact Help Scout support at