Cordova Plugin Setup

Requirements

iOS:

• cordova-ios >= 7.0.0
• Requires Xcode 15.2+
• Minimum iOS version supported 14+
• To use notifications:
  • iOS APNs setup instructions

Android:

• cordova-android >= 12.0.0
• Minimum Android version supported 21+
• Compile SDK version and Target SDK version 34+
• To use notifications:
  • Android FCM setup instructions
  • Huawei Mobile Services (HMS) setup instructions

Setup

Install the plugin using Cordova CLI:

cordova plugin add @ua/cordova-airship

For HMS support, you will also need the HMS module:

cordova plugin add @ua/cordova-airship-hms

iOS Setup

Modify the app’s config.xml to enable swift support and set the min iOS version:

<!-- Deployment target must be >= iOS 14  -->
<preference name="deployment-target" value="14.0" />

<!-- Must be 5.0 -->
<preference name="SwiftVersion" value="5.0" />

Signing

Add your Apple Developer Account Team ID to the build.json .

{
  "ios": {
    "debug": {
    "developmentTeam": "XXXXXXXXXX"
    },
    "release": {
      "developmentTeam": "XXXXXXXXXX"
    }
  }
}

Your iOS builds will need to reference the build.json using Cordova’s --buildConfig flag.

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

FCM

Add a reference to your google-services.json file in the app’s config.xml and enable Google Services plugin:

<preference name="AndroidGradlePluginGoogleServicesEnabled" value="true" />

<platform name="android">
    ...
    <resource-file src="google-services.json" target="app/google-services.json" />
</platform>

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.

// TakeOff
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"
      }
  }
})

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.