Using the iOS User Hook SDK

Loading Hook Points

After you have defined your hook points in the admin webpage, you will need to update your app to call the User Hook servers and load any hook points that apply to the current user.

We suggest that you load hook points when the user starts a new app session. A good place to do this may be the AppDelegate of your app.

#import 'UserHook.h'

- (void)applicationDidBecomeActive:(UIApplication *)application {

    // since the app just became active, we will try to load hookpoints
    [self loadHookpoints];


-(void) loadHookpoints {

    // check for UserHooks for "launch_event_name" event
    [UserHook fetchHookPoint:@"launch_event_name" handler:^(UHHookPoint *hookpoint) {
        if(hookpoint) {
            [hookpoint execute];

Every time you fetch hook points from the server, the server will look at the user’s meta data (session count, session time, custom fields, etc), compare it to the targeting rules of the active hook points, and return one hook point. If no hook point matches the current user, the server will return an empty response.

If the hook point returns an in-app message, such as a Rating Prompt, the prompt will automatically display. If the hook point returns a payload, that will be handled through the Payload Handler.

App Events

Starting with version 2 of the User Hook SDK, all Hook Points now respond to app events. When fetching hook points inside your app, you will need to provide an event name. This allows you to create hook points that respond to specific events within your app. For instance, you may want a survey to appear when a user submits a form. By defining a “submit_form” event, you can assign your survey hook point to only display after the “submit_form” is fired.

When creating a hook point in the User Hook admin website, you are able to create new custom events and attach a hook point to multiple events.

// check for hook points assigned to the "submit_form" event
[UserHook fetchHookPoint:@"submit_form" handler:^(UHHookPoint *hookpoint) {
    if(hookpoint) {
        [hookpoint execute];


When a payload is received from a hook point or push notification, the assigned PayloadHandler is executed.

As an example, let’s imagine we have a payload that will give the user 10 free coins. The payload created in the User Hook admin webpage can be represented as the following:

 'action' : 'give coins',
 'coins' : '10'

In the AppDelegate, we will need to define our payload handler.

#import 'UserHook.h'

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Override point for customization after application launch.

    // setup User Hook
    [UserHook setApplicationId:@"YOUR_USERHOOK_APP_ID" apiKey:@"YOUR_USERHOOK_APP_KEY"]

    [UserHook setPayloadHandler:^(NSDictionary *payload) {

        NSString * action = [payload valueForKey:@"action"];

            if ([action isEqualToString:@"give coins"]) {

                NSNumber * coins = [[payload valueForKey:@"coins"] intValue];

                // logic to give the coins to the user



Sending Custom Fields

Besides any of the predefined targeting fields, you may also send custom fields that will be stored on the User Hook servers. These custom fields can be used when creating targeting rules for hook points.

NSDictionary * customFields = [NSDictionary dictionaryWithObjectsAndKeys:@"user1",@"username", nil];
[UserHook updateCustomFields:customFields];

The above code shows an example of a custom field with the name username and a value of user1. Custom fields are stored as Strings or Numbers. If the value sent to the User Hook servers is convertible to a Number, the value is stored as a Number. Otherwise, the value will be stored as a String.

Logging In-App Purchases

In order to track user purchases, purchase information must be sent to the User Hook servers. Sending purchase data requires an item identifier (ie. sku) and a price. A null price may be sent to the server if you do not wish to track the total purchase amount of a user.

NSString * productIdentifier = ...;
NSNumber * price = ...;
[UserHook updatePurchasedItem:productIdentifier forAmount:price];

Showing Feedback View

To show the Feedback view, the User Hook SDK will create a new UIViewController that is then presented to the user. This happens automatically when the displayFeedback method is called.

[UserHook displayFeedback];

The Feedback view will show all comments submitted by the user and all responses from the app developer.

Setting Title of Feedback View

When the Feedback View is shown, you can customize the title that is shown at the top of the screen. If you wanted to have the screen say “Support” instead of feedback, you could change the title using the following code.

[UserHook setFeedbackScreenTitle:@"Support"];

Sending Custom Feedback Fields

Feedback is sent to User Hook without the need of a user having to create an account. Some developers prefer to know additional information about the user submitting the feedback. Any time during your app lifecycle, you can assign additional fields that will be sent when a user submits new feedback. These additional fields will be displayed inside the feedback thread for that user in the User Hook admin page.

[UserHook setFeedbackCustomFields:@{@"username":@"john123"}];

Showing New Feedback

When the User Hook SDK initializes and creates a new session for the user, it also checks for any new Feedback responses from the app developer to the app user. If there is a new feedback message available, a notification with the name is UH_NotificationNewFeedback is posted. Your app can respond to this feedback and alert the user as needed. One way to alert the user is to display a prompt asking if the user would like to read the new message.

#import 'UserHook.h'

-(void) viewDidLoad {
    // respond to the User Hook new feedback response
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(showFeedback) name:UH_NotificationNewFeedback object:nil];

-(void) showFeedback {

    [UserHook displayFeedbackPrompt:@"You have a new response to your recently submitted feedback. Do you want to read it now?" positiveButtonTitle:@"Yes" negativeButtonTitle:@"Not Now"];


If the user clicks on the positive button, the Feedback screen will be displayed. If the user clicks on the negative button, the prompt will be closed.

Showing Rating Prompts

Besides using a Message Hook Point to display a “Rate This App” prompt, you may also manually display a prompt.

This example is for how to display the rating prompt after a user action, such as clicking on a menu item for “Rate This App”. When using a Message Hook Point, displaying of the prompt is handled automatically by the SDK and the following code is not needed.

[UserHook displayRatePrompt:@"Do you mind leaving us a rating and review in the App Store?" positiveButtonTitle:@"Yes" negativeButtonTitle:@"Not Now"];

You may also redirect the user to the iTunes rating page without using a prompt.

[UserHook rateThisApp]

Starting with iOS 10.3, Apple introduced a new native in-app rate this app prompt. The User Hook SDK will use this new native prompt when available. Apple’s new rating prompt also limits the number of times the prompt can be displayed to the user (currently 3 times per year). In the case where your app tries to show a rating prompt but the native rating prompt does not display, possibly because of this rate limiting, the User Hook SDK will fall back to the older method of redirecting users directly to iTunes to leave a review. Apple has stated that some time in the future, redirecting to iTunes will not be allowed and the native prompt will be the only way to prompt users for reviews.

Static Pages

Static Pages are displayed within the app as a UIViewController with an embedded web view. To display a static page, you need to know the slug of the page you want to display.

#import 'UserHook.h'

NSString * slug  = ...;
NSString * pageTitle = ...;
UHHostedPageViewController * page = [UserHook createHostedPageViewController:slug];
page.navigationItem.title = pageTitle;

UINavigationController * navController  = [[UINavigationController alloc] initWithRootViewController:page];
[self presentViewController:navController animated:YES completion:nil];

You can also query for all available static page names.

// fetch the static page names from the server
[UserHook fetchPageNames:^(NSArray *items) {
   // items is an array of UHPage objects
   // the slug of page is contained in the UHPage.slug property

   for (UHPage * page in items) {
    NSLog(@"page slug=%@ and title=%@", page.slug,;