Capacitor Plugin Setup

Requirements

iOS:

• capacitor >= 5.0.0
• Requires Xcode 15.2+
• Minimum iOS version supported 14+
• To use notifications:
  • iOS APNs setup instructions

Android:

• capacitor >= 5.0.0
• Minimum Android version supported 21+
• Compile SDK version and Target SDK version 34+
• To use notifications, see Android Setup below.

Setup

Install the plugin

npm install @ua/capacitor-airship
npx cap sync

iOS Setup

Use Xcode to enable push notifications in the target’s Signing & Capabilities pane:

1. Open your project in Xcode.

2. Click on your project in the Project Navigator.

3. Select your main app target and then click the Signing & Capabilities tab.

4. If you do not see Push Notifications enabled, click + Capability and add Push Notifications.

   

Next enable background notifications in the target’s Signing & Capabilities pane:

1. Select your main app target and then click the Signing & Capabilities tab.

2. Click + Capability and add Background Modes.

   

3. In the Background Modes section, select the Remote notifications checkbox.

   

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 .

Android Setup

Complete the setup steps for your provider:

• FCM: Follow the Android FCM setup instructions.
• HMS:
  1. Follow Huawei’s documentation  to set up the HMS SDK.
      Note

     Airship requires HMS Core Push SDK 6.3.0.304 or newer.

  2. Add airshipHmsEnabled=true to the app’s gradle.properties.

Initialize Airship

Before you can access any of the module’s API, the Airship module needs to be initialized.

This can be accomplished by calling takeOff when the device is ready with the proper config or by providing plugin config in the capacitor.config.json file.

// TakeOff
await Airship.takeOff({
  production: {
    appKey: "<APP_KEY>",
    appSecret: "<APP_SECRET>"
  },
  development: {
    appKey: "<APP_KEY>",
    appSecret: "<APP_SECRET>"
  },
  inProduction: true, 
  site: "us", // use "eu" for EU cloud projects
  urlAllowList: ["*"],
  android: {
      notificationConfig: {
          icon: "ic_notification",
          accentColor: "#00ff00"
      }
  }
})

{
   "appId":"com.example.plugin",
   "appName":"example",
   "bundledWebRuntime":false,
   "webDir":"dist",
   "plugins":{
      "SplashScreen":{
         "launchShowDuration":0
      },
      "Airship":{
         "config":{
            "default":{
               "appKey":"<APP_KEY>",
               "appSecret":"<APP_SECRET>"
            },
            "site":"us",
            "urlAllowList":[
               "*"
            ],
            "android":{
               "notificationConfig":{
                  "icon":"ic_notification",
                  "accentColor":"#00ff00"
               }
            }
         }
      }
   },
   "server":{
      "androidScheme":"https"
   }
}
}

Takeoff can be called multiple times, but the config passed in takeOff won’t be applied until the next app init.

URL Allowlist

The URL allowlist controls which URLs the Airship SDK is able to act on. The SDK divides up usages of URLs into three different config options:

• urlAllowListScopeOpenUrl: 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.
• urlAllowListScopeJavaScriptInterface: These URLs are checked before the Airship JavaScript interface is injected into the webview. Defaults to any Airship-originated URLs
• urlAllowList: Both scopes are applied to these URLs.

<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>

To accept any URL within the SDK, set the urlAllowList to ["*"].

Extending Airship

To access the underlying native SDK when Airship is ready, you can provide a plugin extender that will be automatically loaded for the app. This gives the app a chance to customize parts of Airship that are not configurable through the Capacitor plugin, and gives a place to setup iOS Live Activities and Android Live Updates

iOS

For iOS, create a Swift file named AirshipPluginExtender.swift and needs to be included in the main app target. Make sure the class has the @objc(AirshipPluginExtender) annotation and inherits AirshipPluginExtenderProtocol.

import Foundation
import AirshipKit
import AirshipFrameworkProxy
import ActivityKit

@objc(AirshipPluginExtender)
public class AirshipPluginExtender: NSObject, AirshipPluginExtenderProtocol {
  
  public static func onAirshipReady() {
   // Called when Airship is ready on the MainActor
  }

}

Android

Create a file in the App’s src directory named AirshipExtender. It needs to extend com.urbanairship.android.framework.proxy.AirshipPluginExtender and have an empty constructor.

// Replace with your package
package com.example

import android.content.Context
import androidx.annotation.Keep
import com.urbanairship.UAirship
import com.urbanairship.android.framework.proxy.AirshipPluginExtender

@Keep
public final class AirshipExtender: AirshipPluginExtender {

    override fun onAirshipReady(context: Context, airship: UAirship) {
        // Called when Airship is ready on a background thread. 
        // Avoid doing long running, blocking work or it will delay Airship
    }

}

Register the extender in the manifest:

<application ...>

    <meta-data android:name="com.urbanairship.plugin.extender"
        android:value="com.example.AirshipExtender" />

    <!-- ... -->
</application>

Implementation best practices

Make sure to set up logging. Internal logging can be valuable when troubleshooting issues that arise when testing.

Anytime you make any changes or updates to the SDK, test on a development device to ensure your integration was successful. Also make sure analytic information is still flowing to your Airship project before sending the app to production.