# SDK Installation

Complete installation and configuration guides for the Airship .NET package.

<!-- PAGE: Getting Started, PATH: https://www.airship.com/docs/developer/sdk-integration/dotnet/installation/getting-started/ -->

# Getting Started

> How to install the Airship .NET package.We provide native binding packages for iOS and Android, and cross-platform .NET packages for core functionality and features:

* **Airship Native Bindings**: The native bindings contain all the functionality of
  the iOS/Android SDKs, but provide no cross-platform interface. They can be found under the `UrbanAirship`
  namespace for Android and the `Airship` namespace for iOS.
* **Airship .NET Library**: The `Airship.Net` package exposes a common subset
  of functionality between the iOS and Android SDKs. This library can be used within
  shared codebases (e.g., a .NET MAUI app).
* **Airship .NET MessageCenter Library**: The `Airship.Net.MessageCenter` package exposes a custom message view
  control that can be used to display Message Center messages in shared codebases.

## Setup

> **Note:** This guide applies to apps built with .NET MAUI. If your app uses Xamarin and Xamarin.Forms, please refer to the [Airship Xamarin Setup](https://www.airship.com/docs/developer/sdk-integration/dotnet/installation/getting-started/) guide.


Before you begin, set up Push and any other Airship features for
[Mobile](https://www.airship.com/docs/developer/sdk-integration/). The
.NET bindings, like the SDKs that they wrap, are platform-specific,
so this would be a good time to familiarize yourself with the SDK APIs
and features for each platform you wish to target.

## Android Integration

The following packages are available for Android integration with .NET MAUI.

### Android Packages

| Package name                         | Description                                                    |
|--------------------------------------|----------------------------------------------------------------|
| Airship.Net.Android.Core             | Core SDK support                                               |
| Airship.Net.Android.Adm              | ADM push provider support                                      |
| Airship.Net.Android.Fcm              | FCM push provider support                                      |
| Airship.Net.Android.Automation       | In-App Automation, In-App Messaging, and Landing pages support |
| Airship.Net.Android.MessageCenter    | Message Center support                                         |
| Airship.Net.Android.PreferenceCenter | Preference Center support                                      |
| Airship.Net.Android.Layout           | Layout support                                                 |
| Airship.Net.Android.LiveUpdate       | Live Update support                                            |
| Airship.Net.Android.FeatureFlag      | Feature Flag support                                           |

### Push Provider
The Airship SDK for Android is split into modules which allow you to choose the push providers included in your application. You must
install at least one push provider in your Android app. You can install more than one provider.

Add the packages directly to your `.csproj` file by editing it and adding the appropriate `PackageReference` entries. Here's an example showing how to add the FCM push provider along with common feature modules:

**Example `.csproj` with Android packages**


```xml
<ItemGroup Condition="'$(TargetFramework)' == 'net8.0-android'">
  <PackageReference Include="Airship.Net.Android.Core" Version="19.13.6" />
  <PackageReference Include="Airship.Net.Android.Fcm" Version="19.13.6" />
  <PackageReference Include="Airship.Net.Android.Automation" Version="19.13.6" />
  <PackageReference Include="Airship.Net.Android.MessageCenter" Version="19.13.6" />
  <PackageReference Include="Airship.Net.Android.PreferenceCenter" Version="19.13.6" />
  <PackageReference Include="Airship.Net.Android.Layout" Version="19.13.6" />
</ItemGroup>
```


> **Note:** Replace `19.13.6` with the latest version available on [NuGet](https://www.nuget.org/packages?q=Airship.Net.Android).


### Airship Config

Airship config options are a convenient way to pass custom settings to your app
without needing to edit the source code. By default, the Airship SDK loads
these settings from the `airshipconfig.properties` file located in your
application's `Assets` directory for the Android platform. In the default MAUI
single-project structure, this should be located at `Platforms/Android/Assets`.
You may need to create the `Assets` directory, if it doesn't already exist.

Use this file, among other things, to set the backend credentials for your app,
and to toggle between development and production builds. In order
for this file to be visible to the SDK during TakeOff, be sure that its
`Build Action` is set to `AndroidAsset` in your app project.

**Example `airshipconfig.properties`**


```ruby
developmentAppKey = Your Development App Key
developmentAppSecret = Your Development App Secret

productionAppKey = Your Production App Key
productionAppSecret = Your Production Secret

 # Toggles between the development and production app credentials
 # Before submitting your application to an app store set to true
inProduction = false

 # LogLevel is "VERBOSE", "DEBUG", "INFO", "WARN", "ERROR" or "ASSERT"
developmentLogLevel = DEBUG
productionLogLevel = ERROR

 # Notification customization
notificationIcon = ic_notification
notificationAccentColor = #ff0000
```


The `airshipconfig.properties` file should be placed in `Platforms/Android/Assets/` and its `Build Action` should be set to `AndroidAsset` in the properties panel.

### EU Cloud Site
If your app uses Airship's EU cloud site, you will need to add that to `airshipconfig.properties`.

```ruby
# EU Cloud Site
site = EU
```


### FCM-specific instructions
Follow [FCM Android Setup](https://firebase.google.com/docs/android/setup) and [FCM Push Provider Setup](https://www.airship.com/docs/developer/sdk-integration/android/installation/getting-started/#fcm-setup) to configure your application to use FCM.

For MAUI apps, ensure your `google-services.json` file is placed in `Platforms/Android/` with `Build Action` set to `GoogleServicesJson`.

### TakeOff

Create a class that extends `Autopilot` in `Platforms/Android` and register your Autopilot in the Android `AssemblyInfo.cs` file
to generate the required metadata in the `AndroidManifest.xml` file. If needed, create a new `AssemblyInfo.cs` file in the
`Platforms/Android/Properties/` directory.

**Platforms/Android/SampleAutopilot.cs**


```c#
using UrbanAirship;

namespace ExampleApp;

[Register("com.example.SampleAutopilot")]
public class SampleAutopilot : Autopilot
{

  public override void OnAirshipReady(UAirship airship)
  {
    // perform any post takeOff airship customizations
  }

  public override AirshipConfigOptions CreateAirshipConfigOptions(Context context)
  {
    /* Optionally set your config at runtime
    AirshipConfigOptions options = new AirshipConfigOptions.Builder()
         .SetInProduction(!BuildConfig.DEBUG)
         .SetDevelopmentAppKey("Your Development App Key")
         .SetDevelopmentAppSecret("Your Development App Secret")
         .SetProductionAppKey("Your Production App Key")
         .SetProductionAppSecret("Your Production App Secret")
         .SetNotificationAccentColor(ContextCompat.getColor(this, R.color.color_accent))
         .SetNotificationIcon(R.drawable.ic_notification)
         .Build();
    return options;
    */
    return base.CreateAirshipConfigOptions(context);
  }
}
```


**Platforms/Android/Properties/Assemblyinfo.cs**


```c#
using Android.App;

[assembly: MetaData("com.urbanairship.autopilot", Value = "com.example.SampleAutopilot")]
```


**Platforms/Android/MainActivity.cs**


```c#
using UrbanAirship;

namespace ExampleApp;

[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true,
          ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation |
                                ConfigChanges.UiMode | ConfigChanges.ScreenLayout |
                                ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
public class MainActivity : MauiAppCompatActivity
{
    protected override void OnCreate (Bundle savedInstanceState)
    {
        Autopilot.AutomaticTakeOff(this.ApplicationContext);

        //...
    }
}
```


## iOS Integration

The following packages are available for iOS integration with .NET MAUI.

### iOS Packages

The Airship .NET component comes with full native bindings for the iOS SDK via the `Airship.Net.iOS.ObjectiveC` package.

| Package name                  | Description                                        |
|-------------------------------|----------------------------------------------------|
| Airship.Net.iOS.ObjectiveC    | Full iOS SDK bindings (Core, Automation, Message Center, Preference Center, Feature Flags) |

Add the iOS package directly to your `.csproj` file by editing it and adding the appropriate `PackageReference` entry:

**Example `.csproj` with iOS package**


```xml
<ItemGroup Condition="'$(TargetFramework)' == 'net8.0-ios'">
  <PackageReference Include="Airship.Net.iOS.ObjectiveC" Version="19.11.5" />
</ItemGroup>
```


> **Note:** Replace `19.11.5` with the latest version available on [NuGet](https://www.nuget.org/packages/Airship.Net.iOS.ObjectiveC).


### Airship Config

Provide an `AirshipConfig.plist` file with the application's configuration in the `Platforms/iOS` folder.
In order for this file to be visible to the SDK during TakeOff, be sure that its `Build Action` is set to
`BundleResource` in your app project.

**Example `AirshipConfig.plist`**


```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
     <key>detectProvisioningMode</key>
     <true/>
     <key>developmentAppKey</key>
     <string>Your Development App Key</string>
     <key>developmentAppSecret</key>
     <string>Your Development App Secret</string>
     <key>productionAppKey</key>
     <string>Your Production App Key</string>
     <key>productionAppSecret</key>
     <string>Your Production App Secret</string>
     <true/>
  </dict>
</plist>
```


The `AirshipConfig.plist` file should be placed in `Platforms/iOS/` and its `Build Action` should be set to `BundleResource` in the properties panel.

### EU Cloud Site
If your app uses Airship's EU cloud site, you will need to add that to `AirshipConfig.plist`.

```xml
<key>site</key>
  <string>EU</string>
```


### TakeOff

The Airship SDK requires only a single entry point in the app
delegate, known as *takeOff*. Inside your application delegate's
`FinishedLaunching` method, initialize a shared `UAirship` instance by
calling `takeOff`.
This will bootstrap the SDK and look for settings specified in the
`AirshipConfig.plist` config file.

> **Note:** If the `takeOff` process fails due to improper or missing configuration, the shared
> `UAirship` instance will be `null`. The Airship SDK always logs implementation errors at
> high visibility.


**Example takeOff**


```c#
using Airship;

namespace ExampleApp;

[Register ("AppDelegate")]
public class AppDelegate : MauiUIApplicationDelegate
{
    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();

    public override bool FinishedLaunching (UIApplication application, NSDictionary launchOptions)
    {
        // Populate AirshipConfig.plist with your app's info from https://go.urbanairship.com
        // or set runtime properties here.
        NSError configError;
        UAConfig config = UAConfig.DefaultConfigWithError(out configError);

        if (config == null || configError != null)
        {
            throw new InvalidOperationException($"Failed to load Airship configuration: {configError?.LocalizedDescription ?? "Unknown error"}");
        }

        NSError error;
        bool success = UAirship.TakeOff(config, launchOptions as NSDictionary<NSString, NSObject>, out error);

        if (!success || error != null)
        {
            throw new InvalidOperationException($"Failed to initialize Airship: {error?.LocalizedDescription ?? "Unknown error"}");
        }

        // Configure Airship here

        return base.FinishedLaunching(application, launchOptions);
    }
}
```


### Notification Service Extension

In order to take advantage of iOS notification attachments,
such as images, animated gifs, and video, you will need to create
a Notification Service Extension target in your project.

Follow the [iOS Notification Service Extension Guide](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/notification-service-extension/) for setup instructions.

### Notification Content Extension

The iOS SDK's Notification Content Extension provides support for carousel UI.

Follow the [iOS Notification Content Extension Guide](https://www.airship.com/docs/developer/sdk-integration/apple/installation/getting-started/#notification-content-extension) for setup instructions.

## .NET Shared Components Installation  {#maui-component-installation}

Installing the Airship components is a quick and easy process,
seamlessly integrated into Visual Studio. You have two installation options:

* **Native bindings**: If you are only working with one platform, or if there is no
  reason for you to have a shared codebase between your platform projects, this may be an
  appropriate option. It's possible to make use of the native bindings

* **Airship.NET + native bindings**: If you are working with multiple platforms, and you have a shared codebase (e.g., a MAUI app), this may be an appropriate option.
  You can use the Airship .NET libraries in the shared codebase, while the native bindings can handle platform-specific calls in each platform folder or project.
  Platform-specific native bindings can also be called directly from cross-platform code, using
  [conditional compilation](https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/invoke-platform-code?view=net-maui-8.0#conditional-compilation).

All components can be installed by editing your `.csproj` file directly or via the NuGet package manager in Visual Studio or the `dotnet` CLI.

> **Note:** After adding platform-specific binding packages, inspect your `.csproj` file to make sure that
> the `ItemGroup` or `PackageReference` includes the correct `Condition` attribute for your .NET
> version and target platform:
> 
> ```xml
> <ItemGroup Condition="'$(TargetFramework)' == 'net8.0-android'">
>     <PackageReference Include="Airship.Net.Android.Core" Version="19.13.6" />
>     <PackageReference Include="Airship.Net.Android.Fcm" Version="19.13.6" />
>     <PackageReference Include="Airship.Net.Android.Automation" Version="19.13.6" />
>     <PackageReference Include="Airship.Net.Android.MessageCenter" Version="19.13.6" />
>     <PackageReference Include="Airship.Net.Android.PreferenceCenter" Version="19.13.6" />
> </ItemGroup>
> 
> <ItemGroup Condition="'$(TargetFramework)' == 'net8.0-ios'">
>     <PackageReference Include="Airship.Net.iOS.ObjectiveC" Version="19.11.5" />
> </ItemGroup>
> ```


### Cross-Platform Library

To use the cross-platform Airship .NET library, add it to your `.csproj` file:

```xml
<ItemGroup>
  <PackageReference Include="Airship.Net" Version="20.2.1" />
</ItemGroup>
```


> **Note:** The Airship SDK packages were updated in 2018 to reflect the modularization of the Android SDK, which is
> now split into Core, ADM, FCM, and a set of feature modules. The original package named `urbanairship` is deprecated
> and out of date, but currently remains in NuGet. The `airship.netstandard` package is not compatible with .NET MAUI
> and is only appropriate for use in apps built with the older Xamarin Forms framework.
> 
> When in doubt, check the release date of the package before installing.


## Native Bindings

Using the native binding libraries is similar to using either the Android or iOS
SDKs. Below we provide a simple comparison between setting a named user ID
in the native SDK and binding library. In general, the two changes you will notice
between the bindings and SDKs are:

* Method calls are generally capitalized.
* Getters/setters are generally converted into properties.

### Android

**Native Java Call**


```java
// Set the named user ID
UAirship.shared().contact().identify("NamedUserID");
```


**Binding Library**


```c#
// Set the named user ID
UAirship.Shared().Contact.Identify("NamedUserID");
```


For more information on the Android SDK, please see the
[Android platform documentation](https://www.airship.com/docs/developer/sdk-integration/android/).

### iOS

**Native Swift Call**


```swift
// Set the named user ID
Airship.contact.identify("NamedUserID")
```


**Binding Library**


```c#
// Set the named user ID
UAirship.Contact.Identify("NamedUserID");
```


For more information on the iOS SDK, please see the
[iOS platform documentation](https://www.airship.com/docs/developer/sdk-integration/apple/).

## Airship .NET Library

The Airship .NET library provides a unified interface for common SDK
calls, allowing users to place common code in a shared location. This is
ideal for working with MAUI -- simply add the `Airship.Net` NuGet dependency
and all of these calls should be available from your shared codebase.

> **Note:** Because the Airship.NET library currently has no shared interface for initializing
> the app (i.e., calling `takeOff`), you must install the native bindings for each platform target and add platform-specific calls to initialize Airship
> in your platform-specific sources or projects.


The Airship .NET library is accessible through the `Airship` class, found in the `AirshipDotNet` namespace.
Full documentation for the .NET library can be found [here](https://www.airship.com/docs/reference/libraries/maui/latest/).

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


<!-- /PAGE: Getting Started -->

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

# 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. |
| **Assert** | Disables all logging. |

## Configuring log levels

You can set the log level in the Airship config files for Android and iOS.

### Android

In your `airshipconfig.properties` file:

```text
# Available log levels: VERBOSE, DEBUG, INFO, WARN, ERROR, ASSERT
productionLogLevel = VERBOSE
developmentLogLevel = VERBOSE
```


### iOS

In your `AirshipConfig.plist` file:

```xml
<!--  Available log levels: TRACE, DEBUG, INFO, WARNING, NONE -->
<key>productionLogLevel</key>
<string>TRACE</string>
<key>developmentLogLevel</key>
<string>TRACE</string>
```




<!-- /PAGE: Logging -->

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

# Locale

> Configure locale behavior and override the default locale that Airship uses.
> **Note:** Locale configuration is not supported in the Airship .NET library. Use native binding methods instead.




<!-- /PAGE: Locale -->