Customizing iOS SDK

Setting up Pushwoosh iOS SDK
iOS Manual Configuration
Requirements
Create Pushwoosh account if you do not already have one.
Real device with iOS 9 and later. The Xcode simulator doesn't support push notifications so you must test on a real device.
A Mac with a new version of Xcode.
An iOS Push Certificate. For details, please read iOS configuration.
Integration
​Background modes​
​Notification alert in foreground​
​Controlling Log Level​
​Deep linking​
​In-Apps Tracking​
​Geozones push notifications​
​Creating a Rich Media queue​
​Custom UNNotificationCenterDelegate​
​Custom push sound​
​Complete list of iOS SDK feature flags​
​iOS Provisional Push​
Background modes
To ensure that Pushwoosh SDK always receives the push token it is highly recommended to enable the Remote notifications option from the Background modes section of the Capabilities tab in your Xcode project. You can also enable this support by including the UIBackgroundModes key with the remote-notification value in your app’s Info.plist file.
1
<key>UIBackgroundModes</key>
2
<array>
3
    <string>remote-notifications</string>
4
</array>
Copied!
pushwoosh-quickstart-ios/Info.plist at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
Example
Notification alert in foreground
By default Pushwoosh iOS SDK displays the notification banner when the app is running in the foreground.
You can control this behavior by setting the following boolean flag in your code (i.e. in your AppDelegate):
Swift
Objective-C
1
//set false to disable foreground notications, true to enable it
2
Pushwoosh.sharedInstance().showPushnotificationAlert = true;
Copied!
1
//set 0 to disable foreground notications, 1 to enable it 
2
[[Pushwoosh sharedInstance] setShowPushnotificationAlert:0];
Copied!
pushwoosh-quickstart-ios/ViewController.swift at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
Example
Controlling Log Level
To assist with debugging and integration, SDK will print all requests to the console by default. When you are ready for the production build, set "Pushwoosh_LOG_LEVEL" string key in your Info.plist file to one of the following values, depending on how much you want to see:
NONE - No logs from SDK
ERROR - Only display errors in console
WARNING - Also display warnings
INFO - Add informational messages
DEBUG - Add debug information
VERBOSE - Everything SDK can print and more
1
<key>Pushwoosh_LOG_LEVEL</key>
2
<string>YOUR_LOG_LEVEL</string>
Copied!
Info.plist
pushwoosh-quickstart-ios/Info.plist at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
Deep linking
In your Info.plist file add URL types array with URL Identifier and URL Scheme.
In the example below the URL Scheme is com.pushwoosh and the URL Identifier is promotion.
In your App Delegate file (usually AppDelegate.m) add openURL delegate function as outlined in the example below. The example checks for the correct page, parses "id" value from the URL and opens PromoPageViewController in response.
Swift
Objective-C
1
func open(_ url: URL, options: [String : Any] = [:], completionHandler completion: ((Bool) -> Swift.Void)? = nil) {
2
        let components = URLComponents(url: url, resolvingAgainstBaseURL: false)
3
        let page = components?.host
4
        var promotionId: String?
5
        
6
        if page == "promotion" {
7
            return
8
        }
9
        
10
        let items = components?.queryItems ?? []
11
        
12
        for item in items {
13
            if item.name == "id" {
14
                promotionId = item.value
15
            }
16
        }
17
        
18
        //show PromoPageViewController
19
    }
Copied!
1
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
2
    NSURLComponents *components = [NSURLComponents componentsWithURL:url resolvingAgainstBaseURL:NO];
3
    NSString *page = components.host;
4
    NSString *promotionId = nil;
5
  
6
    //return if this is not a promotion deep link
7
    if(![page isEqualToString:@"promotion"])
8
        return NO;
9
​
10
    for(NSURLQueryItem *item in components.queryItems)
11
    {
12
        if([item.name isEqualToString:@"id"])
13
            promotionId = item.value;
14
    }
15
  
16
    PromoPageViewController *vc = [[PromoPageViewController alloc] init];
17
    vc.promotionId = promotionId
18
    [self presentViewController:vc animated:YES completion:nil];
19
}
Copied!
In-Apps Tracking
In paymentQueue:updatedTransactions: delegate method call sendSKPaymentTransactions method of PushManager
Swift
Objective-C
1
 func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) {
2
     // In-Apps Tracking Pushwoosh code here
3
     Pushwoosh.sharedInstance().sendSKPaymentTransactions(transactions)
4
     // the rest of the code, consume transactions, etc
5
 }
Copied!
1
- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions {
2
  
3
  [[PushNotificationManager pushManager] sendSKPaymentTransactions:transactions];
4
  
5
  //the rest of the code, consume transactions, etc
6
}
Copied!
InAppTrackingViewController.swift
pushwoosh-quickstart-ios/InAppTrackingViewController.swift at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
Geozones push notifications
Gezones push notifications are encapsulated into a separate framework PushwooshGeozones.
1. To add PushwooshGeozones.framework to your project using a dependency manager, put the following lines in your podfile or cartfile:
Podfile
Carfile
SwiftPM
1
pod 'PushwooshXCFramework/Geozones'
Copied!
1
github "Pushwoosh/pushwoosh-ios-sdk"
Copied!
If you want to use PushwooshGeozones.xcframework, enter the following Package URL:
​https://github.com/Pushwoosh/PushwooshGeozones-XCFramework​
Also, you can simply drag and drop the framework into Link Binaries With Libraries in your project's Build Phases.
2. Add the following keys to your Info.plist:
NSLocationWhenInUseUsageDescription – (required) for app to track Geozones only while running in the foreground.
NSLocationAlwaysAndWhenInUseUsageDescription - (required) for app to track Geozones in both conditions and to show a permission request dialog pop-up.
NSLocationAlwaysUsageDescription – (optional) for app to track Geozones at all times; should be used if your app targets iOS 10 and earlier versions.
1
<ke><key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
2
<string>for app to track Geozones in both conditions and to show a permission request dialog pop-up</string>
3
<key>NSLocationWhenInUseUsageDescription</key>
4
<string>for app to track Geozones only while running in the foreground</string>
Copied!
Info.plist
pushwoosh-quickstart-ios/Info.plist at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
3. Import the framework:
Swift
Objective-C
1
import PushwooshGeozones
Copied!
1
#import <PushwooshGeozones/PWGeozonesManager.h>
Copied!
4. Start Geozones tracking when needed:
GitHub Swift Code
GitHub Objective-C Code
1
PWGeozonesManager.shared()?.startLocationTracking()
Copied!
pushwoosh-quickstart-ios/GeozonesViewController.swift at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
1
[[PWGeozonesManager sharedManager] startLocationTracking];
Copied!
pushwoosh-quickstart-ios/PWGeozonesViewController.m at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
Swift Example
Objective-C example
Example
Example
Creating a Rich Media queue
In case there are several Rich Media pages to display simultaneously (for example, trigger events for two or more In-Apps take place at one moment, or a Rich Media page is being displayed already at the moment a different trigger event occurs), you can set up a queue for Rich Media pages displaying. To create a queue, follow the steps described below.
1.Create a class which implements PWRichMediaPresentingDelegate:
1
@interface ChainedRichMediaPresentingDelegate () <PWRichMediaPresentingDelegate>
2
​
3
@property (nonatomic) NSMutableArray *queue;
4
​
5
@property (nonatomic) BOOL inAppIsPresenting;
6
​
7
@end
8
​
9
​
10
@implementation ChainedRichMediaPresentingDelegate
11
​
12
- (instancetype)init {
13
    self = [super init];
14
    
15
    if (self) {
16
        _queue = [NSMutableArray new];
17
    }
18
    
19
    return self;
20
}
21
​
22
- (BOOL)richMediaManager:(PWRichMediaManager *)richMediaManager shouldPresentRichMedia:(PWRichMedia *)richMedia {
23
    [_queue addObject:richMedia];
24
    return !_inAppIsPresenting;
25
}
26
​
27
- (void)richMediaManager:(PWRichMediaManager *)richMediaManager didPresentRichMedia:(PWRichMedia *)richMedia {
28
    _inAppIsPresenting = YES;
29
}
30
​
31
- (void)richMediaManager:(PWRichMediaManager *)richMediaManager didCloseRichMedia:(PWRichMedia *)richMedia {
32
    _inAppIsPresenting = NO;
33
    
34
    [_queue removeObject:richMedia];
35
    
36
    if (_queue.count) {
37
        [[PWRichMediaManager sharedManager] presentRichMedia:_queue.firstObject];
38
    }
39
}
40
​
41
- (void)richMediaManager:(PWRichMediaManager *)richMediaManager presentingDidFailForRichMedia:(PWRichMedia *)richMedia withError:(NSError *)error {
42
    [self richMediaManager:richMediaManager didCloseRichMedia:richMedia];
43
}
44
​
45
@end
Copied!
2. Set the delegate:
1
 [PWRichMediaManager sharedManager].delegate = [ChainedRichMediaPresentingDelegate new];
Copied!
Swift (GitHub) 
Objective-C (GitHub)
pushwoosh-quickstart-ios/customizing/customizing/Rich Media Queue at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
pushwoosh-quickstart-ios/customizing/customizingObjC/customizingObjC/Rich Media Queue at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
Custom UNNotificationCenterDelegate
If you want to use your own UNNotificationCenterDelegate (for example, for local notifications), you should inform Pushwoosh SDK about it for proper behavior. You can do it with the notificationCenterDelegateProxy property of Pushwoosh instance:
Swift
Objective-C
1
Pushwoosh.sharedInstance()?.notificationCenterDelegateProxy.add(my_delegate)
Copied!
pushwoosh-quickstart-ios/CustomNotificationCDViewConrtoller.swift at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
1
[Pushwoosh.sharedInstance.notificationCenterDelegateProxy addNotificationCenterDelegate:my_delegate];
Copied!
pushwoosh-quickstart-ios/PWCustomNotificationCDViewConrtoller.m at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
Then, implement UNNotificationCenterDelegate methods in your delegate:
Swift
Objective-C
1
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
2
    if (!PWMessage.isPushwooshMessage(notification.request.content.userInfo)) {
3
        // handle your notification
4
        completionHandler(UNNotificationPresentationOptions.alert)
5
    }
6
}
7
​
8
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
9
    if (!PWMessage.isPushwooshMessage(response.notification.request.content.userInfo)) {
10
        // handle your notification
11
        completionHandler()
12
    }
13
}
Copied!
pushwoosh-quickstart-ios/CustomNotificationCDViewConrtoller.swift at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
1
- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
2
    if (![PWMessage isPushwooshMessage:notification.request.content.userInfo]) {
3
        //handle your message
4
        completionHandler(UNNotificationPresentationOptionAlert);
5
    }
6
}
7
​
8
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)(void))completionHandler {
9
    if (![PWMessage isPushwooshMessage:response.notification.request.content.userInfo]) {
10
        //handle your message
11
        completionHandler();
12
    }
13
}
Copied!
pushwoosh-quickstart-ios/PWCustomNotificationCDViewConrtoller.m at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
Custom push sound
To play a custom sound when on a push notification receiving, first put the audio file into your project's root folder. For example, here's the Pushwoosh sample app with the sound files included: https://github.com/Pushwoosh/pushwoosh-ios-sdk/tree/master/Samples/iPhone​
Then, specify the sound file's name in push parameters – fill in the Sound field of the iOS-specific settings of your message or specify the file name as a value for the "ios_sound" param of the createMessage API request. 
Audio file for custom iOS sound has to be in one of the following formats: .aif, .caf, .wav. Make sure to specify the format in the file's name; otherwise, it will be ignored by Pushwoosh iOS SDK. 
Consider App Store limitations on bundle size when adding the sound file to your bundle.
Complete list of iOS SDK Info.plist properties
Property
Description
Possible values
Pushwoosh_APPID
Sets the Pushwoosh application ID for production build
XXXXX-XXXXX
Type: String
Pushwoosh_APPID_Dev
Sets the Pushwoosh application ID for development build
XXXXX-XXXXX
Type: String
Pushwoosh_SHOW_ALERT
Shows notification foreground alert
YES (default) / NO
Type: Boolean
Pushwoosh_ALERT_TYPE
Sets the notification alert style 
BANNER (default) / ALERT / NONE
Type: String
Pushwoosh_BASEURL
Overrides the Pushwoosh server base url
​https://cp.pushwoosh.com/json/1.3/ (default)
Type: String
Pushwoosh_AUTO_ACCEPT_DEEP_LINK_FOR_SILENT_PUSH
If YES, Deep Links received in silent pushes will be processed automatically
YES (default) / NO
Type: Boolean
Pushwoosh_ALLOW_SERVER_COMMUNICATION
Allows the SDK to send network requests to Pushwoosh servers
YES (default) / NO
Type: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_DATA
Allows the SDK to collect and to send device data (OS version, jailbreak status, locale, model, connection type and sim operator) to the server
YES (default) / NO
Type: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_OS_VERSION
Allows the SDK to collect and to send device OS version to the server
YES (default) / NO
Type: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_JAILBREAK_STATUS
Allows the SDK to collect and to send device jailbreak status to the server
YES (default) / NO
Type: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_LOCALE
Allows the SDK to collect and to send device locale to the server
YES (default) / NO
Type: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_MODEL
Allows the SDK to collect and to send device model to the server
YES (default) / NO
Type: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_CONNECTION_TYPE
Allows the SDK to collect and to send device connection type to the server
YES (default) / NO
Type: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_SIM_OPERATOR
Allows the SDK to collect and to send device sim operator to the server
YES (default) / NO
Type: Boolean
Pushwoosh_LOG_LEVEL
Pushwoosh SDK logging level. For details, refer to Controlling Log Level ​
NONE / ERROR / WARNING / INFO / DEBUG (default) / VERBOSE
Type: String
Pushwoosh_PURCHASE_TRACKING_ENABLED
Allows the SDK to track in-app purchases. Needed for Customer Journey Builder. 
YES (default) / NO
Type: Boolean
iOS Provisional Push
Supported on iOS 12 and later.
How it works 
Provisional push notifications appear silently in the user’s Notification Center but not on the lock screen. This type of pushes doesn’t need to be allowed by a user explicitly: you can start sending them as soon as a user installs and launches your app.
However, users still can subscribe to your prominent push notifications: when opening the Provisional Push, they have two options to choose their experience – to keep pushes in Notification Center without alerts and sounds or allow you to send pushes prominently so that they appear on the lock screen.
Provisional Pushes are designed to let users make informed decisions about whether they’d like to receive notifications from your app. As the APN native subscription request is shown to users only once and to subscribe later, they should go to their phone’s system settings, and some users might not subscribe since they aren’t aware of what value they get with your pushes. Provisional Pushes give users this understanding: they can see what content you deliver in push notifications and decide whether they need to be notified about this content prominently.
Important!
Please note that Provisional Pushes, when implemented, replace the native APN prompt, which means users cannot subscribe to prominent notifications until they open their Notification Center and choose to receive Provisional Pushes as prominent ones.
How to implement 
1. Integrate the Pushwoosh iOS SDK by following the guide.
2. Add the following string to your project's AppDelegate before calling the registerForPushNotifications() method:
Swift
Objective-C
1
if #available(iOS 12.0, *) {
2
    Pushwoosh.sharedInstance().additionalAuthorizationOptions = UNAuthorizationOptions.provisional
3
}
Copied!
pushwoosh-quickstart-ios/AppDelegate.swift at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
1
if (@available(iOS 12.0, *)) {
2
	[Pushwoosh sharedInstance].additionalAuthorizationOptions = UNAuthorizationOptionProvisional;
3
}
Copied!
pushwoosh-quickstart-ios/AppDelegate.m at main · Pushwoosh/pushwoosh-quickstart-ios
GitHub
That's it! App users will receive messages directly to their Notification Center once they install the app.
Share your feedback with us
Your feedback helps us create a better experience, so we would love to hear from you if you have any issues during the SDK integration process. If you face any difficulties, please do not hesitate to share your thoughts with us via this form.