Beacon for Android

For issues or questions, contact Help Scout support at help@helpscout.com.

Requirements

Please view the requirements for the Android Beacon SDK here on Github.

Supported versions

We make every effort to ensure the Beacon SDK is compatible with the latest, non-beta versions of Android, Kotlin, Java, and other third-party dependencies. However, sometimes breaking changes are introduced outside of our control, and in these cases, you may wish to delay updating to the latest version of those libraries to ensure compatibility.

If you find a compatibility problem, please contact Help Scout support at help@helpscout.com

View the currently supported versions on the sample GitHub repository.

ProGuard

The Beacon Android SDK ships with ProGuard rules therefore no specific rules are needed.

Useful links

SDK reference - generated Javadocs for all public classes/methods
Changelog – get a list of recent changes to the Beacon SDK

Sample application

We’ve created an open-source sample repository with several sample apps that you can reference during your implementation. We hope it’s helpful!

Installation

Maven Central

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

dependencies {
  implementation "com.helpscout:beacon:<beaconVersion>"
}

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

Download

You can download the .aar files from our repository on Maven Central or the releases section of the Sample repository.

Usage

Initialize Beacon

You can find setup code and your Beacon ID in the web Beacon builder by clicking “Installation” on the left sidebar, then navigating to “Android” in the options displayed at the top.

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 is a great place to initialize the SDK. If you won’t know the Beacon ID at Application start or running multiple Beacons, you’ll need to make sure to add the following call to the Beacon.Builder() before you launch BeaconActivity.

Beacon beacon = new Beacon.Builder()
  .withBeaconId("YOUR_BEACON_ID_HERE")       
  .build();

Beacon ID field is mandatory. Failing to provide it will throw an SDKInitException when an interaction with the Beacon object is done.

We use a Provider to to handle the initialization of the SDK with Application Context. You can disable Auto Init by adding the following meta-data tag to your manifest

<meta-data android:name="com.helpscout.beacon.SDKAutoInitialise" android:value="false" />

However if Auto Init is disabled, you need to pass a context to Beacon.Builder.withContext() to manually init the Beacon.

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

BeaconActivity.open(context);

There isn’t an explicit method for closing the Beacon; instead, the user closes it when they tap the close button or navigate away using the back button.

Developer options

It’s possible to launch the Beacon SDK in developer mode. By doing so, you’ll be able to track the actions that happen inside the SDK.

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

 Beacon beacon = Beacon.Builder()
   .withBeaconId("YOUR_BEACON_ID_HERE")       
   .withLogsEnabled(true)       
   .build();

Once this is done, head over to LogCat.

Authenticating users

You can provide the name and email address to pre-populate and hide the fields on the ‘Create a message’ screen.

Normal mode

Normal mode authentication requires a user’s email address as the user identifier.

Beacon.identify("user@domain.com");

Alternatively, you can also identify the user’s name.

Beacon.identify("user@domain.com", "John Doe");

Or add some more extra attributes such as company name, job title and a url to use as the customer’s avatar.

Beacon.identify(
    "user@domain.com",
    "John Doe",
    "Company Name",
    "Job title",
    "https://valid-url-to-avatar-image"
);

Character limits for identify parameters:

Name: 80 characters maximum
Company: 60 characters maximum
Job Title: 60 characters maximum
Avatar URL: 200 characters maximum

Note: If any parameter exceeds these limits, the value will not be saved.

Secure mode

If you provide a valid signature, you can use it to authenticate a user in Secure Mode and retrieve their previous conversations.

To retrieve previous conversations in Secure Mode, you must:

Identify the user with their email and name using Beacon.identify()
Open Beacon with the signature using BeaconActivity.openInSecureMode()

For security reasons, you’ll need to pass in the signature every time you want to open the Beacon UI.

Note: You should not store the secret key in the app. Instead, your server should provide the computed signature value.

// First, identify the user
Beacon.identify("user@domain.com", "John Doe");

// Then open Beacon in secure mode with the signature
BeaconActivity.openInSecureMode(context, "8235545a15c6f41b64e3c47e5c94d3...");

Logout

Calling this method clears the current user’s session and identity data. This is the method you should call when a user logs out of your app, but you want to continue using the same Beacon instance.

What gets cleared:

User identity and attributes

What is preserved:

Beacon ID
Configuration and overrides
Prefilled forms and article suggestions

  Beacon.logout();

By default, any active chat for the user will remain active after logout. To end the active chat upon logout, use the overloaded method:

  Beacon.logout(true); // Ends any active chat

Note: Push notifications will continue to work after logout. The SDK maintains device registration across user sessions, allowing new users to receive notifications immediately after identification without requiring device re-registration.

Use logout() when switching between different users in your app while keeping the same Beacon configuration active.

Clear

This method performs a complete reset of the Beacon SDK, clearing all persisted data and state. After calling this method, you must re-initialize Beacon with a Beacon ID before using it again.

What gets cleared:

Beacon ID
All user data and session information
Configuration and overrides
Prefilled forms and article suggestions
Commands queue

  Beacon.clear();

Note: Push notifications will continue to work after clear(). The SDK maintains device registration across Beacon instances, ensuring push notifications work immediately after re-initialization without requiring additional setup.

Use clear() when you need to completely remove the Beacon instance, such as switching to a different Beacon ID in different parts of your app, or when implementing a complete teardown/reinstallation of the Beacon feature.

User attributes

For Help Scout plans with access to Customer Properties, you can pass custom attributes that will be synced to the customer’s record and visible in the Customer Properties sidebar app.

Attribute keys should exactly match Customer Property IDs, which are case-sensitive and can include letters, numbers, hyphens, and underscores, but no other special characters. name and email are reserved attribute keys. Attribute values should be of type String.

Limits:

You may add up to 30 different attributes
Attribute keys have a maximum length of 100 characters
Attribute values have a maximum length of 255 characters

The addAttributeWithKey method returns true if the attribute was added successfully, or false if the attribute limit has been reached.

You may add an attribute like so:

  boolean added = Beacon.addAttributeWithKey("Subscription", "Free Plan");
  if (!added) {
      // Attribute limit reached (30 attributes maximum)
  }

You may also remove specific attributes, or clear the entire set.

  Beacon.removeAttribute("a-key"); // Remove one attribute
  Beacon.clearAttributes(); // Clear all attributes

Session attributes

This method allows you to add session-specific information to a new message or chat. Unlike the Beacon.addAttributeWithKey(..) method above, use Beacon.setSessionAttributes(..) to pass data into the Beacon visitor activity note that’s only relevant to a specific conversation or chat. We do not sync this data to either the customer profile or the Customer Properties app.

You can add up to 20 attribute-value pairs. Each attribute label can contain up to 100 characters, and each value can contain up to 10,000 characters.

The setSessionAttributes method returns true if the attributes were set successfully, or false if more than 20 attributes were provided.

Map<String, String> sessionAttributes = new HashMap<>();
sessionAttributes.put("Key", "Value");
boolean added = Beacon.setSessionAttributes(sessionAttributes);
if (!added) {
    // More than 20 attributes provided
}

Prefilling the contact form

Use the PreFilledForm object to pre-populate the “Create a message” contact form data. You can fill any of the fields: name, subject, the body of the message, custom fields, attachment URIs, and email. Unlike when using Secure Mode, the name and email fields remain visible and editable.

Attachments:

A maximum of three attachments is permitted
Each attachment must not exceed 10 MB in size

For how to determine the ids for custom field population, see this documentation for the Beacon web component.

 Beacon.addPreFilledForm(
    new PreFilledForm(
        "Steve Aoki", //name
        "Need help with invoice", //subject,
        "steve@aoki.com", // email
        "Hello, I need some help with my invoice. See attached PDF...", //message
        Collections.singletonMap(5678, "Question"), //custom field values
        Collections.singletonList("content://media/path/to/invoice"), // list of string URIs
    )
);

Resetting the contact form

Reset the contact form by clearing all of its fields, custom fields, and attachments.

If your Beacon is in Normal Mode, calling contactFormReset() clears all contact form fields, including name and email address.

If your Beacon is in Secure Mode, calling contactFormReset() does not clear the customer’s name or email address, those inputs remain hidden.

Please note that if a customer has been identified using the identify() method, then their name and email address won’t be cleared with this method, you’ll have to use logout for this purpose.

 Beacon.contactFormReset();

Navigate to a specific screen

The default behavior for Beacon is to open the Home screen. If you want to open another screen, you can do it by calling one of the BeaconActivity.open() methods.

Opening with search results

Open the search screen and with the search results for the string “search term”

ArrayList<String> searchList = new ArrayList<String>();
searchList.add("search term");
BeaconActivity.open(this, BeaconScreens.SEARCH_SCREEN, searchList);

Opening to an article

You can use this method to open a specific Docs article within Beacon, using the article’s ID.

Article IDs are found in Help Scout by navigating to the article and copying the article ID from the URL. The URL is structured like this: https://secure.helpscout.net/docs/[COLLECTION ID]/article/[ARTICLE ID]/.

 ArrayList<String> articleList = new ArrayList<String>();
 articleList.add("12345abcd");
 BeaconActivity.open(this, BeaconScreens.ARTICLE_SCREEN, articleList);

Opening to the contact form

Open to the contact form screen. Note: Requires the Beacon to have messaging enabled.

BeaconActivity.open(this, BeaconScreens.CONTACT_FORM_SCREEN, new ArrayList<String>());

Opening to previous messages

Open directly to the previous messages screen. Note: Requires the Beacon to have messaging enabled. If the user does not have previous messages, the page is empty with “Sorry, no previous messages” error message.

BeaconActivity.open(this, BeaconScreens.PREVIOUS_MESSAGES, new ArrayList<String>());

Opening to chat

Open direct to realtime chat. Note: Requires the Beacon to have chat enabled; if it is not enabled, this method will fallback to opening the contact form.

BeaconActivity.open(this, BeaconScreens.CHAT, new ArrayList<String>());

Opening to ask

Open to the Ask chooser tab. Note: Requires the Beacon to have docs and messaging enabled.

BeaconActivity.open(this, BeaconScreens.ASK, new ArrayList<String>());

Opening to answers

Open directly to the docs/articles list. This bypasses the Home screen and takes the user straight to browsing available articles. Note: Requires the Beacon to have docs enabled.

BeaconActivity.open(this, BeaconScreens.ANSWERS, new ArrayList<String>());

Opening to AI Answers

Open the AI Answers screen, allowing the user to enter their own question. Note: Requires AI Answers to be enabled.

BeaconActivity.open(this, BeaconScreens.AI_ANSWERS, new ArrayList<String>());

Opening to AI Answers with a question

Open the AI Answers screen with a specific question automatically sent to AI Answers. The question is immediately submitted without requiring user interaction. Note: Requires AI Answers to be enabled.

ArrayList<String> questionList = new ArrayList<String>();
questionList.add("How do I reset my password?");
BeaconActivity.open(this, BeaconScreens.ASK_QUESTION, questionList);

Custom suggestions

You can programmatically override and change the suggestions based on any criteria that you specify. You can suggest articles by specifying their IDs or by passing an article title and an URL.

// There is a limit of 10 suggestions. If the list is larger than 10, additional suggestions will be ignored.
List<SuggestedArticle> suggestedArticles = new ArrayList();
suggestedArticles.add(new SuggestedArticle.SuggestedArticleWithId("ARTICLE_ID"));
suggestedArticles.add(new SuggestedArticle.SuggestedArticleWithUrl("ARTICLE_TITLE", "ARTICLE_URL"));
Beacon.setOverrideSuggestedArticlesOrLinks(suggestedArticles);

Custom suggestions only get loaded when displaying the Beacon. If the Beacon is not present, loading the custom suggestion data queues it up for the next Beacon display.

If you’d like to revert to the default suggestion list from the Beacon Builder, call resetSuggestedArticlesOverrides():

Beacon.resetSuggestedArticlesOverrides();

Note: The older method setOverrideSuggestedArticles(List<String> articleIds) has been deprecated since v7.0.0. Please use setOverrideSuggestedArticlesOrLinks(List<SuggestedArticle> suggestions) instead, which supports both articles and external links.

Open and close events

These methods allow you to listen to specific events in the lifecycle of the Beacon to perform custom actions. Right now we support ‘open’ and ‘close’ events.

To use it, please register the BeaconEventLifecycleHandler listener in your Application class. Example:

private void initBeaconListener() {
    BeaconEventLifecycleHandler eventLifecycleHandler = new BeaconEventLifecycleHandler(
        new BeaconOnOpenedListener() {
            @Override
            public void onOpened() {
                Timber.i("Open Beacon event called");
            }
        },
        new BeaconOnClosedListener() {
            @Override
            public void onClosed() {
                Timber.i("Close Beacon event called");
            }
        }
    );

    registerActivityLifecycleCallbacks(eventLifecycleHandler);
}

To unregister from events, use the following example:

private void unregisterFromBeaconEvents() {
    unregisterActivityLifecycleCallbacks(eventLifecycleHandler);
}

Settings customization

You can override various settings from the Beacon Builder configuration using the Beacon.setConfigOverrides(configOverrides) method.

General options

Name	Type	Options	Description
messagingEnabled	Boolean	`true` or `false`	Enable or disable the contact form. It must be enabled in the Beacon settings for you to enable it via this API.
docsEnabled	Boolean	`true` or `false`	Enable or disable the article/docs. It must be enabled in the Beacon settings for you to enable it via this API.
chatEnabled	Boolean	`true` or `false`	Enable or disable the realtime chat. It must be enabled in the Beacon settings for you to enable it via this API.
color	String	`"#617DEC"`	Beacon primary color in hex format.
focusMode	Enum	`SELF_SERVICE`, `NEUTRAL`, `ASK_FIRST`	If your Beacon has Docs and Messaging (email or chat) enabled, the mode controls the user experience of the Beacon. Learn more.
enablePreviousMessages	Boolean	`true` or `false`	Enable or disable Previous Messages in Beacon. Defaults to true.

Contact form options

These are set by setting the BeaconContactForm object on the BeaconConfigOverrides

Name	Type	Options	Description
customFieldsEnabled	Boolean	`true` or `false`	Enable or disable Custom Fields.
showName	Boolean	`true` or `false`	Display an editable Name field.
showSubject	Boolean	`true` or `false`	Display an editable Subject field.
allowAttachments	Boolean	`true` or `false`	Display the add Attachments button.

Show pre-filled custom fields

It is possible to hide custom fields that you’ve pre-filled using the Beacon.showPrefilledCustomFields(false). By default, pre-filled custom fields are shown just like the other pre-filled fields.

Translation strings

You have two ways to customize Beacon text:

Beacon Builder - Configure default text in the web Beacon builder (single language only)
Android string resources - Override strings in your app’s resources (recommended for multi-language support)

We lean on the Android resources system to provide overrides for strings defined in the Beacon Builder. Android string resources always take precedence over the Beacon Builder string values. You can find a list of the overridable string keys in the tables below. Just define a string resource with the same key, and we’ll use that in preference over the Beacon Builder string value.

This allows for full localization support. For example, within your res/values-es folder you could create a strings.xml file and include the following to offer Spanish localization:

<!-- res/values-es/strings.xml -->
<string name="hs_beacon_suggested_for_you">Sugerido para ti</string>
<string name="hs_beacon_search">Buscar</string>
<string name="hs_beacon_send_a_message_title">Enviar un mensaje</string>

You can similarly create resource files for other languages (e.g., res/values-fr/strings.xml for French, res/values-de/strings.xml for German).

Available string resources

Below is the complete list of string resource IDs and default values organized by category.

Answers

String resource Id	Default value
hs_beacon_suggested_for_you	"Instant Answers"
hs_beacon_get_in_touch	"Get in touch"
hs_beacon_search	"What can we help you with?"
hs_beacon_try_again	"Try again"
hs_beacon_default_message_error	"There was a problem sending your message. Please try again in a moment."
hs_beacon_beacon_button_close	"Close"
hs_beacon_beacon_button_chat_minimize	"Minimise chat"
hs_beacon_beacon_button_chat_open	"Open chat"

Ask

String resource Id	Default value
hs_beacon_answer	"Answers"
hs_beacon_ask	"Ask"
hs_beacon_message_button	"Email"
hs_beacon_no_time_to_wait	"No time to wait around? We usually respond within a few hours"
hs_beacon_chat_button	"Chat"
hs_beacon_chat_button_description	"We’re online right now, talk with our team in real-time"
hs_beacon_were_here_to_help	"Start a conversation"
hs_beacon_what_method_works	"What channel do you prefer?"
hs_beacon_previous_messages	"Previous Conversations"

Search Results

String resource Id	Default value
hs_beacon_cant_find_any_articles	"Can’t find an answer?"
hs_beacon_related_articles	"Related Articles"
hs_beacon_nothing_found	"Hmm…"
hs_beacon_docs_search_empty	"We couldn’t find any articles that match your search."
hs_beacon_try_broader_term	"Try searching a broader term, or"
hs_beacon_docs_article_error	"There was a problem retrieving this article. Please double-check your internet connection and try again."
hs_beacon_docs_search_error	"There was a problem retrieving articles. Please double-check your internet connection and try again."
hs_beacon_escalation_question_feedback	"Did this answer your question?"
hs_beacon_escalation_question_feedback_no	"No"
hs_beacon_escalation_question_feedback_yes	"Yes"
hs_beacon_escalation_search_text	"Browse our help docs for an answer to your question"
hs_beacon_escalation_search_title	"Keep searching"
hs_beacon_escalation_talk_text	"Talk with a friendly member of our support team"
hs_beacon_escalation_talk_title	"Talk to us"
hs_beacon_escalation_thanks_feedback	"Thanks for the feedback"
hs_beacon_escalation_what_next	"What next?"

Send A Message

String resource Id	Beautified default value
hs_beacon_send_a_message_title	"Send a message"
hs_beacon_first_a_few_questions	"Let’s begin with a few questions"
hs_beacon_what_help_with	"How can we help?"
hs_beacon_response_time	"We usually respond in a few hours"
hs_beacon_history	"History"
hs_beacon_upload_image	"Upload an image"
hs_beacon_add_attachment	"Attach a file"
hs_beacon_continue_writing	"Continue writing…"
hs_beacon_last_updated	"Last updated"
hs_beacon_you	"You"
hs_beacon_name	"Name"
hs_beacon_subject	"Subject"
hs_beacon_email_address	"Email address"
hs_beacon_message	"How can we help?"
hs_beacon_send	"Send a message"
hs_beacon_next	"Next"
hs_beacon_we_are_on_it	"We’re on it!"
hs_beacon_message_confirmation	"You’ll receive an email reply within a few hours."
hs_beacon_view_and_update	"You can view and update your message in"
hs_beacon_error_field_required	"May not be empty"
hs_beacon_custom_fields_validation	"Please complete all fields"
hs_beacon_email_not_valid	"Please use a valid email address"
hs_beacon_attachment_error	"There was a problem uploading your attachment. Please try again in a moment."
hs_beacon_attachment_size_error	"Attachments may be no larger than 10MB"

Previous Messages

String resource Id	Default value
hs_beacon_reply	"Add a reply"
hs_beacon_add_your_message_here	"Add your message here..."
hs_beacon_send_message	"Send message"
hs_beacon_received	"Received"
hs_beacon_waiting_answer	"Waiting for an answer"
hs_beacon_previous_message_error	"There was a problem retrieving this message. Please double-check your Internet connection and try again."
hs_beacon_just_now	"Just Now"

Chat

String resource Id	Default value
hs_beacon_chat_heading	"Chat with our team"
hs_beacon_chat_sub_label	"We’ll be with you soon"
hs_beacon_chat_end_callout_heading	"All done!"
hs_beacon_chat_end_callout_message	"A copy of this conversation will land in your inbox shortly."
hs_beacon_chat_end_callout_link	"Return home"
hs_beacon_chat_end_unassigned_heading	"Sorry about that"
hs_beacon_chat_end_unassigned_message	"It looks like nobody made it to your chat. We’ll send you an email response as soon as possible."
hs_beacon_chat_end_waiting_heading	"Sorry about that"
hs_beacon_chat_end_waiting_message	"Your question has been added to our email queue and we’ll get back to you shortly."
hs_beacon_ending	"Ending..."
hs_beacon_chat_end	"End chat"
hs_beacon_chat_ended	" ended the chat"
hs_beacon_chat_connected	"Connected to "
hs_beacon_chatbot_name	"Help Bot"
hs_beacon_chatbot_greet	"Hi there! You can begin by asking your question below. Someone will be with you shortly."
hs_beacon_chatbot_prompt_email	"Got it. Real quick, what’s your email address? We’ll use it for any follow-up messages."
hs_beacon_chatbot_confirmation	"Thanks! Someone from our team will jump into the chat soon."
hs_beacon_chatbot_generic_error	"Something went wrong sending your message, please try again in a few minutes."
hs_beacon_chatbot_inactivity_prompt	"Since the chat has gone idle, I’ll end this chat in a few minutes."
hs_beacon_chatbot_invalid_email	"Looks like you’ve entered an invalid email address. Want to try again?"
hs_beacon_chatbot_agent_disconnected	" has disconnected from the chat. It’s possible they lost their internet connection, so I’m looking for someone else to take over. Sorry for the delay!"
hs_beacon_chat_availability_change	"Our team’s availability has changed and there’s no longer anyone available to chat. Send us a message instead and we’ll get back to you."

Transcript Email

String resource Id	Default value
hs_beacon_email_heading	"Today’s chat with "
hs_beacon_email_greeting	"Hey "
hs_beacon_email_copy_of_discussion	"Here’s a copy of your discussion"
hs_beacon_email_continue_conversation	"If you’ve got any other questions, feel free to hit reply and continue the conversation."
hs_beacon_email_joined	" joined the chat"
hs_beacon_email_ended	" ended the chat"
hs_beacon_email_you	"You"

AI Answers

String resource Id	Default value
hs_beacon_welcome_message	"Hello, I can find answers from the help center. How can I help?"

Note: Some AI Answers strings are controlled server-side and may not be overridable.

Android-Specific Strings

These strings are specific to the Android platform and have default values defined in the SDK. They are not configured in the Beacon Builder.

Network Error View

String resource Id	Default
hs_beacon_network_error_title	"Unable to Connect"
hs_beacon_network_error_message	"Please check your connection and\ntry again."
hs_beacon_network_error_retry_button	"Try Again"
hs_beacon_network_error_close_button	"Close"

Push Notifications

String resource Id	Default
hs_beacon_notification_channel_id	"Beacon"
hs_beacon_chat_notification_channel_id	"Beacon chat"
hs_beacon_chat_notification_channel_name	"Beacon chat notifications"
hs_beacon_chat_ended_title	"Chat ended"
hs_beacon_chat_notification_agent_replied_default_title	"New chat message"
hs_beacon_chat_notification_inactivity_title	"Chat has gone idle"
hs_beacon_conversation_notification_default_title	"New message"

Push notifications

Note: There is no admin UI in Help Scout currently where you can manage your Firebase Cloud Messaging (FCM) details. If you would like to try out this feature, you can email your FCM service account JSON and your App ID to help@helpscout.com, and we’ll set it up manually for you.

If you don’t have an FCM service account JSON, you can follow these steps:

Go to Firebase Console.
Select your project, and click the gear icon on the top of the sidebar.
Head to project settings.
Navigate to the service account tab.
Click Generate New Private Key, then confirm by clicking Generate Key.
Clicking Generate Key downloads the JSON file – ensure that you persist this file somewhere safe, you won’t be able to download it again.

The push notification support allows your users to receive push notifications when a support agent replies to one of their messages (sent from the Beacon SDK) or an in-progress, realtime chat.

Agent conversation replies - tapping the notification opens Beacon and takes the user to the conversation.
Agent chat replies - tapping the notification opens Beacon and takes the user to the chat.

Android 13+ notify runtime permissions

Android 13 (API level 33) added a new restriction where users must consent via a runtime permission to show system notifications like those noted above. Beacon SDK does not handle this runtime permission request therefore please follow the steps outlined by Android developer to define and request the android.permission.POST_NOTIFICATIONS. If your app is running on Android 13 an device and targeting Android 13 if this permission is not requested or allowed the Beacon SDK notifications will not be shown.

Setup

Follow Set Up a Firebase Cloud Messaging Client App on Android, making sure to add the required FCM dependencies. In either case, you’ll need to send us the device’s push token, which tells the Beacon SDK to register for push notifications on future messages and replies sent from the SDK.

 Beacon.setFirebaseCloudMessagingToken(context, newToken);

For receiving the push messages, there are two paths to take here, depending on whether your application uses FCM already or not.

Your application is already enabled for FCM

In your custom extension of the FirebaseMessagingService class you’ll already be overriding the onNewToken() method. Just add a call to Beacon.setFirebaseCloudMessagingToken() to send us the token.

@Override
public void onNewToken(String deviceToken) {
    super.onNewToken(deviceToken);
    if (deviceToken != null) {
      // Send Beacon the token
      Beacon.setFirebaseCloudMessagingToken(this, deviceToken);
    }
}

Once completed, Beacon can send push notifications to your application. To differentiate between Beacon push notifications and any other push notifications your app might receive, we’ve added a utility method.

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    if (remoteMessage.getData().size() > 0) {
      BeaconPushNotificationsProcessor beaconPushNotificationsProcessor = new BeaconPushNotificationsProcessor();
        if (BeaconPushNotificationsProcessor.isBeaconNotification(remoteMessage.getData())) {
            beaconPushNotificationsProcessor.process(this, remoteMessage.getData());
        } else {
            // Here can process your own push messages                
        }
    }
}

Your application isn’t currently using FCM

We’ll automatically receive the push message and display a system notification. We just need the device push token.

FirebaseInstanceId.getInstance()
    .getInstanceId()
    .addOnSuccessListener(
        new OnSuccessListener<InstanceIdResult>() {
           @Override
           public void onSuccess(InstanceIdResult instanceIdResult) {
               String deviceToken = instanceIdResult.getToken();

               // Send Beacon the token
               Beacon.setFirebaseCloudMessagingToken(context, deviceToken);
           }
       }
    );

If, in the future, you want to enable your own push messaging with FCM, please follow the instructions above.

Customizing Beacon notifications

Apps targeting Android Oreo (SDK 26) or higher have push notifications delivered to a notification channel. If you wish to override the channel settings for Beacon notifications, set the following resources to the values of your choice:

   <string name="hs_beacon_notification_channel_id">your_channel_id</string>
   <string name="hs_beacon_notification_channel_name">Your channel name</string>

If you wish, you can also change the icon that is shown in the status bar when receiving a notification. Just provide your own drawable called hs_beacon_ic_notification and it’ll override the default icon.

Migration Guide (v7.0.0)

Starting with version 7.0.0, the Android Beacon SDK includes several improvements and updated features. This introduces some breaking changes that require updates to your integration.

Breaking Changes

1. Removal of `login()` Methods

The deprecated login() methods have been removed after being deprecated since version 2.0.0 (2020). Use the identify() methods instead.

Before (v6.0.1 and earlier):

// These methods are no longer available
Beacon.login("user@domain.com");
Beacon.login("user@domain.com", "John Doe");

After (v7.0.0):

// Use identify() instead
Beacon.identify("user@domain.com");
Beacon.identify("user@domain.com", "John Doe");

Migration: Replace all Beacon.login() calls with Beacon.identify(). The method signatures are identical, so this is a straightforward find-and-replace operation.

2. Push Notification Token Registration

The setFirebaseCloudMessagingToken method now requires a Context parameter.

Before (v6.0.1 and earlier):

String token = "your-fcm-token";
Beacon.setFirebaseCloudMessagingToken(token);

After (v7.0.0):

String token = "your-fcm-token";
Beacon.setFirebaseCloudMessagingToken(context, token);

Migration: Add your application context as the first parameter when calling this method.

3. Article Suggestion Limit

The maximum number of article suggestions has increased from 5 to 10.

Before (v6.0.1 and earlier):

// Maximum 5 suggestions
List<SuggestedArticle> suggestions = new ArrayList();
// Add up to 5 articles...

After (v7.0.0):

// Maximum 10 suggestions
List<SuggestedArticle> suggestions = new ArrayList();
// Add up to 10 articles...

Migration: You can now provide up to 10 article suggestions instead of 5.

Deprecations

`setOverrideSuggestedArticles()` Deprecated

The setOverrideSuggestedArticles(List<String> articleIds) method has been deprecated in favor of setOverrideSuggestedArticlesOrLinks(List<SuggestedArticle>), which supports both articles and external links.

Before:

List<String> articleIds = new ArrayList();
articleIds.add("ARTICLE_ID");
Beacon.setOverrideSuggestedArticles(articleIds);

After:

List<SuggestedArticle> suggestions = new ArrayList();
suggestions.add(new SuggestedArticle.SuggestedArticleWithId("ARTICLE_ID"));
Beacon.setOverrideSuggestedArticlesOrLinks(suggestions);

Migration: Replace setOverrideSuggestedArticles() with setOverrideSuggestedArticlesOrLinks(). The new method provides more flexibility by supporting both article IDs and custom URLs.

What Stays the Same

The following APIs remain unchanged and require no migration:

✅ Beacon.Builder() - Initialization
✅ Beacon.identify() - User identification
✅ Beacon.logout() - Clearing user data
✅ BeaconActivity.open() - Opening Beacon
✅ BeaconActivity.openInSecureMode() - Secure mode
✅ Beacon.addAttributeWithKey() - User attributes
✅ Beacon.setSessionAttributes() - Session attributes
✅ Beacon.addPreFilledForm() - Prefilling forms
✅ All BeaconScreens navigation options
✅ Push notification handling

Testing Your Migration

After updating to v7.0.0:

Test push notifications - Verify that FCM token registration works with the new signature
Review UI text - Check that all customized strings appear correctly
Test all features - Verify that user identification, messaging, chat, and docs all work as expected

Need Help?

If you encounter issues during migration, please contact Help Scout support at help@helpscout.com.

Help Scout Developers

Requirements

Supported versions

ProGuard

Useful links

Sample application

Installation

Maven Central

Download

Usage

Initialize Beacon

Open Beacon

Developer options

Authenticating users

Normal mode

Secure mode

Logout

Clear

User attributes

Session attributes

Prefilling the contact form

Resetting the contact form

Navigate to a specific screen

Opening with search results

Opening to an article

Opening to the contact form

Opening to previous messages

Opening to chat

Opening to ask

Opening to answers

Opening to AI Answers

Opening to AI Answers with a question

Custom suggestions

Open and close events

Settings customization

General options

Contact form options

Show pre-filled custom fields

Translation strings

Available string resources

Answers

Ask

Search Results

Send A Message

Previous Messages

Chat

Transcript Email

AI Answers

Android-Specific Strings

Network Error View

Push Notifications

Push notifications

Android 13+ notify runtime permissions

Setup

Your application is already enabled for FCM

Your application isn’t currently using FCM

Customizing Beacon notifications

Migration Guide (v7.0.0)

Breaking Changes

1. Removal of login() Methods

2. Push Notification Token Registration

3. Article Suggestion Limit

Deprecations

setOverrideSuggestedArticles() Deprecated

What Stays the Same

Testing Your Migration

Need Help?

1. Removal of `login()` Methods

`setOverrideSuggestedArticles()` Deprecated