# Unity Integrate the Airship SDK into your Unity applications for iOS and Android. # Deep Links > Configure deep link handling for Airship messaging. Deep linking allows Airship messaging to open your app to specific resources or screens. When a user interacts with a message (notification, in-app message, etc.), the deep link can navigate them directly to the relevant content in your app. ## Listening for deep links The SDK provides a way to listen for deep links so you can handle them in your app. This handler receives all deep links except for Message Center and Preference Center display requests, which are handled automatically by their respective features. > **Note:** For Message Center and Preference Center display requests, see [Message Center: Getting Started](https://www.airship.com/docs/developer/sdk-integration/unity/message-center/getting-started/) and [Preference Center: Getting Started](https://www.airship.com/docs/developer/sdk-integration/unity/preference-center/getting-started/). ```csharp UAirship.Shared.OnDeepLinkReceived += (string deepLink) => { // Handle deep link }; ``` # Unity Plugin Changelog > The latest updates to the Airship Unity plugin. See the [SDK Support Policy](https://www.airship.com/docs/reference/sdk-support-policy/) for version coverage and maintenance windows. [View Older Releases](https://github.com/urbanairship/ua-unity-plugin/releases?q=created%3A%3C2024-05-15&expanded=true) # Unity Plugin Resources > API documentation, source code, and changelogs for the Airship Unity plugin. ## API References * [API docs](https://www.airship.com/docs/reference/libraries/unity/latest/) ## GitHub * [Source](https://github.com/urbanairship/ua-unity-plugin) * [Example Behavior Script](https://github.com/urbanairship/ua-unity-plugin/blob/main/Assets/Scripts/UrbanAirshipBehaviour.cs) ## Changelog * [Unity Changelog](https://www.airship.com/docs/developer/sdk-integration/unity/changelog/) ## License All Airship SDKs and frameworks are open sourced and licensed under Apache Software License 2.0. ## SDK Installation Complete installation and configuration guides for the Airship Unity plugin. # Install and Set Up the Unity Plugin > How to install the Airship Unity plugin. ## Requirements * Unity 5+ * iOS: Xcode `15.3+` * iOS: Minimum deployment target iOS `15+` * Android: Android SDK installed and updated (requires `minSdkVersion` = `23+`) * Android: Using Android SDK manager, install API `36+`. * If a Custom Gradle Template is used, the gradle template needs to be configured to use API VERSION `36+`. ## Setup [Download](https://github.com/urbanairship/ua-unity-plugin/releases) the latest plugin and import the `unitypackage` into the Unity project: `Open Assets -> Import Package -> Custom Package`. ![Importing the Airship package in Unity](https://www.airship.com/docs/images/unity-assets-import-package_hu_a6880ed7081154dc.webp) *Importing the Airship package in Unity* Configure Airship Settings: `Open Window -> Airship -> Settings` and set the Airship settings. > **Important:** Leave the `Android FCM Sender ID` field **BLANK** for both Production and Development. > **Important:** If your app uses Airship's EU cloud site, you will need to configure that using the `Cloud Site` setting. ![Airship Settings window in Unity](https://www.airship.com/docs/images/unity-ua-settings_hu_94e022e909756bec.webp) *Airship Settings window in Unity* ![Airship configuration options in Unity](https://www.airship.com/docs/images/unity-ua-config_hu_1800978d81e08caf.webp) *Airship configuration options in Unity* If proguard is enabled, add Airship settings to the `proguard-user.txt` file: `-keep public class com.urbanairship.unityplugin.UnityPlugin -keepclassmembers class com.urbanairship.unityplugin.UnityPlugin { public ; public ; static ; }` For push notification setup, see the [Push Notifications Getting Started guide](https://www.airship.com/docs/developer/sdk-integration/unity/push-notifications/getting-started/). ## Troubleshooting A common error when setting up our Unity plugin is "Could not create an instance of type org.gradle.initialization.DefaultSettings_Decorated". If you encounter this error, take these steps in the Unity Editor: 1. Go to **Assets**, then **External Dependency Manager**, then **Android Resolver**, then **Force Resolve**. 1. Sometimes Unity has difficulty retrieving the JDK installed with your editor even when selected. To solve this: 1. Go to **Edit**, then **Preferences**, then **External Tools**. 1. For **JDK**, select **Copy Path**, uncheck **JDK Installed with Unity (Recommended)**, then paste the path. ![Setting the JDK path in the Unity Editor](https://www.airship.com/docs/images/unity/unity-uncheck-jdk-installed_hu_9c5a35b94f3157d2.webp) *Setting the JDK path in the Unity Editor* 1. ![Enabling project templates in the Unity Editor](https://www.airship.com/docs/images/unity/unity-enable-custom-gradle_hu_7a1ebe2c4fc15bd9.webp) *Enabling project templates in the Unity Editor* If the previous steps do not fix your issue: 1. Go to **Project Settings**, then **Player**, then **Android**, then **Publishing Settings**, then **Build**, and then select **Custom Main Gradle Template** and **Custom Gradle Properties Template**. 1. Go to **Assets**, then **External Dependency Manager**, then **Android Resolver**, then **Force Resolve**. If you don't see a channel ID or encounter errors during initialization, see [Troubleshooting Initialization](https://www.airship.com/docs/developer/sdk-integration/unity/troubleshooting/initialization/) for common problems and solutions. # Logging > Configure log levels 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 Log levels can be set within the Airship config menu in Unity. # Locale > Configure locale behavior and override the default locale that Airship uses. > **Note:** Locale configuration is not supported in the Airship Unity plugin. ## Push Notifications Configure and implement push notifications for iOS and Android platforms. # Push Notifications > How to configure your application to receive and respond to notifications. Before you can send and receive push notifications, you need to configure your app for the platform(s) you're targeting. ## Platform Setup Follow the platform-specific setup instructions below to enable push notifications in your Unity app. ### iOS After generating a project for iOS, enable Push Notifications in the project editor's Capabilities pane: ![Enabling Push Notifications in the Xcode project editor](https://www.airship.com/docs/images/ios-enable-push-notifications_hu_d5790d72c4daf49a.webp) *Enabling Push Notifications in the Xcode project editor* #### 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 .

Follow the steps in the [iOS Notification Service Extension Guide](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/notification-service-extension/). ### Android Download the Android Firebase configuration file, `google-services.json`, from the application's Firebase console and add it to the `Assets` directory. If your Unity application does not have an associated application in the Firebase console, follow the [FCM setup instructions](https://www.airship.com/docs/developer/sdk-integration/android/installation/getting-started/#fcm-setup) to set one up. ## Enable User Notifications Enabling `userNotificationsEnabled` will prompt the user for permission to send notifications. To increase the likelihood that the user will accept, you should avoid prompting the user for permission immediately, and instead wait for a more appropriate time in the app. The Airship SDK makes a distinction between `user notifications`, which can be seen by the user, and other forms of push that allow you to send data to your app silently, or in the background. Enabling or disabling user notifications is a preference often best left up to the user, so by default, user notifications are disabled. ```csharp UAirship.Shared.UserNotificationsEnabled = true; ``` > **Note:** For apps that target Android 13 (API 33) and above, enabling user notifications will display a runtime permission prompt to allow notifications to be sent. > > To increase the likelihood that the user will accept, you should avoid prompting the user for permission immediately on app startup, and instead wait for a more appropriate time to prompt for notification permission. ## Handle Notification Events The Airship SDK provides several callbacks for when a push is received or a notification is interacted with. Apps can use these callbacks to do custom push processing. Registering for a callback is optional, the SDK will automatically launch the application without the need to set a callback. ```csharp UAirship.Shared.OnPushReceived += (PushMessage message) => { // Handle message }; UAirship.Shared.OnPushOpened += (PushMessage message) => { // Handle message }; ``` ## Silent Notifications Silent notifications are push messages that do not present a notification to the user. These are typically used to briefly wake the app from a background state to perform processing tasks or fetch remote content. > **Important:** We recommend that you thoroughly test your implementation to confirm that silent notifications do not generate any device notifications. For Android, all push messages are delivered in the background, but default Airship will treat messages without an `alert` as silent. For iOS, set the `content_available` property to `true` in the [iOS override object](https://www.airship.com/docs/developer/rest-api/ua/schemas/platform-overrides/#iosoverrideobject). > **Note:** Pushes sent with the `content_available` property (iOS) or without an `alert` (Android) do not have guaranteed delivery. Factors affecting delivery include battery life, whether the device is connected to WiFi, and the number of silent pushes sent within a recent time period. These metrics are determined solely by iOS/Android and APNs/FCM. Therefore, this feature is best used for supplementing the regular behavior of the app rather than providing critical functionality. For instance, an app could use a silent push to pre-fetch new data ahead of time in order to reduce load times when the app is later launched by the user. ## iOS Notification Options > **Note:** iOS notification options, badges, and quiet time are not supported in Unity. If push notifications aren't working as expected, see [Troubleshooting Push Notifications](https://www.airship.com/docs/developer/sdk-integration/unity/troubleshooting/push-notifications/) to check notification status and fix common issues. ## Message Center Implement Message Center to provide an inbox for rich HTML-based messages. # Message Center > The default Message Center is available for Unity with minimal integration required. Basic theming options are supported. Message Center provides an inbox for rich, HTML-based messages that users can view at their convenience. By default, when your app receives a push notification with a Message Center action, the Message Center automatically displays. You can also display the Message Center manually by calling a simple method, making it easy to add a Message Center button to your app's navigation. Message Center inboxes are associated with channel IDs. Each device has a unique channel ID that persists across app launches, allowing users to access their message history. ## Display the Message Center Display the Message Center with a single method call: ```csharp UAirship.Shared.DisplayMessageCenter(); ``` ## Override Default Display Behavior Custom display behavior is not supported in Unity. The default Message Center will be displayed when requested. ## Fetch Messages Retrieve messages from the inbox: ```csharp UAirship.Shared.InboxMessages(); ``` ## Listen for Message Updates Subscribe to message updates using callbacks: ```csharp UAirship.Shared.InboxMessages(messages => { // Handle messages }); ``` ## Listen for Unread Count Changes Subscribe to unread count updates: ```csharp var unreadCount = UAirship.Shared.UnreadCount; // Update badge or UI ``` ## Refresh Messages Manually refresh the message list from the server: ```csharp UAirship.Shared.RefreshInbox(); ``` ## Mark Messages as Read Mark one or more messages as read: ```csharp UAirship.Shared.MarkInboxMessageRead("message-id"); ``` ## Delete Messages Delete one or more messages: ```csharp UAirship.Shared.DeleteInboxMessage("message-id"); ``` ## Preference Center Implement Preference Center to let users control their subscription preferences. # Preference Center > Preference Center allows users to opt in and out of subscription lists configured via the Airship Dashboard. > **Important:** Airship Preference Centers are widgets that can be embedded in a page in an app or website. Please verify with your legal team that your full Preference Center page, including any web page for email Preference Centers, is compliant with local privacy regulations. Preference Center provides a pre-built UI for users to manage their subscription preferences. Learn more in the [Preference Center user guide](https://www.airship.com/docs/guides/messaging/features/preference-centers/). ## Display a Preference Center Display a Preference Center with a single method call: ```csharp UAirship.Shared.OpenPreferenceCenter("preference-center-id"); ``` ## Audience Management Integrate audience management features into your Unity app. This guide covers how to identify contacts, access channel IDs, and set tags, attributes, and subscription lists on channels and contacts. For information about using these features for segmentation and targeting, see the [Audience User Guide]({{< ref "/guides/audience/segmentation/segmentation.md" >}}). # Channels > Access and manage channel IDs and listen for channel creation. Each device/app install will generate a unique identifier known as the Channel ID. Once a Channel ID is created, it will persist in the application until the app is reinstalled, or has its internal data is cleared. For information about finding Channel IDs, using the Channel Capture tool, and other methods to access Channel IDs, see [Finding Channel IDs](https://www.airship.com/docs/guides/getting-started/developers/identifiers/). ## Accessing the Airship Channel ID Apps can access the Channel ID directly through the SDK. ```csharp string channelId = UAirship.Shared.ChannelId; ``` The Channel ID is asynchronously created, so it may not be available right away on the first run. Changes to Channel data will automatically be batched and applied when the Channel is created, so there is no need to wait for the Channel to be available before modifying any data. Applications that need to access the Channel ID can use a listener to be notified when it is available. ```csharp UAirship.Shared.OnChannelUpdated += (string channelId) => { Debug.Log ("Channel updated: " + channelId); }; ``` # Contacts > Identify contacts, reset contacts, and get named user IDs. A Contact is any user in your project. Contacts are identified as either an Anonymous Contact or a Named User. Airship can set targeting data on these identifiers, which are also used to map devices and channels to a specific user. For detailed information about contacts and named users, see [Named users](https://www.airship.com/docs/guides/audience/named-users/). ## Managing the Contact's identifier (Named User ID) Identify can be called multiple times with the same Named User ID. The SDK will automatically deduplicate `identify` calls made with the same Named User ID. If the ID is changed from a previous value, the Contact will automatically be dissociated from the previous Named User ID. ```csharp UAirship.Shared.NamedUserId = "some named user ID"; ``` If the user logs out of the device, you may want to reset the contact. This will clear any anonymous data and dissociate the contact from the Named User ID, if set. This should only be called when the user manually logs out of the app, otherwise you will not be able to target the Channel by its Contact data. ```csharp UAirship.Shared.NamedUserId = null; ``` You can get the Named User ID only if you set it through the SDK. ```csharp UAirship.Shared.NamedUserId ``` # Tags > Set device tags, contact tags, and tag groups for audience segmentation. For information about tags, including how to use them for segmentation and targeting, see the [Tags user guide](https://www.airship.com/docs/guides/audience/tags/). ## Channel Tags Channel tags are tags managed on the Channel by the SDK. Device tags (tags without a group) can be modified or fetched from the Channel. ```csharp // Add tag UAirship.Shared.AddTag ("some-tag"); // Remove tag UAirship.Shared.RemoveTag ("other-tag"); // Accessing channel tags IEnumerable tags = UAirship.Shared.Tags; ``` ## Channel Tag Groups Tag groups are tags scoped within a group. Tag groups can be modified from the SDK but cannot be fetched. Device tags (tags without a group) can be fetched. If you need to be able to fetch tag groups, consider using subscription lists. ```csharp UAirship.Shared.EditChannelTagGroups () .AddTag ("loyalty", "silver-member") .RemoveTag ("loyalty", "bronze-member") .Apply (); ``` ## Contact Tag Groups Contact tag groups are tags scoped within a group at the Contact level. Tag groups can be modified from the SDK but cannot be fetched. If you need to be able to fetch tag groups, consider using subscription lists. ```csharp UAirship.Shared.EditNamedUserTagGroups () .AddTag ("loyalty", "silver-member") .RemoveTag ("loyalty", "bronze-member") .Apply (); ``` ## Verifying Tags To verify that tags have been set correctly, look up the channel or contact in the [Contact Management](https://www.airship.com/docs/guides/audience/contact-management/) view. You can search by Channel ID or Named User ID to view the tags and tag groups associated with a channel or contact. # Attributes > Set channel and contact attributes as key-value pairs for personalization. For information about Attributes, including overview, use cases, and how to target Attributes, see [About Attributes](https://www.airship.com/docs/guides/audience/attributes/about/). ## Channel Attributes Channel attributes are attributes managed on the Channel by the SDK. ```csharp UAirship.Shared.EditChannelAttributes() .SetAttribute("device_name", "Bobby's Phone") .SetAttribute("average_rating", 4.99) .RemoveAttribute("vip_status") .Apply() ``` ## Contact Attributes Contact attributes are attributes managed on the Contact by the SDK. ```csharp UAirship.Shared.EditNamedUserAttributes() .SetAttribute("first_name", "Bobby") .Apply() ``` ## Verifying Attributes To verify that attributes have been set correctly, look up the channel or contact in the [Contact Management](https://www.airship.com/docs/guides/audience/contact-management/) view. You can search by Channel ID or Named User ID to view the attributes associated with a channel or contact. ## Data Collection Overview of data collection and controls provided by the Airship Unity SDK. # Privacy Manager > Use Privacy Manager to enable or disable Airship SDK features for privacy and consent management. > **Note:** Privacy Manager is not supported in the Airship Unity plugin. For information about what data is collected for each Privacy Manager flag, see [SDK Data Collection](https://www.airship.com/docs/reference/data-collection/sdk-data-collection/). # Analytics > Track user engagement and app performance with Airship analytics, including custom events, screen tracking, and associated identifiers. > **Note:** Analytics events are batched and uploaded asynchronously in the background to minimize battery impact. The database size is fixed, so events are safely stored even when offline. Events may not upload immediately and may wait until the next app initialization if the app is closed before the upload completes. ## Custom Events Track user activities and key conversions with custom events. They require enabling analytics for your app. For detailed information, see the [Custom Events guide](https://www.airship.com/docs/guides/audience/events/custom-events/). ```csharp CustomEvent customEvent = new CustomEvent(); customEvent.EventName = "event_name"; customEvent.EventValue = 123.45; customEvent.AddProperty("my_custom_property", "some custom value"); customEvent.AddProperty("is_neat", true); UAirship.Shared.AddCustomEvent(customEvent); ``` ## Associated Identifiers Associated identifiers (also called custom identifiers) associate an external identifier with a [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id). They are visible in [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds). We recommend adding any IDs that you may want to be visible in your event stream. You can assign up to 20 associated identifiers to a device. Unlike other identifiers (e.g., tags), you cannot use associated identifiers to target your users. ```csharp UAirship.Shared.AssociateIdentifier("key", "value"); ``` ## Screen Tracking The Airship SDK gives you the ability to track which screens a user views within the application, how long a user stayed on each screen, and also includes the user's previous screen. These events then come through [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds), allowing you to see the path a user took through the application, or trigger actions based on a user visiting a particular area of the application. ```csharp UAirship.Shared.TrackScreen("MainScreen") ``` ## Troubleshooting Common issues and solutions for Airship plugin setup, initialization, and integration. # Troubleshooting Initialization > Troubleshoot common initialization issues and apply solutions. When following steps in [Getting Started](https://www.airship.com/docs/developer/sdk-integration/unity/installation/getting-started/), if you don't see a channel ID in the logs or encounter errors during initialization, review the following common problems and solutions. ## Installation Errors If you encounter errors during installation: - Verify that you're using a compatible version of Unity. See [Requirements](https://www.airship.com/docs/developer/sdk-integration/unity/installation/getting-started/#requirements) in *Getting Started*. - Ensure the Unity package is properly imported. - Check that your iOS and Android build settings are correctly configured. ## Initialization Errors If you encounter errors during SDK initialization: - Verify your credentials in the Airship dashboard. The credentials used by `takeOff` are your Airship project's [App Key](https://www.airship.com/docs/reference/glossary/#app_key) and [App Secret](https://www.airship.com/docs/reference/glossary/#app_secret). To find them, select the dropdown menu (▼) next to your project name, and then **Project details**. - Check that `takeOff` is called correctly in your Unity scripts. - Ensure both iOS and Android native modules are properly configured. # Troubleshooting Push Notifications > Check push notification status and fix common issues. If [push notifications](https://www.airship.com/docs/developer/sdk-integration/unity/push-notifications/) aren't working as expected: - Verify that push notifications are enabled for both iOS and Android. - Check that APNs (iOS) and FCM (Android) are properly configured. - Ensure the app has notification permissions.