Basic integration guide

This section contains information on how to integrate the Pushwoosh SDK into your iOS application.

Prerequisites

To integrate the Pushwoosh iOS SDK into your app, you will need the following:

Requirements

• A Pushwoosh account
• A Pushwoosh project set up in your account.
• An iOS platform configured to send push notifications. We recommend using the Token-Based Authentication configuration as the simplest approach.
• During setup, set the Gateway to Sandbox to send pushes to a simulator.

1. Installation

You can integrate the Pushwoosh SDK into your application using either Swift Package Manager or CocoaPods.

Swift Package Manager

In the Package Dependencies section, add the following package:

https://github.com/Pushwoosh/Pushwoosh-XCFramework

CocoaPods

Open your Podfile and add the dependency:

pod 'PushwooshXCFramework'

Then, in the terminal, run the following command to install dependencies:

pod install

2. Capabilities

To enable Push Notifications in your project, you need to add certain capabilities.

In the Signing & Capabilities section, add the following capabilities:

• Push Notifications
• Background Modes. After adding this capability, check the box for Remote notifications.

If you intend to use Time Sensitive Notifications (iOS 15+), also add the Time Sensitive Notifications capability.

3. Initialization code

AppDelegate

Add the following code to your AppDelegate class:

Swift

import PushwooshFramework

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, PWMessagingDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        //initialization code
        //set custom delegate for push handling, in our case AppDelegate
        Pushwoosh.sharedInstance()?.delegate = self;

        //register for push notifications
        Pushwoosh.sharedInstance()?.registerForPushNotifications()

        return true
    }

    //handle token received from APNS
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Pushwoosh.sharedInstance()?.handlePushRegistration(deviceToken)
    }

    //handle token receiving error
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        Pushwoosh.sharedInstance()?.handlePushRegistrationFailure(error);
    }

    //this is for iOS < 10 and for silent push notifications
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        Pushwoosh.sharedInstance()?.handlePushReceived(userInfo)
        completionHandler(.noData)
    }

    //this event is fired when the push gets received
    func pushwoosh(_ pushwoosh: Pushwoosh!, onMessageReceived message: PWMessage!) {
        print("onMessageReceived: ", message.payload.description)
    }

    //this event is fired when a user taps the notification
    func pushwoosh(_ pushwoosh: Pushwoosh!, onMessageOpened message: PWMessage!) {
        print("onMessageOpened: ", message.payload.description)
    }
}

Objective-C

#import <PushwooshFramework/PushwooshFramework.h>

@implementation AppDelegate

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

  // set custom delegate for push handling, in our case AppDelegate
  [Pushwoosh sharedInstance].delegate = self;

  //register for push notifications!
  [[Pushwoosh sharedInstance] registerForPushNotifications];

  return YES;
}

//handle token received from APNS
- (void)application:(UIApplication *)application
  didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  [[Pushwoosh sharedInstance] handlePushRegistration:deviceToken];
}

//handle token receiving error
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  [[Pushwoosh sharedInstance] handlePushRegistrationFailure:error];
}

//this is for iOS < 10 and for silent push notifications
- (void)application:(UIApplication *)application
  didReceiveRemoteNotification:(NSDictionary *)userInfo
      fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [[Pushwoosh sharedInstance] handlePushReceived:userInfo];
    completionHandler(UIBackgroundFetchResultNoData);
}

//this event is fired when the push gets received
- (void)pushwoosh:(Pushwoosh *)pushwoosh onMessageReceived:(PWMessage *)message {
    NSLog(@"onMessageReceived: %@", message.payload);
}

//this event is fired when user taps the notification
- (void)pushwoosh:(Pushwoosh *)pushwoosh onMessageOpened:(PWMessage *)message {
    NSLog(@"onMessageOpened: %@", message.payload);
}

@end

Info.plist

In your Info.plist:

• set the Pushwoosh_APPID key to the Application Code.
• set the PW_API_TOKEN key to the API Token

4. Message delivery tracking

Pushwoosh supports tracking delivery events for push notifications via the Notification Service Extension

Add Notification Service Extension

1. In Xcode, Select File > New > Target…
2. Choose Notification Service Extension and press Next.
3. Enter the target name and press Finish.
4. When prompted for activation, press Cancel.

Add Pushwoosh SDK to Notification Service Extension

This code allows you to intercept and process notifications within your notification extension.

Swift

import UserNotifications
import PushwooshFramework

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        // Pushwoosh **********
        PWNotificationExtensionManager.shared().handle(request, contentHandler: contentHandler)
        // ********************

        self.contentHandler = contentHandler
        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent {
            // Modify the notification content here...
            bestAttemptContent.title = "\(bestAttemptContent.title) [modified]"

            contentHandler(bestAttemptContent)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Called just before the extension will be terminated by the system.
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }

}

Objective-C

#import "PWNotificationExtensionManager.h"

@interface NotificationService : UNNotificationServiceExtension

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    // Pushwoosh **********
    [[PWNotificationExtensionManager sharedManager] handleNotificationRequest:request contentHandler:contentHandler];
    //*********************
}

@end

App Groups capability

You must enable App Groups capability to allow the Notification Service Extension to communicate with the main app.

For both the main target and the Notification Service Extension:

1. Go to Signing & Capabilities and add the App Groups capability.
2. Press + to add a new group.
3. Ensure the group name starts with group..
4. Use the same group for both the main target and the Notification Service Extension.

Info.plist

In your main target’s Info.plist, add

• PW_APP_GROUPS_NAME — The name of your App Groups group

In your Notification Service Extension’s Info.plist, add:

• PW_APP_GROUPS_NAME — The name of your App Groups group
• Pushwoosh_APPID - Your Application Code.

5. Run the project

1. Build and run the project.
2. Go to the Pushwoosh Control Panel and send a push notification.
3. You should see the notification in the app.

Troubleshooting

If you encounter any issues during the integration process, please refer to the support and community section.