Skip to content

Step-by-Step Integration

App Configuration

SendMan's integration with your app strives to be as simple and explicit as possible.

Install the SDK

SendMan can be installed via either CocoaPods or via Carthage

pod 'SendMan', '~> 1.0.0'
github "sendmanio/sendman-ios-sdk" ~> 1.0.0

Connect with Your App's Code

These are the steps for integrating our SDK:

  1. Initializing our SDK
  2. Registering the device for push notifications
  3. Handling received notifications
  4. Optional: Reporting custom properties

SDK Initialization

In order to start reporting to our API, your app needs to authenticate itself using its configured set of mobile keys.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ... Standard initiailization of your application

    // Connect SendMan SDK
    let sendmanConfig = SMConfig(key: YOUR_APP_KEY, andSecret: YOUR_APP_SECRET)
    SendMan.setAppConfig(sendmanConfig)

    // Set your AppDelegate as the delegate in charge of receiving notifications for the app from the OS. 
    UNUserNotificationCenter.current().delegate = self

    return true
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ... Standard initiailization of your application

    SMConfig *config = [[SMConfig alloc] initWithKey:YOUR_APP_KEY andSecret:YOUR_APP_SECRET];
    [SendMan setAppConfig:config];

    [UNUserNotificationCenter currentNotificationCenter].delegate = self;

    return YES;
}

Aside from app-level identification, we need to identify each app user separately. There are two ways to do it:

  1. If your application has unique IDs for its users, you can use them to identify your users:

    SendMan.setUserId("some-unique-id")
    
    [SendMan setUserId:@"some-unique-id"];
    
  2. If your application does not have unique user IDs, SendMan can automatically generate unique user IDs for you. Configure it by altering the SDK initialization as follows:

    SendMan.setAppConfig(SMConfig(key: YOUR_APP_KEY, andSecret: YOUR_APP_SECRET, autoGenerateUsers: true))
    
    [SendMan setAppConfig:[[SMConfig alloc] initWithKey:YOUR_APP_KEY andSecret:YOUR_APP_SECRET autoGenerateUsers:YES]];
    

    Attention

    Never use autoGenerateUsers and setUserId on the same app.

Register notification tokens

In order to send notifications to an iOS device, the device needs to be identified by Apple with some device ID. In order to do this, we issue a device token using Apple's Push Notification Service (commonly known as APN), which is the native way to send push notifications to Apple devices.

This process is comprised of 2 stages:

  1. Opting in to push notifications through the operating system.
    This happens by calling the requestAuthorizationWithOptions method from UNUserNotificationCenter.
    Doing so in SendMan is as simple as:

    // Without a custom callback
    SendMan.requestPushAuthorization()
    
    // OR: With a custom callback
    SendMan.requestPushAuthorization { granted in
        // An optional callback to perform once the user has interacted
        // with Apple's native push notification authorization dialog
        // granted is true if the user authorized the request
    }
    
    // Without a custom callback
    [SendMan requestPushAuthorization:nil];
    
    // OR: With a custom callback
    [SendMan requestPushAuthorization:^(BOOL granted) {
        // An optional callback to perform once the user has interacted
        // with Apple's native push notification authorization dialog
        // granted is true if the user authorized the request
    }];
    

    Tip

    Getting approval for push notifications from your users is a delicate procedure.
    Apple will only display the native popup once, so make sure you display it at a time your users are most inclined to agree to receiving notifications.
  2. Requesting an APN device token specific to this app and device combination. This happens by calling the registerForRemoteNotifications method from UIApplication.
    This will automatically be called when the app moves to the foreground, triggering a pair of callbacks:

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // ... Your own handling of device tokens, if you choose to have one.
    
        SendMan.applicationDidRegisterForRemoteNotifications(withDeviceToken: deviceToken)
    }
    
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        // ... Your own error reporting regarding token registration, if you choose to have one.
    
        SendMan.applicationDidFailToRegisterForRemoteNotificationsWithError(error)
    }
    
    - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
        // ... Your own handling of device tokens, if you choose to have one. 
    
        [SendMan applicationDidRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
    }
    
    - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
        // ... Your own error reporting regarding token registration, if you choose to have one.
    
        [SendMan applicationDidFailToRegisterForRemoteNotificationsWithError:error];
    }
    

    Alternatively, you can set the token in SendMan by yourself:

    SendMan.setAPNToken(token)
    
    [SendMan setAPNToken:token];
    

    This can be used when you already have a snippet of code in your app that is in charge of getting the token from Apple.

Receive and display push notifications

When a push notification is received by an iOS device, there are several methods that may be called, according to the app's state and the contents of the received notification.

Scenario 1: App is currently running in the foreground

When a push notification is received while the app is in the foreground, SendMan can track it using this method:

func userNotificationCenter(_: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    SendMan.userNotificationCenterWillPresent(notification)
    completionHandler(.alert) // Show the native iOS alert even though the user is currently using the app
}
- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
    [SendMan userNotificationCenterWillPresentNotification:notification];
    completionHandler(UNNotificationPresentationOptionAlert); // Show the native iOS alert even though the user is currently using the app
}
Implementing this method will allow SendMan to track Received in Foreground.

Info

Aside from the tracking, you should also decide on the form of display that is most suitable for the user experience (UX) of your application.
The example above shows the leanest form of displaying a foreground notification — using Apple's native dialog.

Scenario 2: App is currently in the background

If a push notification is received while the app is in the background, this method will be called when the user clicks on the notification to open the app (and not, for instance, if the user did so by clicking on the app icon):

func userNotificationCenter(_: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    completionHandler()
    SendMan.userNotificationCenterDidReceive(response)
}
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    completionHandler();
    [SendMan userNotificationCenterDidReceiveNotificationResponse:response];
}

Implementing this method will allow SendMan to track Direct Engagement.

Scenario 3: App was not running at all

If the app has not been started since a device restart (or was killed from the task manager), clicking a notification is handled by the app launch method (which you already encountered during the SDK initialization), as follows:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ... Standard initiailization of your application

    // SendMan Initialization
    let sendmanConfig = SMConfig(key: YOUR_APP_KEY, andSecret: YOUR_APP_SECRET)
    SendMan.setAppConfig(sendmanConfig)

    // This handles notifications that launch the application
    SendMan.applicationDidFinishLaunching(options: launchOptions)

    return true
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ... Standard initiailization of your application

    // SendMan Initialization
    SMConfig *config = [[SMConfig alloc] initWithKey:YOUR_APP_KEY andSecret:YOUR_APP_SECRET];
    [SendMan setAppConfig:config];

    // This handles notifications that launch the application 
    [SendMan applicationDidFinishLaunchingWithOptions:launchOptions];

    return YES;
}

Implementing this method will allow SendMan to track Direct Engagement and Indirect Engagement.

Report Custom Properties (Optional)

SendMan supports setting custom properties for your users in the following way:

SendMan.setUserProperties(["some property": "value", "a numeric property": 2, "a boolean property": true])
[SendMan setUserProperties:@{@"some property": @"value", @"a numeric property": @2, @"a boolean property": @YES}];

This is useful for filtering users before sending a group notification.
SendMan also supports notification params, which can be filled dynamically for each user, with the value of these custom properties.

Configure Capabilities

In order to receive notifications, make sure your app matched the capabilities below.
Go to Target > Signing & Capabilities and check the following capabilities:

  1. Push Notifications
  2. Background Modes
    • Remote Notifications
Any other capabilities can be set depending on your app's needs.

Info

Our SDK supports iOS versions 10 and above.

Finish Configuration

This concludes the integration on your app's end.
In order to make everything work, you should now head to our console and configure your app as described in this 'Add Application' section.