Getting Started
This is a developers' guide for setting up an Airship configuration for native iOS apps. We will take you through the basic technical steps for configuring Apple and UA services, show you how to send your first basic push notification and Message Center message, and provide detailed samples and instructions for using advanced Airship features.
Resources
- Airship Docs
- AirshipLocation Docs
- AirshipNotificationServiceExtensions Docs
- AirshipNotificationContentExtensions Docs
An Important Note about Location
As of Spring 2019, Apple has begun rejecting applications that use, or appear to use, Core Location services
without supplying usage descriptions in their Info.plist
files. In Airship SDK 11.0, all references to
CoreLocation were removed from the core library and placed in a separate location framework. Developers with
no need for location services can continue to use Airship as before, but for those who have been using the
UALocation
class, see the Location sections for updated
setup instructions.
As of SDK 10.2 and Apple’s current App Store review policies, apps building against Airship without location usage
descriptions in Info.plist
are likely to be rejected. To avoid this, either use SDK 11.0 or newer, or add usage description
strings to your Info.plist
file under the NSLocationAlwaysUsageDescription
,
NSLocationWhenInUseUsageDescription
, and NSLocationAlwaysAndWhenInUseUsageDescription
keys.
Apple Setup
Before you can integrate Airship into your iOS apps, there are a handful of steps you must take on the Apple end of things, which requires membership in the iOS Developer Program.
We will be using the Apple Push Notification Service (APNs) as the transport method for iOS push notifications. In the next section we will configure a development app and a production app for push services.
Production vs. Development Apps
When you create or edit an Airship project (and thus its application record on our server), you must select whether your app system is Test (development for sending test messages), or Live (production for sending messages to customers). We suggest making two projects in the Airship dashboard, so that you can continue to build and develop your application even after releasing it, without interrupting your users.
Do not a) submit to the App Store or b) test notifications on an ad hoc build while your app’s code is pointing to an Airship app key that is set as Test. Test apps use different tokens that, when included in a push to a Live app, will fail and in many cases cause all other pushes to fail.
Always create a Live Airship project first, and make sure your application code is pointing to the live project’s app key. For more tips on what to check before you release your app, see the iOS Production Launch Checklist.
Register Your Authentication Signing Key
We recommend that new applications use token signing for authentication, described below. For instructions on setting up certificate-based authentication, see iOS Push Certificate Authentication.
Log in to the Apple Developer Member Center.
Go to Account » Membership and copy your Team ID. You’ll need this ID when you configure the APNs service in Airship later.
In the left side menu, go to Certificates, IDs & Profiles » Identifiers, and click your app’s name in the list of App IDs.
Note your Bundle ID and check the box for Push Notifications, then click Save. If Push Notifications was already enabled, click All Identifiers at the top of the page to go back.
In the left side menu, click Keys.
Click + to register a new key, then enter a unique key name and enable Apple Push Notifications service (APNs). Click Continue.
Click Register to finish registering your key.
On the following screen, note your Key ID and Click Download to save the key in .p8 format.
Important Be sure to save your key in a secure location if you intend to use it across multiple apps or Airship projects. Apple only allows two registered APNs keys per team, so reaching this limit would require you to revoke one of your existing keys before creating a new one, which in turn would require an update for any apps previously using the revoked key. Airship will not make your key available for download or sharing across projects once it has been uploaded.
Airship Steps
Configure your iOS project for push notifications in the Airship dashboard.
Configure the APNs Service
You will need your downloaded .p8 file and noted Team, Bundle, and Key IDs from the previous section.
Airship defaults to token-based authentication for APNs, but will fall back on certificates if token authentication is not configured. For existing projects, it is recommended that you leave your certificate in place when migrating to token-based authentication so that push can be quickly restored if there are any issues during that process. Also, if you remove your certificate before setting up token-based authentication, you may have a period when you cannot send messages.
After confirming token-based authentication is working, you can let the certificate expire, or revoke the certificate from the Apple Developer Member Center.
- Go to Settings » Channels » Mobile App and click Add for iOS.
- Select Token-based authentication, then upload the .p8 file and enter your Team, Bundle, and Key IDs.
- Click Add iOS.
Your authentication signing key is now uploaded and ready for use. In the next section we will configure the Airship iOS SDK.
SDK Installation
The Airship SDK can be installed using CocoaPods, Swift Package Manager, Carthage, or manually. Pick the option that makes the most sense for your project.
CocoaPods
Before you begin, ensure that you have CocoaPods installed. If you are having troubles with CocoaPods, check out the troubleshooting guide.
$ gem install cocoapods
Update the podfile
The primary Airship pod includes the standard feature set and is advisable to use for most use cases. The standard feature set includes:
Core
: Push messaging features including channels, tags, named user and default actionsMessageCenter
: Message centerAutomation
: Automation and in-app messagingExtendedActions
: Extended action functionality including the rate app action
The primary Airship pod includes the subspecs Airship/Core, Airship/MessageCenter, Airship/ExtendedActions and Airship/Automation - making it unnecessary to explicitly include these when using the primary pod.
Example podfile:
use_frameworks!
# Airship SDK
target "<Your Target Name>" do
pod 'Airship'
# Optional: uncomment to install the location subspec
# pod 'Airship/Location'
end
The Airship
pod also contains several subspecs that can be installed
independently and in combination with one another when only a particular
selection of functionality is desired:
Airship/Core
: Push messaging features including channels, tags, named user and default actionsAirship/MessageCenter
: Message centerAirship/Automation
: Automation and in-app messagingAirship/ExtendedActions
: Extended actionsAirship/Location
: Location including geofencing and beacons
The Airship/Location
subspec is not compatible with the primary Airship
pod. When using the Airship/Location
subspec, it is necessary to use the appropriate subspecs, i.e. Airship/Core
, Airship/MessageCenter
, Airship/Automation
and/or Airship/ExtendedActions
instead of using the primary Airship
pod.
Example podfile:
use_frameworks!
target "<Your Target Name>" do
pod 'Airship/Core'
pod 'Airship/MessageCenter'
pod 'Airship/Automation'
pod 'Airship/ExtendedActions'
# Optional: uncomment to install the location subspec
# pod 'Airship/Location'
end
Explicitly specify the tvOS platform in your podfile when targeting tvOS. Cocoapods automatic platform selection can also be used if the platform must be left unspecified.
When targeting tvOS - specify the platform in your podfile:
platform :tvos, '11.0'
Install the pods
$ pod install
After running pod install, an Xcode workspace (extension .xcworkspace
) will be generated.
Make sure to always open it instead of the project file (extension .xcodeproj
)
when building your projects.
Swift Package Manager
In your Xcode project, go to the Swift Packages
tab of the project settings.

Add a new package by providing the Airship package repository.

Choose the versioning rule that suits best your project.

Choose Airship modules that you want to include in your app.

Advanced Installation
Notification Service Extension
To take advantage of notification attachments, such as images, animated gifs, and video, you will need to create a notification service extension.
Create a new iOS target in Xcode
In Xcode, click the File menu, select New » Target…, then click the Notification Service Extension template.
Typically extensions are named with a suffix on the main application’s ID. In
this example the bundle identifier would be
com.urbanairship.sample.ExampleServiceExtension
.
Check that your app’s target Embed App Extensions contains your newly created
extension.
Install Airship Notification Service Extension Dependencies
CocoaPods
Service extensions depend on the NotificationService subspec of the AirshipExtensions pod.
Example podfile:
target "<Your Service Extension Target Name>" do
pod 'AirshipExtensions/NotificationService'
end
Install using the following command:
$ pod install
Carthage
Before you begin, ensure you have Carthage installed.
Adding the SDK framework to your application
Follow Carthage’s adding frameworks to an application instructions to add AirshipNotificationServiceExtension.framework to your service extension target.
If you are also using the Airship SDK, follow the instructions in the iOS SDK Guide.
Specify the Airship iOS SDK in your cartfile:
github "urbanairship/ios-library"
Verify Enable Modules
and Link Frameworks Automatically
are enabled in the project’s Build Settings.
Manual
Follow the same manual process to install AirshipNotificationServiceExtension.xcframework using the same method that you followed to install Airship.xcframework, except add AirshipNotificationServiceExtension.framework to your service extension target.
Modify the Service Extension
CocoaPods
Extension:
// Notification.swift
import AirshipExtensions
class NotificationService: UANotificationServiceExtension {
}
// NotificationService.h
@import AirshipExtensions;
@interface NotificationService : UANotificationServiceExtension
@end
// NotificationService.m
@import Foundation;
import "NotificationService.h"
@implementation NotificationService
@end
Carthage and Manual
Extension:
// Notification.swift
import AirshipNotificationServiceExtension
class NotificationService: UANotificationServiceExtension {
}
// NotificationService.h
@import AirshipNotificationServiceExtension;
@interface NotificationService : UANotificationServiceExtension
@end
// NotificationService.m
@import Foundation;
import "NotificationService.h"
@implementation NotificationService
@end
Delete all dummy source code for your new extension and inherit from UANotificationServiceExtension in NotificationService.
Notification Content Extension
To provide a custom interface when a user previews your notification in the notification center, you will need to create a notification content extension by following the instructions in the content extension guide.
App Clips
To add an App Clip to your application, you will need to create a new target in your project by following the instructions in The App Clips guide.
Update the Target’s Capabilities
Use Xcode to enable push notifications in the target’s Capabilities
pane:

Enable background notifications by including the
UIBackgroundModes
key with the remote-notification
value in your app’s
Info.plist
file. When viewing the plist in Xcode, UIBackgroundModes
is
displayed as Required background modes
and remote-notification
is
displayed as App downloads content in response to push notifications
.

You can also enable Background Modes
and Remote notifications
under the target’s
Capabilities
section:

Create Airship Config Options
Create a plist
AirshipConfig.plist
and include it in your application’s target.
The default config will be loaded from the AirshipConfig.plist
file if its included
in the application target.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>developmentAppKey</key>
<string>Your Development App Key</string>
<key>developmentAppSecret</key>
<string>Your Development App Secret</string>
<key>productionAppKey</key>
<string>Your Production App Key</string>
<key>productionAppSecret</key>
<string>Your Production App Secret</string>
</dict>
</plist>
EU Cloud Site
If your app uses Airship’s EU cloud site, you will need to add that to AirshipConfig.plist
.
<key>site</key>
<string>EU</string>
TakeOff
The Airship SDK requires only a single entry point in the app
delegate, known as takeOff. Inside your application delegate’s
application:didFinishLaunchingWithOptions:
method, initialize a
shared UAirship instance by calling UAirship takeOff
.
This will bootstrap the SDK and look for settings specified in the
AirshipConfig.plist
config file.
import Airship
...
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
...
UAirship.takeOff(config)
return true
}
@import Airship;
...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
[UAirship takeOff];
return YES;
}
TakeOff must be called on the main thread and before application:didFinishLaunchingWithOptions:
returns.
Send Your First Push Notification
Remote notifications are only available on a real device. You will not be able to send any notifications through APNs on a simulator.
At this point in the guide, if you followed all the steps above you should be ready to send a test push notification to verify everything is set up properly.
Before sending a push, you must enable user notifications. The SDK does not
enable user notifications by default in order to avoid prompting the user
for permissions before your app is ready to do so. But for a testing purposes,
you can enable user notifications in the app delegate immediately after
takeOff
. You may also want to set default foreground presentation options
to display the notification in the foreground. For more information on
customizing push notifications or receiving callbacks, see
Push Notifications.
UAirship.push().userPushNotificationsEnabled = true
UAirship.push().defaultPresentationOptions = [.alert, .badge, .sound]
[UAirship push].userPushNotificationsEnabled = YES;
[UAirship push].defaultPresentationOptions = (UNNotificationPresentationOptionAlert |
UNNotificationPresentationOptionBadge |
UNNotificationPresentationOptionSound);
See Send Your First Message or our API reference for details on sending the first notification.
URL Allow List
As of SDK 14.0, open URL scoped URLs are now always verified.
The UAURLAllowList controls which URLs the Airship SDK is able to act on. The SDK divides up usages of URLs into two different scopes:
UAURLAllowListScopeOpenURL
: Only URLs allowed for this scope can be opened from an action, displayed in landing page, displayed in an HTML in-app message, or displayed as media in an In-App Automation. Defaults to any Airship-originated URLs and YouTube URLs.UAURLAllowListScopeJavaScriptInterface
: These URLs are checked before the Airship JavaScript interface is injected into the webview. Defaults to any Airship-originated URLs.
The easiest way to expand the list of allowed URLs is to provide a list of URL patterns in the AirshipConfig.plist
.
<key>URLAllowListScopeOpenUrl</key>
<array>
<string>https://*.mydomain.com</string>
</array>
<key>URLAllowListScopeJavaScriptInterface</key>
<array>
<string>https://*.mydomain.com</string>
</array>
<key>URLAllowList</key>
<array>
<string>https://*.mydomain.com</string>
</array>
<pattern> := '*' | <scheme>'://'<host>/<path> | <scheme>'://'<host> | <scheme>':/'<path> | <scheme>':///'<path>
<scheme> := <any char combination, '*' are treated as wild cards>
<host> := '*' | '*.'<any char combination except '/' and '*'> | <any char combination except '/' and '*'>
<path> := <any char combination, '*' are treated as wild cards>
Deep Linking
Deep linking is a technique that allows an app to be opened to a specific UI or resource, in response to some external event. By implementing a deep linking strategy, your app becomes more responsive and capable of navigation to arbitrary content in response to push notifications, much in the same way that URLs can link you to specific pages on the Web.
With the Actions Framework, the Airship SDK now supports opening deep links from push notifications, and through Rich HTML content interactions. Because there is no one standard means of performing deep linking, this support only provides a consistent interface for triggering deep links. As an application developer, you still need to pick a deep linking strategy and perform some manual integration to be able to take advantage of this feature.
There are two common strategies for deep linking in iOS. For most applications,
implementing the UADeepLinkDelegate
will be the preferred strategy. This allows
complete control over URL processing and sidesteps the need to register a unique
URL scheme with the operating system. The alternative strategy is to register a unique
URL scheme with the operating system and handle URL processing in the App Delegate’s
openURL:
callback.
Implementing the Deep Link Delegate
Deep linking is most easily accomplished by implementing the deep link delegate’s
receivedDeepLink:completionHandler:
callback. This allow your app to process
the URL provided in a UADeepLinkAction
and use it to navigate to the desired
view within your app.
- (void)receivedDeepLink:(NSURL *_Nonnull)url completionHandler:(void (^_Nonnull)(void))completionHandler {
NSArray *pathComponents = url.pathComponents;
if ([pathComponents containsObject:ViewStoryboardID]) {
// Navigate to desired view
}
// Call completion handler
completionHandler();
}
func receivedDeepLink(_ url: URL, completionHandler: @escaping () -> ()) {
let pathComponents = url.pathComponents
if pathComponents.contains(ViewStoryboardID) {
// Navigate to desired view
}
// Call completion handler
completionHandler()
}
Categories