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 read the HTTP requests and other actions that happen with 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"

Secure mode

If you provide a valid signature, you can use it to authenticate a user in Secure Mode and retrieve their previous conversations. 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.

  BeaconActivity.openInSecureMode(context, "8235545a15c6f41b64e3c47e5c94d3...");

Logout

Calling this method resets the current Beacon state, thereby deleting all the user data: email, name, user attributes, push token and resets the Beacon Device ID. It won’t remove the Beacon ID, or any local config overrides.

  Beacon.logout();

Clear

This method wipes all data from the Beacon, including the Beacon ID. This may be useful if you are using different Beacons in different parts of your app.

  Beacon.clear();

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.

You may add an attribute like so:

  Beacon.addAttributeWithKey("Subscription", "Free Plan");

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

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. Note a maximum of three attachments is permitted. Unlike when using Secure Mode, the name and email fields remain visible and editable. We clear the data from the PreFilledForm object on contact form send.

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
                 "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 )
                 "steve@aoki.com");//email address

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 is logged-in using the login 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 Help & Support 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>());

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.

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]/.

// There is a limit of 5 article ids. If the list is larger than 5, we ignore the additional articles.
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, you can call Beacon.setOverrideSuggestedArticlesOrLinks with an empty list.

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

messagingEnabled

docsEnabled

chatEnabled

color

focusMode

enablePreviousMessages

Contact form options

These are set by setting the BeaconContactForm object on the BeaconConfigOverrides

customFieldsEnabled

showName

showSubject

allowAttachments

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

We lean on the Android resources system to provide overrides for Strings defined in the Beacon Builder. You can find a list of the overridable strings keys in the public.txt of the beacon-ui AAR file. 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 beacon-strings.xml file and include the following to offer Spanish localization.

<string name="hs_beacon_send_a_message_title">Contáctenos</string>
<string name="hs_beacon_related_articles">También podría gustarte</string>
...

The customization sample project shows this in practice.

Mobile specific strings

Note some strings are Android/Mobile specific and there isn’t a Beacon Builder equivalent but these can also be overridden in the same way. For example:

<string name="hs_beacon_home_title">Help Desk</string>
<string name="hs_beacon_error_open_activity_not_found">Cannot find an app that supports opening files of this type</string>

hs_beacon_error_loading_more

hs_beacon_error_open_activity_not_found

hs_beacon_error_open_unknown

hs_beacon_menu_close

hs_beacon_customfield_select_option

hs_beacon_customfield_dropdown_leave_blank

hs_beacon_discard

hs_beacon_continue_to

hs_beacon_reply_sent

hs_beacon_search_error_more

hs_beacon_error_config

hs_beacon_error_config_title

hs_beacon_error_article_not_found

hs_beacon_message_attachments_section_title

hs_beacon_error_timeout

hs_beacon_error_network

hs_beacon_error_server

hs_beacon_error_unknown

hs_beacon_confirm_email_address_to_view_conversations

hs_beacon_message_error_too_many_files

hs_beacon_message_error_downloading_attachment

hs_beacon_message_error_invalid_attachment_extension

hs_beacon_attachment_downloading_please_wait

hs_beacon_message_error_uploading_attachment

hs_beacon_message_error_deleting_attachment

hs_beacon_message_error_no_previous_messages_found

hs_beacon_conversation_show_more

hs_beacon_error_article_error_title

hs_beacon_error_article_not_found_go_back

Chat specific strings

hs_beacon_chat_message_failed

hs_beacon_chat_view_conversation

hs_beacon_message_agent_avatar_content_description

hs_beacon_chat_downloading_image_attachment

hs_beacon_chat_downloading_image_attachment_failed

hs_beacon_chat_tap_to_retry

hs_beacon_chat_download_error

hs_beacon_chat_attachment_upload_error

hs_beacon_chat_attachment_invalid_extension_error

hs_beacon_chat_end_chat_dialog_header

hs_beacon_chat_ended_title

hs_beacon_chat_email_hint

hs_beacon_chat_menu_download_file

hs_beacon_chat_attachment_image_download

hs_beacon_chat_max_attachments_reached

hs_beacon_chat_agent_name_if_missing

hs_beacon_chat_rating_button_skip

hs_beacon_chat_rating_discard_changes_message

hs_beacon_chat_rating_discard_changes_button_positive

hs_beacon_chat_rating_discard_changes_button_negative

Push notification strings

hs_beacon_notification_reply_action_label

hs_beacon_notification_mark_as_read_action_label

hs_beacon_notification_channel_id

hs_beacon_notification_channel_name

hs_beacon_chat_notification_channel_id

hs_beacon_chat_notification_channel_name

hs_beacon_chat_notification_agent_replied_default_title

hs_beacon_chat_notification_default_agent_name

hs_beacon_chat_notification_inactivity_title

hs_beacon_notification_default_users_name

hs_beacon_conversation_notification_default_agent_name

hs_beacon_conversation_notification_default_title

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:

1. Go to Firebase Console.
2. Select your project, and click the gear icon on the top of the sidebar.
3. Head to project settings.
4. Navigate to the service account tab.
5. Click Generate New Private Key, then confirm by clicking Generate Key.
6. 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.

If running on Android 7.0 (API level 24), users can use Direct reply and enter text directly into the notification.

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