Getting Started
This is a developers’ guide for setting up the Airship SDK for React Native apps.
The Airship React Native modules allow a developer to integrate push notification services with React Native apps targeting both Android and iOS. These modules are designed to be cross-platform, and applications making use of them can leverage the same code on both platforms.
Resources
- Sample
- Airship React Native API Docs
- Airship Accengage React Native API Docs
- Airship HMS React Native API Docs
- Airship Location React Native API Docs
- Github Repo
Requirements
- React Native >= 0.60.0
- React Native cli >= 2.0.1
iOS
- Xcode
13+
- minimum deployment target iOS
11+
Android
- minSdkVersion
21+
- compileSdkVersion
31+
- Gradle Plugin version 3.0.0+
- Java 8
Installation
Standard React Native Setup
Install the plugin using yarn or npm:
yarn add urbanairship-react-native
Android
- 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
// ...
}
}
- 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
}
}
- Download the Android Firebase configuration file
google-services.json
from the application’s Firebase console into the root directory atandroid/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.
iOS
- Install pods
$ pod install
- Open your apps project in the generated
.xcworkspace
file, add the following capabilities:
- Push Notification
- Background Modes > Remote Notifications
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:
"plugins":[
[
"airship-expo-plugin",
{
"android":{
"icon":"./assets/ic_notification.png"
},
"ios":{
"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';
UrbanAirship.takeOff({
default: {
appSecret: "REPLACE_WITH_YOUR_APP_SECRET",
appKey: "REPLACE_WITH_YOUR_APP_KEY"
},
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 URLsurlAllowList
: 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 ["*"]
.
Send Your First Push Notification
At this point in the guide, if you followed all the steps above you should be ready to send a test push notification to verify everything is set up properly.
Before sending a push, you must enable user notifications. The module does not enable user notifications by default in order to avoid prompting the user for permissions. But for a testing purposes, you can enable user notifications as soon as the application is ready. You may also want to set default foreground presentation options to display the notification in the foreground.
import {
UrbanAirship,
UACustomEvent,
} from 'urbanairship-react-native'
class SampleApp extends Component {
constructor(props) {
super(props);
UrbanAirship.setUserNotificationsEnabled(true)
}
...
}
Categories