iOS Getting Started

Learn how to set up push notifications on iOS

To implement push notifications into your iOS app, there are two things you need to do: integrate the Pushwoosh SDK into your project and configure your app to receive pushes on Apple Developer Portal. This guide describes the process.

Download SDK
Download Sample
SDK API Docs

1. Integrate Pushwoosh SDK into your app.

1.1. To add Pushwoosh.framework to your project using a dependency manager, put the following lines in your podfile or cartfile:

target 'MyApp' do
	pod 'Pushwoosh'
end
github "Pushwoosh/pushwoosh-ios-sdk"

Also, you can simply drag and drop the framework into Link Binaries With Libraries in your project's Build Phases.

1.2. Adding libraries.
In Build Phases tab of your project, open Link Binaries With Libraries and click on Add items ("+" button). Search for and add libz.tbd and libc++.tbd libraries to your project:

1.3. In your Info.plist, add the Pushwoosh_APPID string type key with your Pushwoosh Application ID value.

1.4. Add the following code to your AppDelegate:

import Pushwoosh
import UserNotifications

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, PushNotificationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {  
        //initialization code
        //set custom delegate for push handling, in our case AppDelegate
        PushNotificationManager.push().delegate = self

        //set default Pushwoosh delegate for iOS10 foreground push handling
        if #available(iOS 10.0, *) {
            UNUserNotificationCenter.current().delegate = PushNotificationManager.push().notificationCenterDelegate
        }
        // track application open statistics
        PushNotificationManager.push().sendAppOpen()
    
        // register for push notifications!
        PushNotificationManager.push().registerForPushNotifications()
        return true
    }
  
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        PushNotificationManager.push().handlePushRegistration(deviceToken as Data!)
    }
  
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        PushNotificationManager.push().handlePushRegistrationFailure(error)
    }
  
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        if #available(iOS 10.0, *) {
            completionHandler(UIBackgroundFetchResult.noData)
        } else {
            PushNotificationManager.push().handlePushReceived(userInfo)
            completionHandler(UIBackgroundFetchResult.noData)
        }
    }
    //this event is fired when the push gets received
    func onPushReceived(_ pushManager: PushNotificationManager!, withNotification pushNotification: [AnyHashable : Any]!, onStart: Bool) {
        print("Push notification received: \(pushNotification)")
        // shows a push is received. Implement passive reaction to a push here, such as UI update or data download.
    }
    //this event is fired when user taps the notification
    func onPushAccepted(_ pushManager: PushNotificationManager!, withNotification pushNotification: [AnyHashable : Any]!, onStart: Bool) {
        print("Push notification accepted: \(pushNotification)")
        // shows a user tapped the notification. Implement user interaction, such as showing push details
    }
}
#import <Pushwoosh/PushNotificationManager.h>
#import <UserNotifications/UserNotifications.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    //lots of initialization code
  
    // set custom delegate for push handling, in our case AppDelegate
    PushNotificationManager * pushManager = [PushNotificationManager pushManager]; 
  pushManager.delegate = self;
  
    // set default Pushwoosh delegate for iOS10 foreground push handling
    if (@available(iOS 10.0, *)) {
        [UNUserNotificationCenter currentNotificationCenter].delegate = [PushNotificationManager pushManager].notificationCenterDelegate;
    }

    // track application open statistics
    [[PushNotificationManager pushManager] sendAppOpen];

    // register for push notifications!
    [[PushNotificationManager pushManager] registerForPushNotifications]; 
    return YES;
}

// system push notification registration success callback, delegate to pushManager
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [[PushNotificationManager pushManager] handlePushRegistration:deviceToken];
}
 
// system push notification registration error callback, delegate to pushManager
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    [[PushNotificationManager pushManager] handlePushRegistrationFailure:error];
}
 
// system push notifications callback, delegate to pushManager
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
    if (@available(iOS 10.0, *)) {
        completionHandler(UIBackgroundFetchResultNoData);
    } else {
        [[PushNotificationManager pushManager] handlePushReceived:userInfo];
     completionHandler(UIBackgroundFetchResultNoData);
    }
}

// this event is fired when the push gets received
- (void)onPushReceived:(PushNotificationManager *)pushManager withNotification:(NSDictionary *)pushNotification onStart:(BOOL)onStart {
    NSLog(@"Push notification received");
    // shows a push is received. Implement passive reaction to a push, such as UI update or data download.
}

// this event is fired when user taps the notification
- (void)onPushAccepted:(PushNotificationManager *)pushManager withNotification:(NSDictionary *)pushNotification onStart:(BOOL)onStart {
    NSLog(@"Push notification accepted");
    // shows a user tapped the notification. Implement user interaction, such as showing push details
}

@end

1.5. In Capabilities tab, enable Push Notifications and Remote notifications in Background Modes.

2. Configure iOS platform in Pushwoosh Control Panel.

iOS Auto Configuration

To save time, use our iOS Auto Configuration tool! Simply go to Auto tab in iOS configuration, fill in the required fields, and you're good to go. Please see Step 2.5 for details.
Note that any existing APNs certificates for this Apple App ID will be revoked during Auto Configuration!

After you have integrated Pushwoosh iOS SDK into your project, you need to configure pushes on Apple side.

2.1. Generate a certificate request file.

2.1.1. Launch Keychain Access on your Mac
2.1.2. Select Keychain Access >> Certificate Assistant >> Request a Certificate From a Certificate Authority (Figure 1):

Figure 1

Figure 1

2.1.3. Enter the required information and choose Saved to disk. You should leave the CA email field blank. Click Continue (Figure 2) and Save the certificate request using the suggested name.

Figure 2

Figure 2

2.2. Configure your App ID.

2.2.1. Sign into the Apple Developer Portal and open Certificates, Identifiers & Profiles in the Account tab. There, click Add (Figure 3).

Figure 3

Figure 3

2.2.2. Choose the type of certificate you need and click Continue in the bottom of the page.

2.2.3. Select the App ID of your project on the next page (Figure 4). Then, scroll down and click Continue.

Figure 4

Figure 4

2.2.4. Skip the About Creating a Certificate Signing Request (CSR): you've done it earlier. Click Continue.

2.2.5. Choose the Certificate Signing Request (Figure 5). You've created and saved it in Step 2.1.3.

Figure 5

Figure 5

2.2.6. Download the certificate you have just created and double click it to add to the Keychain Access. Once you click on the certificate, Keychain Access will be launched (Figure 6).

Figure 6

Figure 6

2.3. Export your Private Key.

2.3.1. In Keychain Access, right-click the certificate you just added and choose Export (Figure 7).

Figure 7

Figure 7

2.3.2. Save the Personal Information Exchange (.p12) file anywhere you'd like. You will be prompted to set up a password (Figure 8).

Figure 8

Figure 8

Private Key Password

Make sure to remember the Private Key Password, you will need it later.

2.3.3. After you type in your password, click "Allow" to finish exporting the Private Key.

2.4. Configure your app in Pushwoosh Control panel.

2.4.1. In Pushwoosh Control Panel, choose your app and click on platforms (Figure 9).

Figure 9

Figure 9

2.4.2. Click Configure in the iOS row (Figure 10).

Figure 10

Figure 10

2.4.3. In the opened form, fill in the following fields (Figure 11):

  • Push Certificate (.p12)
  • Private key password
  • Framework
  • Gateway

Click Save. All done!

Figure 11

Figure 11

Certificate File (.cer)

The Certificate file field is deprecated and will be removed soon. You can skip it.

2.5. Auto Configuration

After clicking 'Configure', please select the “Auto” tab and follow these steps to automatically configure iOS platform:

  • 1) Enter your Apple ID and Password;
  • 2) Select your Developer team;
  • 3) Select your App ID;
  • 4) Select the gateway you want to configure: Sandbox for developer builds, Production (aka Distribution) gateway for AdHoc and AppStore builds.

During Auto Configuration a new APNs certificate for the specified Apple App ID is generated. Therefore any existing APNs certificates for this Apple App ID are revoked.