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 33+
• To use notifications:
  • Android FCM setup instructions

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 .

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 ["*"].

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.