Beacon for iOS

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

Requirements

Please view the requirements for the iOS SDK here on Github.

Supported versions

We make every effort to ensure the Beacon SDK is compatible with the latest, non-beta iOS platform, Swift and Objective-C. If you find a compatibility problem, please contact Help Scout support at help@helpscout.com

View the currently supported versions on the GitHub repository

Useful links

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

Sample application

We’ve created an open-source example application that you can reference during your implementation.

Installation

Swift Package Manager

Beacon is available through Swift Package Manager. To install it, simply follow Apple’s guidance for adding the Beacon-iOS package dependency in Xcode.

CocoaPods

Beacon is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'Beacon'

Beacon is currently distributed as a dynamic framework so the use_frameworks! flag will also need to be present in your Podfile.

Manually

Beacon can be installed manually by linking the Beacon.xcframework. To do so, download the Beacon.xcframework.zip from here and add Beacon.xcframework to your Xcode project.

Additional setup

Photos

The attachments menu for sending a message has code to allow users to take a photo or select one from their photo library. Even if you have attachments disabled, Apple flags usage of these APIs; so, it requires a description string in the app’s Info.plist file.

The required settings are NSPhotoLibraryUsageDescription, NSCameraUsageDescription, NSMicrophoneUsageDescription and NSPhotoLibraryAddUsageDescription:

Documents

To access the documents picker in the attachment menu you must create an iCloud container that matches your app’s bundle ID.

Push notifications

If you do not already have push notifications active in your application, you may receive a warning when uploading to App Store Connect. Similar to Photos, App Store Connect flags usage of these APIs in code independent of whether you invoke them or not.

Usage

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

Usage of the Beacon SDK requires an HSBeaconSettings object, which you initialize using your Beacon ID. After you have created a settings object, you can display the Beacon modal view controller via HSBeacon:

Swift

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.open(settings)

Objective-C

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon openBeacon:settings];

If you need more control over the presentation, then you can open Beacon with a presentingViewController. You might do this if you’re trying to open Beacon from a view controller that is itself presented modally.

Swift

let viewController = UIViewController()
let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.open(settings, from: viewController)

Objective-C

UIViewController *viewController = [[UIViewController alloc] init];
HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon openBeacon:settings fromViewController:viewController];

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.

Swift

let user = HSBeaconUser()
user.email = "test@example.com"
user.name = "Test User"
user.company = "Test Company"
user.jobTitle = "iOS Developer"
user.avatar = URL(string: "https://example.com/avatar")

HSBeacon.identify(user)

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.open(settings)

Objective-C

HSBeaconUser *user = [[HSBeaconUser alloc] init];
user.email = @"test@example.com";
user.name = @"Test User";
user.company = @"Test Company";
user.jobTitle = @"iOS Developer";
user.avatar = [NSURL URLWithString:@"https://example.com/avatar"];

[HSBeacon identify:user];

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon openBeacon:settings];

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.

It is mandatory to also provide the user’s name and email.

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.

Swift

let user = HSBeaconUser()
user.name = "Test"
user.email = "test@example.com"
HSBeacon.identify(user)

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.open(settings, signature: "8235545a15c6f41b64e3c47e5c94d3...")

Objective-C

HSBeaconUser *user = [[HSBeaconUser alloc] init];
user.name = "Test"
user.email = @"test@example.com";
[HSBeacon identify:user];

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon openBeacon:settings signature:@"8235545a15c6f41b64e3c47e5c94d3..."];

Logout

Calling logout clears the current customer identity and resets Beacon’s user/session state on the device.

By default, logout does not force-end active chats. In-progress chats are allowed to complete.
If you want to end any active chat immediately when logging out, pass endActiveChat: true.

Swift

// Default behavior: active chats are not ended
HSBeacon.logout()

// Opt-in: end active chats immediately
HSBeacon.logout(true)

Objective-C

// Default behavior: active chats are not ended
[HSBeacon logout];

// Opt-in: end active chats immediately
[HSBeacon logout:YES];

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

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.

Here’s some example code:

Swift

let user = HSBeaconUser()
let added = user.addAttribute(withKey: "key", value: "attribute value")
if !added {
    // Attribute limit reached (30 attributes maximum)
}

Objective-C

HSBeaconUser *user = [[HSBeaconUser alloc] init];
BOOL added = [user addAttributeWithKey:@"key" value:@"attribute value"];
if (!added) {
    // Attribute limit reached (30 attributes maximum)
}

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

Swift

let user = HSBeaconUser()
user.removeAttribute(withKey: "key") // Remove one attribute
user.clearAttributes() // Clear all attributes

Objective-C

HSBeaconUser *user = [[HSBeaconUser alloc] init];
[user removeAttributeWithKey:@"key"]; // Remove one attribute
[user clearAttributes]; // Clear all attributes

Session attributes

This method allows you to add session-specific information to a new message or chat. By implementing the sessionAttributes method on the HSBeaconDelegate protocol, you can 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 delegate attribute of the settings object needs to be set to the instance implementing the HSBeaconDelegate protocol.

Swift

func sessionAttributes() -> [String : String] {
    return [
        "App Version": "1.2.3",
        "Device Model": "iPhone 14 Pro",
        "OS Version": "iOS 17.0"
    ]
}

Objective-C

- (NSDictionary<NSString*, NSString*> *)sessionAttributes {
    return @{
        @"App Version": @"1.2.3",
        @"Device Model": @"iPhone 14 Pro",
        @"OS Version": @"iOS 17.0"
    };
}

Prefilling the contact form

By implementing the prefill method on the HSBeaconDelegate protocol, you can pre-populate the contact form data. You can fill any of the fields: name, email, subject, the body of the message (text), custom fields, and attachments.

Attachments:

• A maximum of three attachments is permitted
• Each attachment must not exceed 10 MB in size
• The addAttachment:data: method returns YES if the attachment was added successfully, or NO if the attachment limit has been reached or if a duplicate filename was detected

Unlike when using Secure Mode, the name and email fields remain visible and editable.

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

The delegate attribute of the settings object needs to be set to the instance implementing the HSBeaconDelegate protocol.

Swift

extension ViewController: HSBeaconDelegate {
    func prefill(_ form: HSBeaconContactForm) {
        form.name = "Steve Aoki"
        form.email = "steve@aoki.com"
        form.subject = "Need help with invoice"
        form.text = "Hello, I need some help with my invoice. See attached PDF..."
        form.addCustomFieldValue("Question", forId: 5678)
        let invoiceData = try! Data(contentsOf: URL(fileURLWithPath: "/path/to/invoice.pdf"))
        let added = form.addAttachment("invoice.pdf", data: invoiceData)
        if !added {
            // Attachment limit reached or duplicate filename
        }
    }
}

SwiftUI

import Beacon
import Foundation

class BeaconDelegate: NSObject, HSBeaconDelegate {

    static let shared = BeaconDelegate()
    var prefill: ((HSBeaconContactForm) -> Void)?
    var email: String?
    var name: String?
    var subject: String?
    var text: String?


    func prefill(_ form: HSBeaconContactForm) {
        if let prefill = prefill {
            prefill(form)
        } else {
            if let email = email {
                form.email = email
            }
            if let name = name {
                form.name = name
            }
            if let subject = subject {
                form.subject = subject
            }
            if let text = text {
                form.text = text
            }
        }
    }

}

Objective-C

- (void)prefill:(HSBeaconContactForm *)form {
    form.name = @"Steve Aoki";
    form.email = @"steve@aoki.com";
    form.subject = @"Need help with invoice";
    form.text = @"Hello, I need some help with my invoice. See attached PDF...";
    [form addCustomFieldValue: @"Question" forId: 5678];
    NSData *invoiceData = [NSData dataWithContentsOfFile:@"/path/to/invoice.pdf"];
    BOOL added = [form addAttachment: @"invoice.pdf" data:invoiceData];
    if (!added) {
        // Attachment limit reached or duplicate filename
    }
}

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 reset clears all contact form fields, including name and email address.

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

Please note that if a customer is identified using the identify method, then their name and email address won’t be cleared with this method, you’ll have to call logout to clear these fields.

Swift

HSBeacon.reset()

Objective-C

[HSBeacon reset];

Navigate to a specific screen

The HSBeacon navigate method opens the Beacon and shows a specific screen.

• Use navigate when you want to deep-link to a particular Beacon screen (welcome, ask, answers, previous messages, etc).
• Prefer dedicated APIs when they exist. For example, use HSBeacon.search(...) for Docs search and HSBeacon.openArticle(...) to open a specific article.

Swift apps can take advantage of the BeaconRoute enum when calling this method. Common screen routes include:

Swift

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.navigate(BeaconRoute.home, settings: settings) // welcome screen
HSBeacon.navigate(BeaconRoute.ask, settings: settings) // ask screen
HSBeacon.navigate(BeaconRoute.askMessage, settings: settings) // message screen
HSBeacon.navigate(BeaconRoute.askChat, settings: settings) // chat screen
HSBeacon.navigate(BeaconRoute.answers, settings: settings) // answers screen
HSBeacon.navigate(BeaconRoute.aiAnswers, settings: settings) // AI answers screen
HSBeacon.navigate(BeaconRoute.previousMessages, settings: settings) // previous conversations screen

Objective-C

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon navigate:@"/" beaconSettings: settings]; // welcome screen
[HSBeacon navigate:@"/ask/" beaconSettings: settings]; // ask screen
[HSBeacon navigate:@"/ask/message/" beaconSettings: settings]; // message screen
[HSBeacon navigate:@"/ask/chat/" beaconSettings: settings]; // chat screen
[HSBeacon navigate:@"/answers/" beaconSettings: settings]; // answers screen
[HSBeacon navigate:@"/ai-answers/" beaconSettings: settings]; // AI answers screen
[HSBeacon navigate:@"/previous-messages/" beaconSettings: settings]; // previous conversations screen

For Docs-specific entry points, prefer the dedicated methods:

Swift

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.search("help", beaconSettings: settings) // Docs search results
HSBeacon.openArticle("DOCS_ARTICLE_ID", beaconSettings: settings) // specific article

If you want to drive navigation entirely via routes (advanced usage), Swift apps can also use the BeaconRoute enum:

let settings = HSBeaconSettings(beaconId: "beacon-id")

// Route-based navigation (works like a deep link into the Beacon UI)
HSBeacon.navigate(.search("help"), settings: settings)
HSBeacon.navigate(.article("DOCS_ARTICLE_ID"), settings: settings)

Note: route-based navigation is a UI-level deep link. Prefer HSBeacon.search(...) and HSBeacon.openArticle(...) when possible. If you build route strings manually (Objective-C), make sure any query parameter values are URL-encoded.

Objective-C

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];

// Recommended, purpose-built entry points
[HSBeacon search:@"help" beaconSettings:settings];
[HSBeacon openArticle:@"DOCS_ARTICLE_ID" beaconSettings:settings];

// Advanced, route-based navigation (UI deep links)
[HSBeacon navigate:@"/docs/search?query=help" beaconSettings:settings];
[HSBeacon navigate:@"/docs/article?query=DOCS_ARTICLE_ID" beaconSettings:settings];

Opening with search results

The HSBeacon search method searches Docs articles and loads the results screen.

Swift

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.search("HIPAA", beaconSettings: settings)

Objective-C

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon search:@"HIPAA" beaconSettings: settings];

Opening to an article

You can use the HSBeacon openArticle 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]/.

Swift

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.openArticle("DOCS_ARTICLE_ID", beaconSettings: settings)

Objective-C

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon openArticle:@"DOCS_ARTICLE_ID" beaconSettings: settings];

Opening to the contact form

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

Swift

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.navigate(BeaconRoute.askMessage, settings: settings)

Objective-C

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon navigate:@"/ask/message/" beaconSettings:settings];

Opening to AI Answers with a question

The AI Answers screen opens automatically with a specific question sent to it. The question is submitted immediately without any user interaction required.

Note: Requires AI Answers to be enabled.

Swift

let settings = HSBeaconSettings(beaconId: "beacon-id")
HSBeacon.askQuestion("How do I reset my password?", beaconSettings: settings)

Objective-C

HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
[HSBeacon askQuestion:@"How do I reset my password?" beaconSettings:settings];

Custom suggestions

The suggest method allows you to programmatically change the default list of suggestions setup in the Beacon Builder.

There is a limit of 10 suggestions. If the list is larger than 10, additional suggestions will be ignored.

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

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.

Swift

HSBeacon.suggest(["DOCS_ARTICLE_ID_1", "DOCS_ARTICLE_ID_2"])

You can also suggest URLs that are not Docs articles. This is what the syntax would need to look like for custom links:

id<HSBeaconSuggestionItem> article1 = [[HSBeaconArticleSuggestion alloc] initWithId:@"DOCS_ARTICLE_ID_1"];
id<HSBeaconSuggestionItem> link = [[HSBeaconLinkSuggestion alloc] initWithUrl:[NSURL URLWithString:@"https://www.helpscout.com"] text:@"Label for the Suggestion"];
id<HSBeaconSuggestionItem> article2 = [[HSBeaconArticleSuggestion alloc] initWithId:@"DOCS_ARTICLE_ID_2"];
[HSBeacon suggestWithItems:@[article1, link, article2]];

Swift

HSBeacon.suggest(with: [
    HSBeaconArticleSuggestion(id: "DOCS_ARTICLE_ID_1"),
    HSBeaconLinkSuggestion(url: URL(string: "https://www.helpscout.com")!, text: "Label for the Suggestion"),
    HSBeaconArticleSuggestion(id: "DOCS_ARTICLE_ID_2")
])

To expand a little further… Perhaps you’d like to display localized Docs articles based upon a customer’s device language. In the below example, we detect a device language of Spanish 🇪🇸 (“es”), and return Spanish articles:

let language = Locale.current.languageCode
if (language == "es") {
    HSBeacon.suggest(["SPANISH_DOCS_ARTICLE_ID_1",
                      "SPANISH_DOCS_ARTICLE_ID_2",
                      "SPANISH_DOCS_ARTICLE_ID_3"])
}

Objective-C

[HSBeacon suggest:@[@"DOCS_ARTICLE_ID_1", @"DOCS_ARTICLE_ID_2"]];

If you’d like to revert to the default suggestion list from the Beacon Builder, you can call suggest with an empty array.

Open and close events

These methods allow you to hook up to open and close events in the lifecycle of the Beacon to perform custom actions. Example usage:

Swift

extension ViewController: HSBeaconDelegate {
    func onBeaconInitialOpen(_ beaconSettings: HSBeaconSettings) {
        print("First open for Beacon \(beaconSettings.beaconId)")
    }

    func onBeaconOpen(_ beaconSettings: HSBeaconSettings) {
        print("Opened Beacon \(beaconSettings.beaconId)")
    }

    func onBeaconInitialClose(_ beaconSettings: HSBeaconSettings) {
        print("First close for Beacon \(beaconSettings.beaconId)")
    }

    func onBeaconClose(_ beaconSettings: HSBeaconSettings) {
        print("Closed Beacon \(beaconSettings.beaconId)")
    }
}

Objective-C

# pragma mark HSBeaconDelegate
-(void)onBeaconInitialOpen:(HSBeaconSettings *)beaconSettings {
    NSLog(@"First open for Beacon %@", beaconSettings.beaconId);
}

-(void)onBeaconOpen:(HSBeaconSettings *)beaconSettings {
    NSLog(@"Opened Beacon %@", beaconSettings.beaconId);
}

-(void)onBeaconInitialClose:(HSBeaconSettings *)beaconSettings {
    NSLog(@"First close for Beacon %@", beaconSettings.beaconId);
}

-(void)onBeaconClose:(HSBeaconSettings *)beaconSettings {
    NSLog(@"Closed Beacon %@", beaconSettings.beaconId);
}

Settings customization

You can set various options on the HSBeaconSettings object to override the Beacon Builder configuration.

General options

messagingEnabled

focusModeOverride

enablePreviousMessages

docsEnabled

chatEnabled

beaconTitle

useNavigationBarAppearance

color

tintColorOverride

useLocalTranslationOverrides

localizationOverrides

messagingSettings

Contact form options

These are set on the messagingSettings settings object on HSBeaconSettings.

contactFormCustomFieldsEnabled

contactFormShowNameField

contactFormShowSubjectField

contactFormAllowAttachments

showPrefilledCustomFields

Translation strings

Beacon SDK can use a custom localizable strings file in order to override the strings displayed to the customer. By providing a BeaconLocalizable.strings file, you can define a string resource with the same key, and we’ll use that in preference over the Beacon Builder string value. You can also provide translations programmatically using the localizationOverrides dictionary property on HSBeaconSettings. You will need to include the useLocalTranslationOverrides bool set to true in your Beacon’s General Options object for these changes to take effect.

All string keys must exactly match the Beacon API label keys as documented at Beacon API translate options. Each label value will be truncated to 160 characters per Beacon API constraints.

You can find a complete list of available strings in the BeaconLocalizable.strings file.

Answers Section

suggestedForYou

getInTouch

searchLabel

tryAgain

defaultMessageErrorText

beaconButtonClose

beaconButtonChatMinimize

beaconButtonChatOpen

Ask Section

answer

ask

messageButtonLabel

noTimeToWaitAround

chatButtonLabel

chatButtonDescription

wereHereToHelp

whatMethodWorks

previousMessages

Search Results Section

cantFindAnswer

relatedArticles

nothingFound

docsSearchEmptyText

tryBroaderTerm

docsArticleErrorText

docsSearchErrorText

escalationQuestionFeedback

escalationQuestionFeedbackNo

escalationQuestionFeedbackYes

escalationSearchText

escalationSearchTitle

escalationTalkText

escalationTalkTitle

escalationThanksFeedback

escalationWhatNext

Send a Message Section

sendAMessage

firstAFewQuestions

howCanWeHelp

responseTime

history

uploadAnImage

attachAFile

continueWriting

lastUpdated

you

nameLabel

subjectLabel

emailLabel

messageLabel

messageSubmitLabel

next

weAreOnIt

messageConfirmationText

viewAndUpdateMessage

mayNotBeEmpty

customFieldsValidationLabel

emailValidationLabel

attachmentErrorText

attachmentSizeErrorText

Previous Messages Section

addReply

addYourMessageHere

sendMessage

received

waitingForAnAnswer

previousMessageErrorText

justNow

Chat Section

chatHeadingTitle

chatHeadingSublabel

chatEndCalloutHeading

chatEndCalloutMessage

chatEndCalloutLink

chatEndUnassignedCalloutHeading

chatEndUnassignedCalloutMessage

chatEndWaitingCustomerHeading

chatEndWaitingCustomerMessage

ending

endChat

chatEnded

chatConnected

chatbotName

chatbotGreet

chatbotPromptEmail

chatbotConfirmationMessage

chatbotGenericErrorMessage

chatbotInactivityPrompt

chatbotInvalidEmailMessage

chatbotAgentDisconnectedMessage

chatAvailabilityChangeMessage

Transcript Email Section

emailHeading

emailGreeting

emailCopyOfDiscussion

emailContinueConversation

emailJoinedLineItem

emailEndedLineItem

emailYou

AI Answers Section

welcomeMessage

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

Network Error View Section

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

networkErrorTitle

networkErrorMessage

networkErrorRetry

networkErrorClose

networkErrorRetrying

Push notifications

Note: There is no admin UI in Help Scout currently where you can manage your push notification certificates. If you would like to try out this feature, you can email your APNS certificate (as a p12 file with no password) and your bundle ID to help@helpscout.com, and we’ll set it up manually for you.

The push notification support allows your users to receive push notifications when a support agent replies to one of their messages or chats sent from the Beacon SDK. Clicking the notification opens Beacon and takes the user to the conversation.

Automatic handling

Calling the initializeAutomaticPushNotificationHandlingWithMethodSwizzling method automatically adds Push Notification support by wrapping your existing push notification methods.

Note: Automatic handling does not work in secure mode. The SDK does not automatically fetch secure mode signatures when push notifications arrive. If you are using secure mode, you must use manual setup and provide signatures when handling push notifications. See the Secure mode push notifications section below for details.

Swift

HSBeacon.initializeAutomaticPushNotificationHandling(withMethodSwizzling: Bool, overrideUserNotificationCenterDelegate: Bool)

Objective-C

[HSBeacon initializeAutomaticPushNotificationHandlingWithMethodSwizzling:BOOL overrideUserNotificationCenterDelegate:BOOL];

Manual setup

When the app starts up, initialize the notification system for Beacon by calling initializeBeaconPushNotificationSupport

Swift

HSBeacon.initializeBeaconPushNotificationSupport()

Objective-C

[HSBeacon initializeBeaconPushNotificationSupport];

Then you need to register the token by calling setDeviceToken from your Application didRegisterForRemoteNotificationsWithDeviceToken method.

Swift

HSBeacon.setDeviceToken(token)

Objective-C

[HSBeacon setDeviceToken:token];

Let Beacon know if registering for a token failed by calling failedToRegisterForRemoteNotificationsWithError from your application didFailToRegisterForRemoteNotificationsWithError method.

Swift

HSBeacon.failedToRegisterForRemoteNotificationsWithError(error)

Objective-C

[HSBeacon failedToRegisterForRemoteNotificationsWithError:error];

For any of the delegate methods that handle push notifications (application:didReceiveRemoteNotification: or userNotificationCenter:didReceiveNotificationResponse), check for a Beacon notification using isBeaconPushNotification method then invoke handlePushNotification if it matches.

Swift

if HSBeacon.isBeaconPushNotification(userInfo) {
  // Basic variant - displays from application delegate's window root view controller
  HSBeacon.handlePushNotification(userInfo, beaconSettings: settings)
  
  // With view controller
  HSBeacon.handlePushNotification(userInfo, beaconSettings: settings, viewController: self)
}

Objective-C

if ([HSBeacon isBeaconPushNotification:userInfo]) {
  // Basic variant - displays from application delegate's window root view controller
  [HSBeacon handlePushNotification:userInfo beaconSettings:beaconSettings];
  
  // With view controller
  [HSBeacon handlePushNotification:userInfo beaconSettings:beaconSettings viewController:self];
}

Secure mode push notifications

When using secure mode, push notifications require special handling. The SDK does not automatically fetch secure mode signatures when push notifications arrive. Your app must obtain a signature from your backend and provide it when handling the push notification.

Important: Even after app termination, secure mode push notifications can work because device and email mappings are restored from Keychain. However, you must still provide a signature when handling the notification.

Here’s how to handle secure mode push notifications:

Swift

func userNotificationCenter(_ center: UNUserNotificationCenter, 
                            didReceive response: UNNotificationResponse, 
                            withCompletionHandler completionHandler: @escaping () -> Void) {
    let userInfo = response.notification.request.content.userInfo
    
    if HSBeacon.isBeaconPushNotification(userInfo) {
        // Fetch signature from your backend
        fetchSecureModeSignature { signature in
            let settings = HSBeaconSettings(beaconId: "beacon-id")
            
            // Provide the signature when handling the push notification
            HSBeacon.handlePushNotification(userInfo, 
                                          beaconSettings: settings, 
                                          signature: signature)
        }
    }
    
    completionHandler()
}

// Helper method to fetch signature from your backend
func fetchSecureModeSignature(completion: @escaping (String?) -> Void) {
    // Your implementation to fetch signature from your backend
    // This should use the same logic you use when opening Beacon normally
    // ...
}

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center 
 didReceiveNotificationResponse:(UNNotificationResponse *)response 
          withCompletionHandler:(void (^)(void))completionHandler {
    NSDictionary *userInfo = response.notification.request.content.userInfo;
    
    if ([HSBeacon isBeaconPushNotification:userInfo]) {
        // Fetch signature from your backend
        [self fetchSecureModeSignatureWithCompletion:^(NSString *signature) {
            HSBeaconSettings *settings = [[HSBeaconSettings alloc] initWithBeaconId:@"beacon-id"];
            
            // Provide the signature when handling the push notification
            [HSBeacon handlePushNotification:userInfo 
                            beaconSettings:settings 
                                 signature:signature];
        }];
    }
    
    completionHandler();
}

// Helper method to fetch signature from your backend
- (void)fetchSecureModeSignatureWithCompletion:(void (^)(NSString *))completion {
    // Your implementation to fetch signature from your backend
    // This should use the same logic you use when opening Beacon normally
    // ...
}

Note: If you call handlePushNotification without a signature in secure mode, the push notification will open Beacon in anonymous/email-only mode, and users will not have access to their previous conversations.

Last but not least, to handle whether notifications are displayed to the user you should forward any relevant notifications from your UNUserNotificationCenterDelegate userNotificationCenter:willPresentNotification:withCompletionHandler: method to Beacon through the handleWillPresentNotification method. Beacon will only call the completionHandler if it is a Beacon notification.

Swift

func userNotificationCenter(_ center: UNUserNotificationCenter, 
                            willPresent notification: UNNotification, 
                            withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
  let handled = HSBeacon.handleWillPresentNotification(notification, withCompletionHandler: completionHandler)
  if !handled {
    // Handle non-Beacon notifications
    completionHandler([])
  }
}

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center 
        willPresentNotification:(UNNotification *)notification 
          withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
  BOOL handled = [HSBeacon handleWillPresentNotification:notification withCompletionHandler:completionHandler];
  if (!handled) {
    // Handle non-Beacon notifications
    completionHandler(UNNotificationPresentationOptionNone);
  }
}