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

An Important Note about Location Permissions

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. The Airship SDK contains lightweight wrappers around Core Location APIs, but does not collect location data by default unless foreground or background locationn is explicitly enabled in UALocationManager. However, since Apple appears to be using static analysis to detect any references of Core Location APIs in submitted app bundles, including AirshipKit can result in your app being flagged as using location APIs. To avoid this, add usage description strings to your Info.plist file under the NSLocationAlwaysUsageDescription, NSLocationWhenInUseUsageDescription, and NSLocationAlwaysAndWhenInUseUsageDescription keys.

 Warning

As of SDK 10.2 and Apple's current App Store review policies, apps bulding against AirshipKit without location usage descriptions in Info.plist are likely to be rejected. While this is easy to fix by resubmitting with the required description strings, we strongly recommend doing this ahead of time to avoid unnecesary delay in the review process. Subsequent SDK releases will likely make significant changes to the way location is handled to avoid this in the future.

If your app does not use the location features of the SDK, these descriptions will not be visible to the user, and are simply an extra step required to satisfy Apple's submission requirements. On the other hand, if your app does use these features, see the Location setup instructions.

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 and 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). Apple treats the two servers separately, so a device token for test/sandbox will not work on live/distribution. Because of this, we suggest making two projects in the Airship dashboard. That way you can continue to build and develop your application even after releasing it, without interrupting your users.

When building your app using a development provisioning profile, set your Airship project to Test, and upload the development Push SSL certificate. To push to an app built with a distribution provisioning profile (either with a release build in Xcode, ad hoc distribution, or the iTunes App Store), use a project that is designated as Live, and upload the production Push SSL certificate.

 Warning

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.

Get Your Certificate

  1. Log in to the Apple Developer Member Center, and navigate to Account » Certificates, IDs & Profiles, or use this direct link.

  2. In the left side menu, click App IDs in the Identifiers section.
     Note

    If you have not already registered an iOS App ID, click the + button and fill out the form, making sure to check the Push Notifications checkbox, and click the Continue button. Then you can skip to step 4.

  3. Click your app's name from the list of App IDs. In the list of Application Services you will see two settings for Push Notifications, with yellow or green status icons.Click the Settings button to continue. The button will be labeled Edit if it has been configured previously.
     Note

    If the Settings/Edit button is not available, you may not be the team agent or an admin. The person who originally created the developer account is your team agent, and they will have to carry out the remaining steps in this section.

  4. Check the box to enable push notifications, then click the Create Certificate... button for either the Development or Production SSL Certificate.You should now see the Add iOS Certificate Assistant.

  5. Follow the instructions in the Add iOS Certificate Assistant, then click Continue.

    You can now use the newly-created Certificate Signing request to generate the APNs Push SSL certificate. The next step requires the Download button to be active. You may need to reload the page if it is not yet active.

  6. Click the Download button, and save the file for use in the remaining step.

Renewing Your Certificate

If you are renewing either your Test or Live Push SSL Certificate, follow the steps outlined above as if you were uploading the certificate for the first time. There is no need to revoke the previous certificate in order to make this change. There may be two production certificates at the same time, to allow you to continue using the old certificate while uploading the new one.

Export as a .p12 File

You're almost there. The final step before heading back over to the Airship application is to save your signing certificate as a .p12 file.

  1. Open the certificate you downloaded in the previous steps, which should open in the Keychain Access app. The certificate should be listed in My Certificates.
  2. Click the certificate in the list, then from the File menu, select Export Items....
     Note

    Be sure to select My Certificates under the Category menu on the lower left-hand side. If My Certificates is not highlighted, you will not be able to export the certificate as a .p12 file.

  3. Save the file in the Personal Information Exchange (.p12) format.You will be prompted to create a certificate password. Use this password in the next step: Configure the APNs Service.

Airship Steps

Configure your iOS project for push notifications in the Airship web portal.

Configure the APNs Service

 Warning

Never use the same push certificate across multiple Airship app keys. You should also never use the same bundle ID across multiple app keys in the same environment (development or production). Not following these instructions can result in rejected device tokens and APNs feedback processed by the wrong app key. If you need to have a third app key for ad hoc builds (which also use Distribution-type push certificates), the bundle ID should be changed so you can use a different certificate, for example: "com.yourcompany.app.adhoc".

These steps require the certificate and password you generated in the previous section.

  1. Open your project from the Airship dashboard, then navigate to Settings » Channels » Mobile App Platforms.

  2. Click Configure for iOS, enter the Certificate password, then Choose File and select the .p12 file exported in the completed Apple Steps.

  3. Click Save.

Your push certificate 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, 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

Specify the UrbanAirship-iOS-SDK pod in your podfile and make sure to specify the flag use_frameworks!

Example podfile:

use_frameworks! target "Your_Target_Name" do pod 'UrbanAirship-iOS-SDK' 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, '10.0'

Install the pods

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.

$ pod install

Advanced Installation

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.

Then in your project's Build Settings you must set the iOS Deployment Target to iOS 10+.

Install AirshipAppExtensions

CocoaPods

Specify the UrbanAirship-iOS-AppExtensions in your podfile and your newly created service extension as the target. Make sure to run pod install after modifying the podfile.

Example podfile:

target "SampleExtension" do pod 'UrbanAirship-iOS-AppExtensions' 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 AirshipAppExtensions.framework to your application.

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

Drag the AirshipAppExtensions.framework into your app project from iOS SDK.


Add AirshipAppExtensions to Target Dependencies in your project's Build Phases.


Add AirshipAppExtensions.framework to a Copy Files phase in your project's Build Phases. Ensure "Frameworks" is set as the destination.


Link against AirshipAppExtensions.framework in your extension's Build Phases.

Modify the Extension

Extension:

// Notification.swift

import AirshipAppExtensions

class NotificationService: UAMediaAttachmentExtension {

}
// NotificationService.h

@import AirshipAppExtensions;

@interface NotificationService : UAMediaAttachmentExtension

@end

// NotificationService.m

@import Foundation;
import "NotificationService.h"

@implementation NotificationService

@end

Delete all dummy source code for your new extension and inherit from UAMediaAttachmentExtension in NotificationService.

Update the Target's Capabilities

Use Xcode to enable push notifications in the target's Capabilities pane:

Enable background notifications that were introduced in iOS 7 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.

Example AirshipConfig.plist
<?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>
  <key>useWKWebView</key>
  <true/>
</dict>
</plist>

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.

Example app delegate changes
import AirshipKit

...

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    ...

    UAirship.takeOff(config)

    return true
}
@import AirshipKit;

...

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...

    [UAirship takeOff];

    return YES;
}
 Note

TakeOff must be called on the main thread and before application:didFinishLaunchingWithOptions: returns.

Send Your First Push Notification

 Note

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 on iOS 10. On older devices, make sure you background the app before sending the push. For more information on customizing push notifications or receiving callbacks, see Push Notifications.

Enable notifications for a quick test after calling takeOff
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.

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.

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()
}