Customizing the Mobile SDKs

Below you will find examples of different on-device mobile SDK customizations you can make using the SDK API.

Custom Navigation

Your customers are unique and the way you engage with them should meet both their needs and yours. The Beacon SDK offers the option to launch into a specific screen depending on your app’s usage or users’ context.

Open to Contact Form

At times you may want to offer the option for your customers to contact you directly. With the custom navigate feature, you can open Beacon straight to your contact form and even save time by pre-filling form fields.

Technical docs link: iOS | Android

Open to an Article

You may have a Docs article that is helpful for a specific screen or part of your app. Consider using the custom navigation to open directly to that article.

Technical docs link: iOS | Android

Similar to opening directly to an article, you can open direct to a search query. This would be useful if you have several applicable Docs articles that you want to offer to your user.

Technical docs link: iOS | Android

Saving your users time

The Beacon Builder allows you to customize your contact form to collect the information most important to you. The Beacon SDK augments that by offering several ways to identify and pre-fill details to ensure customer information is linked when the message arrives in your Help Scout inbox. It also streamlines the experience for your users and reduces opportunities for inadvertent errors.


If you know your user and have their email address you can use this to effectively authenticate them with the identify() method on Android or iOS. This will link any customer information you already when the message arrives in Help Scout. It’s also possible to enrich your customer’s profile further by setting their Name, Company, Job Title, and Avatar Url.

Without Identify

Without Identify

With Identify

With identify

If you don’t have your user’s email or want to allow them to edit the email, you can pre-populate the contact form using pre-fill in the next section.

Pre-populate the Contact Form

The Beacon SDK provides the option to pre-fill the contact form data. The goal is to save the user time, but keep the values editable so they can customize where needed. For example, you might be looking to prompt the user to provide specific data in the message body such as steps to reproduce a bug with expected and actual results.

If enabled on your Beacon, you can also pre-fill attachments (URIs on Android and file path on iOS). This can be useful for app-specific log files.

Technical docs link: iOS | Android

Prefill and hide Custom Fields

A more advanced option is to pre-fill any configured custom fields and then hide them as not to distract the user. This can save time when triaging the incoming Help Scout conversation (as well as enable automated workflows). More on working with Custom Fields.

Check out the technical docs on pre-filling custom fields. They require some manual mapping if the labels ever change in the future so your pre-fill won’t break. It’ll take some extra work upfront, but will stand the test of time.

Technical docs link: iOS | Android (for hiding prefilled custom fields)

Providing more insight about your users

As mentioned above, using identify() helps link the mobile app user with existing user data within Help Scout. The Beacon SDK gives some additional options for augmenting that data.

Session attributes are designed to add context on the current conversation, whereas user attributes are conversation-agnostic and more suited to longer-lived data. This is because they are associated with the user in Help Scout, which is visible on all their incoming conversations.

Session Attributes

We show session attributes within the Beacon Activity note on the Help Scout conversation. Session attributes are ideal for gathering device-specific data such as manufacturer, model, and OS version — information which can be useful and save time when diagnosing a customer issue. We choose session attributes in this case as users may use multiple devices and this will help pinpoint the specific device reporting the problem. We also use session attributes to record the user’s App version.

Technical docs link: iOS | Android

Session Attributes shown in the Beacon note

Customer Properties

We display Customer Properties in the Customer Properties sidebar app inside Help Scout. They are linked to the customer and are more suited to persistent data such as subscriber status.

Technical docs link: iOS | Android

User attributes shown in the side bar

Overriding Beacon Builder

As mentioned above the mobile SDK Beacon will derive the configuration from the Help Scout Beacon Builder inside Help Scout. You can override this configuration and disable certain features at runtime to suit your needs.

Note: the override functionality is designed for turning off enabled features rather than turning on disabled features.

Technical docs link: iOS | Android

Beacon Mode

You may want to alternate the Beacon mode to promote self-service mode for your free users but offer the neutral mode for paid customers.

Technical docs link: iOS | Android

Self Service

Self Service



Ask First

Ask First

Custom Suggestions

The Custom Suggestions API is specifically for use with Beacons where Docs is enabled. For example, assuming you know a mobile user is an existing customer you might want to offer suggested articles on order tracking, or account management. While this article wouldn’t be as useful for new customers it can help provide context for the right audience at the right time.

Another way to offer different content suggestions for your users is to create an additional Beacon for each platform/local or however you divide it, then configure via the Beacon Builder. If you wish to be more granular and dynamic you can override the suggestions using the SDK API in runtime.

Technical docs link: iOS | Android