HSBeacon

@interface 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;

    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;

    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;

    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;

    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;
  • 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;

    Parameters

    user

    The Beacon user to login

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

    Declaration

    Objective-C

    + (HSBeaconUser *_Nullable)currentUser;
  • Logs the current Beacon user out and clears out their information from local storage.

    Declaration

    Objective-C

    + (void)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;

    Parameters

    articleIds

    An array of article ids to override suggestions

  • 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;
  • 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;

    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;
  • 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;
  • 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;

    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;

    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;

    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;

    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.

  • 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;

    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;

    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;

    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;

    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;

    Parameters

    route

    The screen to navigate to - /, /ask/message, 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;

    Parameters

    route

    The screen to navigate to - /, /ask/message, 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;

    Parameters

    route

    The screen to navigate to - /, /ask/message, 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;

    Parameters

    route

    The screen to navigate to - /, /ask/message, 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;

    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;

    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;

    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;

    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.

  • -[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;