HSBeacon

Objective-C

@interface HSBeacon : NSObject

Swift

class HSBeacon : NSObject

HSBeacon provides the APIs necessary to display the Beacon SDK. It allows you to open the Beacon from the current view controller on screen, or a specific view controller of your choice.

Opening the Beacon From The Current View Controller

The Beacon SDK requires an HSBeaconSettings object, which can be initialized using your Beacon ID.

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

Authenticating Users

Authenticating with Beacon is optional, but if you have information you’d like to associate with users, you can do so using HSBeaconUser and the login: method before showing the Beacon.

HSBeaconUser *user = [[HSBeaconUser alloc] init];
user.email = self.emailTextField.text;
user.name = self.nameTextField.text;

[HSBeacon login:user];

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

  • Opens the Beacon SDK from the current view controller.

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)openBeacon:(nonnull HSBeaconSettings *)settings;

    Swift

    class func open(_ settings: HSBeaconSettings)

    Parameters

    settings

    The Beacon settings from which to load Beacon.

  • Opens the Beacon SDK from the current view controller, using a signature.

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)openBeacon:(nonnull HSBeaconSettings *)settings
         signature:(nonnull NSString *)signature;

    Swift

    class func open(_ settings: HSBeaconSettings, signature: String)

    Parameters

    settings

    The Beacon settings from which to load Beacon.
    signature

    The signature to provide, if you are using secure mode.

  • Opens the Beacon SDK from a specific view controller. The Beacon view controller will be presented as a modal.

    Declaration

    Objective-C

    + (void)openBeacon:(nonnull HSBeaconSettings *)settings
    fromViewController:(nonnull UIViewController *)viewController;

    Swift

    class func open(_ settings: HSBeaconSettings, from viewController: UIViewController)

    Parameters

    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.

  • Opens the Beacon SDK from a specific view controller. The Beacon view controller will be presented as a modal.

    Declaration

    Objective-C

    + (void)openBeacon:(nonnull HSBeaconSettings *)settings
    fromViewController:(nonnull UIViewController *)viewController
             signature:(nonnull NSString *)signature;

    Swift

    class func open(_ settings: HSBeaconSettings, from viewController: UIViewController, signature: String)

    Parameters

    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.
    signature

    The signature to provide, if you are using secure mode.

  • Hides the SDK modal window if present. Useful for when the app is returning from the background.

    Declaration

    Objective-C

    + (void)dismissBeacon:(void (^_Nullable)(void))completion;

    Swift

    class func dismiss(_ completion: (() -> Void)? = nil)

  • Deprecated

    Please use HSBeacon.identify instead

    Signs in with a Beacon user. This gives Beacon access to the user’s name, email address, and signature.

    Declaration

    Objective-C

    + (nonnull instancetype)login:(nonnull HSBeaconUser *)user;

    Swift

    class func login(_ user: HSBeaconUser) -> Self

    Parameters

    user

    The Beacon user to login

  • Signs in with a Beacon user. This gives Beacon access to the user’s name, email address, and signature.

    Declaration

    Objective-C

    + (void)identify:(nonnull HSBeaconUser *)user;

    Swift

    class func identify(_ user: HSBeaconUser)

    Parameters

    user

    The Beacon user to identify

  • Returns the current user, providing they are signed in.

    Declaration

    Objective-C

    + (HSBeaconUser *_Nullable)currentUser;

    Swift

    class func currentUser() -> HSBeaconUser?

  • Logs the current Beacon user out and clears out their information from local storage.

    Declaration

    Objective-C

    + (void)logout;

    Swift

    class func logout()

  • Programmatically change the suggestted articles displayed. If the Beacon is visible, the change will take place right away. Otherwise, the article data will change on the next open.

    Passing in an empty array will restore the default list.

    Declaration

    Objective-C

    + (void)suggest:(nonnull NSArray<NSString *> *)articleIds;

    Swift

    class func suggest(_ articleIds: [String])

    Parameters

    articleIds

    An array of article ids to override suggestions

  • Programmatically change the suggestted items displayed. This implementation accepts either HSBeaconArticleSuggestion or HSBeaconLinkSuggestion objects in the array.

    If the Beacon is visible the change will take place right away. Otherwise, the article data will change on the next open.

    Passing in an empty array will restore the default list.

    Declaration

    Objective-C

    + (void)suggestWithItems:
    (nonnull NSArray<id<HSBeaconSuggestionItem>> *)suggestions;

    Parameters

    suggestions

    An array of HSBeaconArticleSuggestion or HSBeaconLinkSuggestion objects

  • Initializes push notifications for the Beacon SDK. This should be called if you intend to receive push notifications with a manual setup.

    Declaration

    Objective-C

    + (void)initializeBeaconPushNotificationSupport;

    Swift

    class func initializeBeaconPushNotificationSupport()

  • Initializes automatic push notification handling for the Beacon SDK.

    This will wrap the following methods on UIApplicationDelegage with method swizzling:

    application:didReceiveRemoteNotification: application:didRegisterForRemoteNotificationsWithDeviceToken: application:didFailToRegisterForRemoteNotificationsWithError:

    In addition, this wraps all of methods on UNUserNotificationCenterDelegate.

    Declaration

    Objective-C

    + (void)initializeAutomaticPushNotificationHandlingWithMethodSwizzling:
            (BOOL)methodSwizzling
                                overrideUserNotificationCenterDelegate:
                                    (BOOL)overrideDelegate;

    Swift

    class func initializeAutomaticPushNotificationHandling(withMethodSwizzling methodSwizzling: Bool, overrideUserNotificationCenterDelegate overrideDelegate: Bool)

    Parameters

    methodSwizzling

    Whether to override push notification methods on the App Delegate.
    overrideDelegate

    Whether to override UNUserNotificationCenter‘s delegate method for automatic handling of push notifications.

  • This lets Beacon know about the user’s notification token, so the Beacon backend can send push notifications on behalf of the app. You only need to call this for manual push notification handling.

    Declaration

    Objective-C

    + (void)setDeviceToken:(nonnull NSData *)deviceToken;

    Swift

    class func setDeviceToken(_ deviceToken: Data)

  • This lets Beacon know that a potential device token is not forthcoming, so dependent processes can continue. You only need to call this for manual push notification handling.

    Declaration

    Objective-C

    + (void)failedToRegisterForRemoteNotificationsWithError:
    (nonnull NSError *)error;

    Swift

    class func failedToRegisterForRemoteNotificationsWithError(_ error: Error)

  • Checks whether a given push notification came from Help Scout. You should call this method before calling handlePushNotification:.

    Declaration

    Objective-C

    + (BOOL)isBeaconPushNotification:(nonnull NSDictionary *)userInfo;

    Swift

    class func isBeaconPushNotification(_ userInfo: [AnyHashable : Any]) -> Bool

  • Handles a Beacon push notification. If the user info dictionary does not match the expected format, this method does nothing.

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)handlePushNotification:(nonnull NSDictionary *)userInfo
                beaconSettings:(nonnull HSBeaconSettings *)settings;

    Swift

    class func handlePushNotification(_ userInfo: [AnyHashable : Any], beaconSettings settings: HSBeaconSettings)

    Parameters

    userInfo

    The user info payload from the notification.
    settings

    The Beacon settings from which to load Beacon.

  • Handles a Beacon push notification. If the user info dictionary does not match the expected format, this method does nothing.

    Declaration

    Objective-C

    + (void)handlePushNotification:(nonnull NSDictionary *)userInfo
                beaconSettings:(nonnull HSBeaconSettings *)settings
                viewController:(nonnull UIViewController *)viewController;

    Swift

    class func handlePushNotification(_ userInfo: [AnyHashable : Any], beaconSettings settings: HSBeaconSettings, viewController: UIViewController)

    Parameters

    userInfo

    The user info payload from the notification.
    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.

  • Handles a Beacon push notification. If the user info dictionary does not match the expected format, this method does nothing.

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)handlePushNotification:(nonnull NSDictionary *)userInfo
                beaconSettings:(nonnull HSBeaconSettings *)settings
                     signature:(NSString *_Nullable)signature;

    Swift

    class func handlePushNotification(_ userInfo: [AnyHashable : Any], beaconSettings settings: HSBeaconSettings, signature: String?)

    Parameters

    userInfo

    The user info payload from the notification.
    settings

    The Beacon settings from which to load Beacon.
    signature

    The signature to provide, if you are using secure mode.

  • Handles a Beacon push notification. If the user info dictionary does not match the expected format, this method does nothing.

    Declaration

    Objective-C

    + (void)handlePushNotification:(nonnull NSDictionary *)userInfo
                beaconSettings:(nonnull HSBeaconSettings *)settings
                viewController:(nonnull UIViewController *)viewController
                     signature:(NSString *_Nullable)signature;

    Swift

    class func handlePushNotification(_ userInfo: [AnyHashable : Any], beaconSettings settings: HSBeaconSettings, viewController: UIViewController, signature: String?)

    Parameters

    userInfo

    The user info payload from the notification.
    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.
    signature

    The signature to provide, if you are using secure mode.

  • Determines whether or not a push notification should be shown to the user. The completionHandler will only be called in the case thatUNNotfication` is a Beacon notification.

    Declaration

    Objective-C

    + (void)handleWillPresentNotification:(nonnull UNNotification *)notification
                withCompletionHandler:
                    (nonnull void (^)(UNNotificationPresentationOptions))
                        completionHandler;

    Swift

    class func handleWillPresent(_ notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void)

    Parameters

    notification

    The UNNotification received by the UNUserNotificationCenterDelegate
    completionHandler

    The completion block passed to the UNUnserNotificationCenterDelegate

  • Opens the Beacon window to search results for the provided string.

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)search:(nonnull NSString *)text
    beaconSettings:(nonnull HSBeaconSettings *)settings;

    Swift

    class func search(_ text: String, beaconSettings settings: HSBeaconSettings)

    Parameters

    text

    The text to search with
    settings

    The Beacon settings from which to load Beacon.

  • Opens the Beacon window to search results for the provided string.

    Declaration

    Objective-C

    + (void)search:(nonnull NSString *)text
    beaconSettings:(nonnull HSBeaconSettings *)settings
    viewController:(nonnull UIViewController *)viewController;

    Swift

    class func search(_ text: String, beaconSettings settings: HSBeaconSettings, viewController: UIViewController)

    Parameters

    text

    The text to search with
    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.

  • Opens the Beacon window to search results for the provided string.

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)search:(nonnull NSString *)text
    beaconSettings:(nonnull HSBeaconSettings *)settings
         signature:(NSString *_Nullable)signature;

    Swift

    class func search(_ text: String, beaconSettings settings: HSBeaconSettings, signature: String?)

    Parameters

    text

    The text to search with
    settings

    The Beacon settings from which to load Beacon.
    signature

    The signature to provide, if you are using secure mode.

  • Opens the Beacon window to search results for the provided string.

    Declaration

    Objective-C

    + (void)search:(nonnull NSString *)text
    beaconSettings:(nonnull HSBeaconSettings *)settings
    viewController:(nonnull UIViewController *)viewController
         signature:(NSString *_Nullable)signature;

    Swift

    class func search(_ text: String, beaconSettings settings: HSBeaconSettings, viewController: UIViewController, signature: String?)

    Parameters

    text

    The text to search with
    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.
    signature

    The signature to provide, if you are using secure mode.

  • Navigates to a specific screen. Available routes are: “/” - welcome screen “/ask/message/” - message screen “/docs/search?query=help” - this is the same as the HSBeacon search method

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)navigate:(nonnull NSString *)route
    beaconSettings:(nonnull HSBeaconSettings *)settings;

    Swift

    class func navigate(_ route: String, beaconSettings settings: HSBeaconSettings)

    Parameters

    route

    The screen to navigate to - “/”, “/ask/message”, “/previous-messages”, or “/docs/search?query=help”
    settings

    The Beacon settings from which to load Beacon.

  • Navigates to a specific screen. Available routes are: “/” - welcome screen “/ask/message/” - message screen “/docs/search?query=help” - this is the same as the HSBeacon search method

    Declaration

    Objective-C

    + (void)navigate:(nonnull NSString *)route
    beaconSettings:(nonnull HSBeaconSettings *)settings
    viewController:(nonnull UIViewController *)viewController;

    Swift

    class func navigate(_ route: String, beaconSettings settings: HSBeaconSettings, viewController: UIViewController)

    Parameters

    route

    The screen to navigate to - “/”, “/ask/message”, “/previous-messages”, or “/docs/search?query=help”
    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.

  • Navigates to a specific screen. Available routes are: “/” - welcome screen “/ask/message/” - message screen “/docs/search?query=help” - this is the same as the HSBeacon search method

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)navigate:(nonnull NSString *)route
    beaconSettings:(nonnull HSBeaconSettings *)settings
         signature:(NSString *_Nullable)signature;

    Swift

    class func navigate(_ route: String, beaconSettings settings: HSBeaconSettings, signature: String?)

    Parameters

    route

    The screen to navigate to - “/”, “/ask/message”, “/previous-messages”, or “/docs/search?query=help”
    settings

    The Beacon settings from which to load Beacon.
    signature

    The signature to provide, if you are using secure mode.

  • Navigates to a specific screen. Available routes are: “/” - welcome screen “/ask/message/” - message screen “/docs/search?query=help” - this is the same as the HSBeacon search method

    Declaration

    Objective-C

    + (void)navigate:(nonnull NSString *)route
    beaconSettings:(nonnull HSBeaconSettings *)settings
    viewController:(nonnull UIViewController *)viewController
         signature:(NSString *_Nullable)signature;

    Swift

    class func navigate(_ route: String, beaconSettings settings: HSBeaconSettings, viewController: UIViewController, signature: String?)

    Parameters

    route

    The screen to navigate to - “/”, “/ask/message”, “/previous-messages”, or “/docs/search?query=help”
    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.
    signature

    The signature to provide, if you are using secure mode.

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

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)openArticle:(nonnull NSString *)articleId
     beaconSettings:(nonnull HSBeaconSettings *)settings;

    Swift

    class func openArticle(_ articleId: String, beaconSettings settings: HSBeaconSettings)

    Parameters

    articleId

    The id of the article to open up
    settings

    The Beacon settings from which to load Beacon.

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

    Declaration

    Objective-C

    + (void)openArticle:(nonnull NSString *)articleId
     beaconSettings:(nonnull HSBeaconSettings *)settings
     viewController:(nonnull UIViewController *)viewController;

    Swift

    class func openArticle(_ articleId: String, beaconSettings settings: HSBeaconSettings, viewController: UIViewController)

    Parameters

    articleId

    The id of the article to open up
    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.

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

    Note

    Displays Beacon from the application delegate’s window root view controller.

    Declaration

    Objective-C

    + (void)openArticle:(nonnull NSString *)articleId
     beaconSettings:(nonnull HSBeaconSettings *)settings
          signature:(NSString *_Nullable)signature;

    Swift

    class func openArticle(_ articleId: String, beaconSettings settings: HSBeaconSettings, signature: String?)

    Parameters

    articleId

    The id of the article to open up
    settings

    The Beacon settings from which to load Beacon.
    signature

    The signature to provide, if you are using secure mode.

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

    Declaration

    Objective-C

    + (void)openArticle:(nonnull NSString *)articleId
     beaconSettings:(nonnull HSBeaconSettings *)settings
     viewController:(nonnull UIViewController *)viewController
          signature:(NSString *_Nullable)signature;

    Swift

    class func openArticle(_ articleId: String, beaconSettings settings: HSBeaconSettings, viewController: UIViewController, signature: String?)

    Parameters

    articleId

    The id of the article to open up
    settings

    The Beacon settings from which to load Beacon.
    viewController

    The view controller to display Beacon from.
    signature

    The signature to provide, if you are using secure mode.

  • Resets the contact form by clearing all of its fields, custom fields and attachments. If your Beacon is in Normal Mode, calling reset will clear all contact form fields, including name and email address.

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

    Declaration

    Objective-C

    + (void)reset;

    Swift

    class func reset()

  • Unavailable

    HSBeacon cannot be created directly

    -[HSBeacon init] is not available because HSBeacon cannot be created directly. Use the openBeacon: methods to display the Beacon SDK.

    Declaration

    Objective-C

    - (nonnull instancetype)init;