Unity

The Urban Airship Unity Plugin allows a developer to integrate push notification services with Unity apps targeting both Android and iOS. This plugin is designed to be cross-platform, and applications making use of it can leverage the same code on both platforms.

To see sample code demonstrating the Urban Airship features discussed in this guide, check out the example script included in the plugin on Bintray or Unity Example on GitHub.

Requirements

  • Unity 5
  • iOS - Xcode 8+ for iOS
  • Android - Android SDK installed and updated (requires Android MinSdkVersion = 16)

Setup

  1. Download the latest plugin

  2. Import the plugin into a unity project: Open Assets -> Import Package -> Custom Package and import the downloaded Urban Airship unitypackage

  3. Configure Urban Airship Settings: Open Window -> Urban Airship -> Settings and set the Urban Airship settings

  4. For iOS, enable Push Notifications in the project editor’s Capabilities pane:

  5. Extra steps are required if you want to support iOS 10 notification attachments, such as images, animated gifs, and video. You will need to create a notification service extension alongside your main application and install the UrbanAirship-iOS-AppExtensions pod to this target.

    Before you begin, ensure that you have the CocoaPods dependency manager installed. You can do so by executing the following command:

    $ gem install cocoapods
    

    In Unity, generate your Xcode project via File -> Build Settings -> select iOS Platform -> click Build And Run.

    Create a new iOS target in Xcode (File -> New -> Target).

    Select the Notification Service Extension type and click Next.

    Typically extensions are named with a suffix on the main application’s ID. In this example, the bundle identifier would be com.urbanairship.sample.ExampleServiceExtension.

    Activate the scheme.

    With your app’s target selected, go to the Build Phases pane and verify that Embed App Extensions contains your newly created extension.

    With your app’s target selected, go to the Build Settings pane and select Standard architectures (armv7, arm64) for Architectures.

    With your extension’s target selected, go to the Build Settings pane and select the Standard architectures (armv7, arm64) for Architectures.

    In the directory where your Xcode project (<Your Unity project>.xcodeproj) resides, create a podfile and specify the UrbanAirship-iOS-AppExtensions in it and your newly created service extension as the target:

    use_frameworks!
    
    # Urban Airship SDK
    target "<Your Service Extension Target Name>" do
      pod 'UrbanAirship-iOS-AppExtensions'
    end
    

    Install using the following command:

    $ pod install
    

    Open the <Your Unity project>.xcworkspace:

    $ open <Your unity project>.xcworkspace
    

    Modify your extension.

    1. Delete all dummy source code for your new extension.

    2. Inherit from UAMediaAttachmentExtension in NotificationService.

      // Notification.swift
      import AirshipAppExtensions
      
      class NotificationService: UAMediaAttachmentExtension {
      
      }
      
      // NotificationService.h
      @import AirshipAppExtensions;
      
      @interface NotificationService : UAMediaAttachmentExtension
      
      @end
      
      // NotificationService.m
      @import Foundation;
      
      #import "NotificationService.h"
      @implementation NotificationService
      
      @end
      

Retrieving your Channel ID

The Channel ID will be logged for all apps. You can always get the Channel ID with a couple of extra lines to your application:

string channelId = UAirship.Shared.ChannelId;

Enabling User Notifications

The Urban 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.

UAirship.Shared.UserNotificationsEnabled = true;

Send a Test Notification

Now would be a great time to send a test notification. See our user guide on Send Your First Notification to get started using our dashboard interface, or our API reference for more details.

Reference and Migration Guide

All the public classes and methods provided by the Urban Airship Unity Plugin are available in our API docs.

We also publish an update to the migration guide Unity Plugin migration guide every time the Plugin is updated, to help make the update process as painless as possible.

Addressing Devices

To help target specific devices or users for a notification, we have Tags, Named Users and Tag Groups.

Tags

Tags allow you to attribute arbitrary metadata to a specific device. Common examples include favorites such as sports teams or news story categories.

Example:

// Add tag
UAirship.Shared.AddTag ("some-tag");

// Remove tag
UAirship.Shared.RemoveTag ("other-tag");

// Get tags
IEnumerable<string> tags = UAirship.Shared.Tags;

Named Users

Named Users allow you to associate multiple devices to a single user or profile that may be associated with more than one device, e.g., an end-user’s Android phone and tablet. A device can have only one Named User, and a single Named User should not be associated with more than 20 devices. Named Users provide the ability to directly set tags on them (see Tag Groups).

By default, Named Users cannot be associated from the device. In this case if the devices attempts a Named User association, the association will fail and the plugin will log an error. In order to change this setting, see the Settings documentation.

Examples:

Once the application has a channel ID, you can associate the channel to a Named User:

UAirship.Shared.NamedUserId = "coolNamedUserId";

To disassociate a channel from a Named User ID, set its ID to null:

UAirship.Shared.NamedUserId = null;

Note

Associating the channel with a Named User ID, will implicitly disassociate the channel from the previously associated Named User ID, if it existed.

Tag Groups

Tag groups are configurable namespaces for organizing tags for the channel and Named User. Please view the Tag Groups documentation for more details. The Tag Group Walkthrough will guide you through the creation of your first Tag Group.

By default, Tag Groups cannot be modified from the device. In this case if a device attempts to modify Tag Groups, the modification will fail and the SDK will log an error. In order to change this setting, see the Settings documentation.

Channel Tag Groups

Once you have created a Tag Group, you can add or remove tags for the Tag Group on the channel. In this example, we have created a Tag Group loyalty and will upgrade a user from “bronze-member” to “silver-member”:

UAirship.Shared.EditChannelTagGroups ()
     .AddTag ("loyalty", "silver-member")
     .RemoveTag ("loyalty", "bronze-member")
     .Apply ();

Named User Tag Groups

Named users provide the ability to directly set tags on them. Once you have created a Tag Group and associated a channel with the Named User, you can add or remove tags for the Tag Group on that Named User in a similar fashion as Channel Tag Groups.

UAirship.Shared.EditNamedUserTagGroups ()
     .AddTag ("loyalty", "silver-member")
     .RemoveTag ("loyalty", "bronze-member")
     .Apply ();