React Native Setup

How to install the Airship React Native module.


  • React Native >= 0.60.0
  • React Native cli >= 2.0.1


  • Xcode 13+
  • minimum deployment target iOS 11+


  • minSdkVersion 21+
  • compileSdkVersion 31+
  • Gradle Plugin version 3.0.0+
  • Java 8


Standard React Native Setup

Install the plugin using yarn or npm:

yarn add urbanairship-react-native


  1. Compile and Target SDK Versions:

    Urban Airship now requires compileSdk version 31+ or higher.

    Please update the build.gradle file:

    android {
       compileSdkVersion 31
       defaultConfig {
             minSdkVersion 21
             targetSdkVersion 31
             // ...
  2. Java 8 Source Compatibility:

    Urban Airship now requires Java 8 language features across all SDK modules.

    Please update Android Gradle Plugin to version 3.0.0 or higher and change the source and target compatibility for each module that uses Airship SDKs:

    android {
       compileOptions {
          sourceCompatibility JavaVersion.VERSION_1_8
          targetCompatibility JavaVersion.VERSION_1_8

    Modules using Kotlin will also need to set the target version of the generated JVM bytecode:

    tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach  {
       kotlinOptions {
          jvmTarget = JavaVersion.VERSION_1_8
  3. Download the Android Firebase configuration file google-services.json from the application’s Firebase console into the root directory at android/app/google-services.json.

    If your react-native application does not have an associated app in the Firebase console, follow the FCM setup instructions to set one up.


  1. Install pods:

    $ pod install

  2. Open your app’s project in the generated .xcworkspace file, and add the following capabilities:

    • Push Notification
    • Background Modes > Remote Notifications
  3. To take advantage of notification attachments, such as images, animated gifs, and video, you will need to create a notification service extension.

    Follow the steps in the iOS Notification Service Extension Guide.

Expo Setup

Apps using Expo’s managed workflows can use the airship-expo-plugin to configure the project.

expo install airship-expo-plugin
yarn add urbanairship-react-native

Configure the plugin

Add the plugin to the app.json with the app’s config:

        "mode": "development"

Android Config:

  • icon: Local path to an image to use as the icon for push notifications. 96x96 all-white png with transparency. The name of the icon will be the resource name.

iOS Config:

  • mode: The APNs entitlement. Either development or production

Calling TakeOff

takeOff should be called in a standard application at the beginning of the lifecycle. Once takeOff is called, the config will be stored and applied for future app inits. If takeOff is called again with a different config, the new config will not be applied until the next app init.

import { UrbanAirship } from 'urbanairship-react-native';

    default: {
        appSecret: "REPLACE_WITH_YOUR_APP_SECRET",
    site: "us", // use "eu" for EU cloud projects
    urlAllowList: ["*"],
    android: {
        notificationConfig: {
            icon: "ic_notification",
            accentColor: "#00ff00"

URL Allow List

The URL allow list controls which URLs the Airship SDK is able to act on. The SDK divides up usages of URLs into 3 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.
Valid URL pattern syntax
<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 ["*"].