iOS Urban Airship SDK

The Urban Airship SDK for iOS provides a simple way to integrate Urban Airship services into your iOS applications.

Contributing Code

We accept pull requests! If you would like to submit a pull request, please fill out and submit our Contributor License Agreement.

One of our engineers will verify receipt of the agreement before approving your pull request.

Resources

• AirshipKit Docs
• AirshipAppExtensions Docs
• Getting started guide
• Migration Guides
• Sample Quickstart Guide
• Swift Sample Quickstart Guide

Installation

Xcode 10.0+ is required for all projects and the static library. Projects must target >= iOS 10.

CocoaPods

Make sure you have the CocoaPods dependency manager installed. You can do so by executing the following command:

$ gem install cocoapods

Specify the UrbanAirship-iOS-SDK in your podfile with the use_frameworks! option:

use_frameworks!

# Urban Airship SDK
target "<Your Target Name>" do
  pod 'UrbanAirship-iOS-SDK'
end

Install using the following command:

$ pod install

In order to take advantage of iOS 10 notification attachments, you will need to create a notification service extension alongside your main application. Most of the work is already done for you, but since this involves creating a new target there are a few additional steps. First create a new "Notification Service Extension" target. Then add the UrbanAirship-iOS-AppExtensions to the new target:

use_frameworks!

# Urban Airship SDK
target "<Your Service Extension Target Name>" do
  pod 'UrbanAirship-iOS-AppExtensions'
end

Install using the following command:

$ pod install

Then delete all the dummy source code for the new extension and have it inherit from UAMediaAttachmentExtension:

import AirshipAppExtensions

class NotificationService: UAMediaAttachmentExtension {

}

Carthage

Make sure you have Carthage installed. Carthage can be installed using Homebrew with the following commands:

$ brew update
$ brew install carthage

Specify the Urban Airship iOS SDK in your cartfile:

github "urbanairship/ios-library"

Execute the following command in the same directory as the cartfile:

$ carthage update

In order to take advantage of iOS 10 notification attachments, you will need to create a notification service extension alongside your main application. Most of the work is already done for you, but since this involves creating a new target there are a few additional steps:

• Create a new iOS target in Xcode and select the "Notification Service Extension" type
• Drag the new AirshipAppExtensions.framework into your app project
• Link against AirshipAppExtensions.framework in your extension's Build Phases
• Add a Copy Files phase for AirshipAppExtensions.framework and select "Frameworks" as the destination
• Delete all dummy source code for your new extension
• Inherit from UAMediaAttachmentExtension in NotificationService

Other Installation Methods

For other installation methods, please checkout - Getting started guide.

Quickstart

Capabilities

Enable Push Notifications and Remote Notifications Background mode under the capabilties section for the main application target.

Adding an Airship Config File

The library uses a .plist configuration file named AirshipConfig.plist to manage your production and development application profiles. Example copies of this file are available in all of the sample projects. Place this file in your project and set the following values to the ones in your application at http://go.urbanairship.com. To view all the possible keys and values, see the UAConfig class reference

You can also edit the file as plain-text:

    <?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>detectProvisioningMode</key>
      <true/>
      <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>

The library will auto-detect the production mode when setting detectProvisioningMode to true.

Advanced users may add scripting or preprocessing logic to this .plist file to automate the switch from development to production keys based on the build type.

Call Takeoff

To enable push notifications, you will need to make several additions to your application delegate.

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

        // Your other application code.....

        // Set log level for debugging config loading (optional)
        // It will be set to the value in the loaded config upon takeOff
        [UAirship setLogLevel:UALogLevelTrace];

        // Populate AirshipConfig.plist with your app's info from https://go.urbanairship.com
        // or set runtime properties here.
        UAConfig *config = [UAConfig defaultConfig];

        // You can then programmatically override the plist values:
        // config.developmentAppKey = @"YourKey";
        // etc.

        // Call takeOff (which creates the UAirship singleton)
        [UAirship takeOff:config];

        // Print out the application configuration for debugging (optional)
        UA_LDEBUG(@"Config:\n%@", [config description]);

        // Set the icon badge to zero on startup (optional)
        [[UAirship push] resetBadge];

        // User notifications will not be enabled until userPushNotificationsEnabled is
        // set YES on UAPush. Once enabled, the setting will be persisted and the user
        // will be prompted to allow notifications. You should wait for a more appropriate
        // time to enable push to increase the likelihood that the user will accept
        // notifications.
        // [UAirship push].userPushNotificationsEnabled = YES;

        return YES;
    }

To enable push later on in your application:

    // Somewhere in the app, this will enable push (setting it to NO will disable push,
    // which will trigger the proper registration or de-registration code in the library).
    [UAirship push].userPushNotificationsEnabled = YES;

SDK Development

Make sure you have the CocoaPods dependency manager installed. You can do so by executing the following command:

$ gem install cocoapods

Install the pods:

$ pod install

Open Airship.xcworkspace

$ open Airship.xcworkspace

Update the Samples AirshipConfig by copyingAirshipConfig.plist.sample to AirshipConfig.plist and update the app's credentials. You should now be able to build, run tests, and run the samples.

The distribution can be generated by running the build.sh script:

./scripts/build.sh

Jenkins will run run_ci_tasks.sh for every PR submitted. Jenkin's Xcode version can be set by updating jenkins-enviornment.properties file.

Third Party Packages

Core Library

Test Code