# SDK Installation

Complete installation and configuration guides for the Airship Cordova plugin.

<!-- PAGE: Install and Set Up the Cordova Plugin, PATH: https://www.airship.com/docs/developer/sdk-integration/cordova/installation/getting-started/ -->

# Install and Set Up the Cordova Plugin

> How to install the Airship Cordova plugin.## Requirements

- cordova-ios 8.0.0 or higher
- cordova-android 15.0.0 or higher
- iOS 16+ (Xcode 26+)
- Android API 23+


## Setup

Install the plugin using Cordova CLI:

```bash
cordova plugin add @ua/cordova-airship
```


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

```bash
cordova plugin add @ua/cordova-airship-hms
```


### iOS

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

```xml
<!-- Deployment target must be >= iOS 16  -->
<preference name="deployment-target" value="16.0" />

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


## 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](https://www.airship.com/docs/reference/libraries/urbanairship-cordova/latest/interfaces/Airship.html#takeOff) when the device is ready.

**Calling takeOff**


```javascript
// 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.

For a complete list of configuration options, see the [AirshipConfig reference](https://www.airship.com/docs/reference/libraries/urbanairship-cordova/latest/interfaces/AirshipConfig.html).

## Test the integration

After completing the setup, verify your integration:

1. **Build and run your app** on your iOS or Android device/simulator/emulator.
2. **Check the console output** for Airship channel creation:
   - **iOS**: Look for a log message in Xcode console: `Channel ID: <CHANNEL_ID>`
   - **Android**: Look for a log message in logcat: `Airship channel created: <CHANNEL_ID>`
   - The channel ID confirms successful SDK initialization.
   - For more detailed logging, see [Logging](https://www.airship.com/docs/developer/sdk-integration/cordova/installation/logging/).

If you see the channel ID in the console and no errors, your integration is successful.

## Next steps

- [Advanced Configuration](https://www.airship.com/docs/developer/sdk-integration/cordova/installation/advanced-configuration/): Configure URL allowlists and other advanced settings
- [Push Notifications](https://www.airship.com/docs/developer/sdk-integration/cordova/push-notifications/getting-started/): Configure push notifications
- [Deep Links](https://www.airship.com/docs/developer/sdk-integration/cordova/deep-links/): Handle deep links in your app

If you don't see a channel ID or encounter errors during initialization, see [Troubleshooting Initialization](https://www.airship.com/docs/developer/sdk-integration/cordova/troubleshooting/initialization/) for common problems and solutions.


<!-- /PAGE: Install and Set Up the Cordova Plugin -->

<!-- PAGE: Logging, PATH: https://www.airship.com/docs/developer/sdk-integration/cordova/installation/logging/ -->

# Logging

> Configure log levels and privacy settings to control how the Airship SDK logs messages.
The Airship SDK provides configurable log levels to help you debug issues without overwhelming the console. By default, the log level is set to **Info** for development builds and **Error** for production builds to ensure clean logs in a live environment.

## Log levels

The following log levels are available, ordered from most to least verbose.

| Log Level | Description |
| :-------- | :---------- |
| **Verbose** | Reports highly detailed SDK status, which is useful for deep debugging and troubleshooting. |
| **Debug** | Reports general SDK status with more detailed information than `Info`. |
| **Info** | Reports general SDK status and lifecycle events. |
| **Warning** | Used for API deprecations, invalid setup, and other potentially problematic situations that are generally recoverable. |
| **Error** | Used for critical errors, exceptions, and other situations that the SDK cannot gracefully handle. |
| **None** | Disables all logging. |

## Configuring log levels

You can set the log level in the Airship config options that are passed during takeOff. This setting acts as a minimum, and only logs at that level and higher will be logged.

```javascript
// Available log levels: verbose, debug, info, warning, none
Airship.takeOff({
  default: {
    logLevel: "verbose"
  },
  ...
});
```


## Log privacy levels

For better security in production environments, you can control the visibility of log contents using privacy levels. This is especially useful when you need to debug a release build without exposing sensitive information.

### private (default)

This is the default setting, designed to protect data in a production environment.

### public

This setting increases log visibility, making it easier to capture detailed information from release builds. To ensure visibility in production builds, `verbose` and `debug` messages are automatically elevated to the `info` log level.

## Setting the privacy level

You can set the privacy level in the Airship config options that are passed during takeOff.

```javascript
Airship.takeOff({
    default: {
        logLevel: "verbose",
        ios: {
          logPrivacyLevel: "public"
        },
        android: {
          logPrivacyLevel: "public"
        }
    },
    ...
});
```




<!-- /PAGE: Logging -->

<!-- PAGE: Locale, PATH: https://www.airship.com/docs/developer/sdk-integration/cordova/installation/locale/ -->

# Locale

> Configure locale behavior and override the default locale that Airship uses.
The Airship SDK is localized in 48 different languages for all strings included within the SDK. The strings within the app will automatically use the device's or app's configured [Locale](https://www.airship.com/docs/reference/glossary/#locale).

Airship uses the user's locale for various locale-sensitive tasks, including selecting the language for messages and reporting for analytics. Apps can override the locale so that Airship uses a different locale than the device's current locale for messaging.

## Overriding the locale

You can override the locale programmatically at runtime, which takes precedence over the device's locale settings.

```javascript
Airship.locale.setLocaleOverride("de")
```


## Clearing the locale override

To remove a locale override and return to using the device's locale:

```javascript
Airship.locale.clearLocaleOverride();
```


## Getting the current locale

To retrieve the locale that Airship is currently using:

```javascript
Airship.locale.getCurrentLocale((locale) => {
    console.log('Current locale: ', locale);
});
```




<!-- /PAGE: Locale -->

<!-- PAGE: Advanced Configuration, PATH: https://www.airship.com/docs/developer/sdk-integration/cordova/installation/advanced-configuration/ -->

# Advanced Configuration

> Configure advanced settings like URL allowlists and other options for the Airship Cordova plugin.
## URL Allowlist

The URL allowlist controls which URLs the Airship SDK is able to act on. Configure the URL allowlist in your `takeOff` config options using the following properties:

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

```javascript
Airship.takeOff({
  production: {
    appKey: "<APP_KEY>",
    appSecret: "<APP_SECRET>"
  },
  inProduction: true,
  site: "us",
  urlAllowList: ["*"],  // Accept all URLs
  // Or configure specific scopes:
  urlAllowListScopeOpenUrl: ["https://example.com/*", "https://*.youtube.com/*"],
  urlAllowListScopeJavaScriptInterface: ["https://example.com/*"]
})
```


**Valid URL pattern syntax**


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

For a complete list of configuration options, see the [AirshipConfig reference](https://www.airship.com/docs/reference/libraries/urbanairship-cordova/latest/interfaces/AirshipConfig.html).



<!-- /PAGE: Advanced Configuration -->