Manual 1.7

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 44

Download
Open PDF In Browser	View PDF

UTNotifications Manual
Version 1.7
Introduction
Getting Started
Creating Local Notifications
Using Notification Profiles (Sounds, Icons and Other Attributes)
Custom User Data & Handling Notifications
Notification Buttons (Android)
Image Notifications (Android)
Open URL Notifications (Android)
Push Notifications Overview
What You Need for Push Notifications
General
iOS: Apple Push Notification Service (APNS)
Android: Firebase Cloud Messaging (FCM)
Android: Amazon Device Messaging (ADM)
Windows Store: Windows Push Notification Services (WNS)
Push Notifications Payload Format
Configuring Apple Push Notification Service (APNS)
Migrating from GCM to FCM
Configuring the Firebase Cloud Messaging (FCM)
Apply Credentials and Test
Configuring the Amazon Device Messaging (ADM)
Getting Your OAuth Credentials and API Key
Apply Credentials and Test
Configuring the Windows Push Notification Services (WNS)
Register your app with the Dashboard
Obtain the identity values for your app
Apply Credentials and Test
Unicode Support
Contacts

Introduction
API Reference​ | F
​ orum​ | ​Support Email​ | ​Issue Tracking
UTNotifications is an advanced and professional Unity extension that is yet very convenient and easy to
use. It provides a convenient cross-platform API for posting and handling local, scheduled (including
those appearing once and those repeating) and push notifications. It fully supports iOS (7.0 and newer),
Android (4.4 and newer, Google Play featured and Amazon Kindle Android devices) and Windows
Store/Universal Windows Platform (Windows Phone 8.1, Windows 8.1/10, Universal 8.1, Universal 10).
Features:
- Immediate and scheduled (those appearing once and those repeating) local notifications with
automated restoring on device reboot.
- Push notifications.
- 2 Android push notifications services: Firebase Cloud Messaging (FCM) & Amazon Device
Messaging (ADM) in a single build.
- Completely cross-platform API.
- The full source code is provided as well as the code of the native plugins so one can change and
adjust anything one likes.
- A demo push notifications provider web server with the source code is included.
- A sample & test scene.
- A detailed manual and an API Reference docs are included.
- Default or custom notifications sounds and icons.
- Convenient Unity editor extension for configuring.
- Notifications enabling/disabling API for all supported platforms allows one to add notifications
toggle to the game options.
- API for handling clicked & received notifications of any type both local and push.
- One can attach custom data to the notification of any type and access it while handling the
received notification.
- Hiding or cancelling a specific notification or all of them.
- Application icon badge number management API for iOS and Android.
- Android: Image notifications.
- Android: Complete integration with Android 8+ Notification Channels.
- Android: Custom buttons.
- Android: High Priority/Heads-Up notifications support.
- And more!
UTNotifications consists of two main parts: Unity client extension and a demo server which shows you
how to send push (remote) notifications. For the production version of your application your own game
server or a dedicated notifications server is required, but you can use the provided demo server source
code as you like. There is also a number of third-party solutions for the push notification servers, such as
free and open source ​Uniqush​, and services like ​OneSignal​, which are compatible with UTNotifications
as it uses plain iOS, Google Android, Amazon Android & Windows push notifications services. You can
also leverage the asset for local/scheduled notifications only - in that case you don’t need any backend.
The asset works well with any edition of Unity 5.4 or newer.

Getting Started
Once you installed the asset into your project, you’re able to open its settings from Unity menu: ​Edit ->
Project Settings -> UTNotifications ​(Unity restart may be required first time to see this menu item).

Local notifications doesn’t require any additional setting up. Configuring push notifications services is
described below​.

There is an example scene: ​Assets/UTNotifications/Sample/UTNotificationsSample.unity​ which
you can use to get familiar with many of the UTNotifications features and how to use them. It also helps
you checking whether the configuration is correct.

You can also add script ​UTNotifications.​UTNotificationsSample
(​Assets/UTNotifications/Sample/UTNotificationsSample.cs​)​ ​to any GameObject in your own
scene to access this test menu. Please note that notifications are not available in some device emulators
and in the Unity editor, so please deploy to a device in order test or debug notifications related
functionality.
You can find an API Reference in UTNotifications Unity Settings and ​here​.

Creating Local Notifications
Local notifications are notifications shown by request of the client application itself. With UTNotifications
you can create immediate, scheduled and repeated scheduled local notifications.
First thing you need to know, is that the entire UTNotifications API is stored in ​namespace
UTNotifications​. So you might like adding a using statement to easily access the namespace contents:
​using​ UTNotifications;

Now let’s Initialize ​UTNotifications.Manager​. It should be done prior to accessing any UTNotifications
methods. ​Awake()​ or ​Start()​ method of some MonoBehaviour is a good place for it:
​public​ ​void​ Start()
{
UTNotifications.​Manager​.Instance.Initialize(​false​);
}

UTNotifications.​Manager​.Instance ​(or just ​Manager​.Instance ​if you added ​using​ UTNotifications​) is
the main access point to all methods of UTNotifications. It returns a ​singletone​ instance of the
UTNotifications.​Manager​ class. We specified ​false​ in the example above as the value of argument
willHandleReceivedNotifications​ of U
​ TNotifications.​Manager​.Initialize​ as we don’t have any

intention to handle shown notifications at the moment. For more info on handling notifications, please
see the ​appropriate section​ of the manual.
Now you can start creating local notifications. F.e.:
UTNotifications.​Manager​.Instance.PostLocalNotification(​"Title"​, ​"Text"​, 1);

It creates an immediate local notification with title = “Title”, text = “Text” and id = 1. Notification ids are
used to identify each notification. F.e. a new notification with the same id as an old one replaces that old
notification instead of creating a second separate notification. id is also used to hide or cancel a specific
notification (see the ​API Reference​ for the details).
Note​ that with the default settings you will not be able to see or hear any immediate notifications on any
of the supported platforms, because notifications are not shown while the application is running by
default. You can modify this behaviour in UTNotifications Settings: ​Common Android Settings​ -> ​Show
Notifications​ & ​Windows Store Settings​ -> ​Notify only when app is closed or hidden​.
Unfortunately, iOS doesn’t allow to control it: you can never see any notifications while the app is running
on iOS.
Let’s now schedule a local notification:
UTNotifications.​Manager​.Instance.ScheduleNotification(​15​, ​"Title"​, ​"Text"​, 2);

A local notification with title = “Title”, text = “Text” and id = 2 wll be triggered in 15 seconds after that
code is executed. You can also specify a ​System.​DateTime​ value as the first argument as a date and
time to trigger the notification.
Similarly you can create a repeated scheduled notification:
UTNotifications.​Manager​.Instance.ScheduleNotificationRepeating(​5​, ​25​, ​"Title"​,
"Text"​, 3);

This notification ​with title = “Title”, text = “Text” and id = 3 will be shown first time in 5 seconds after that
code is executed and then will be repeated every 25 seconds. There is also a ​System.​DateTime​ version
of this method.
Note​ that the repeating times are approximate and may differ, especially on iOS, where only fixed
options like every minute, every day, every week and so on are available. So the provided interval value
will be approximated by one of the available options.
On Android there is a way to show a notification containing an image:
Manager​.Instance.ScheduleNotification(​10​, ​"Image Notification"​,
​"Image notification text"​, ​4​, ​new​ ​Dictionary​<​string​, ​string​>
{
{
​"image_url"​,
​"http://thecatapi.com/api/images/get?format=src&type=png&size=med"
​}
});

For more details on image notifications see ​Image Notifications (Android)​. See also ​Open URL
Notifications (Android)​ and ​Notification Buttons (Android)​ for more information on some more options.
You can also configure notifications icons, sounds and other notifications attributes. For more details see
Using Notification Profiles (Sounds, Icons and Other Attributes)​.

Using Notification Profiles (Sounds, Icons and Other Attributes)
By default any notification will be posted with a default system notification sound and the application
icon. UTNotifications allows definining custom sounds and icons for notifications (custom notification
icons are not supported by iOS, no customization is currently supported on Windows Store). What sound
and icon is used for a specific notification is defined by a ​notification profile​ - named set of the
notification options. Notification profiles also define ​Android 8+ Notification Channels​ - named
user-configurable groups of notifications.
For example, a game might have two kinds of notifications - when a player receives a gift and when
some in-game research is complete. One can define two notification profiles: ​“gift”​ &
“research_complete”​. First one will use a gift box icon when shown and some specific sound, and
second one will have a bulb icon and another sound.
You can create and edit the notification profiles in UTNotifications editor: ​Edit -> Project Settings ->
UTNotifications -> Notification Profiles (sounds, icons and more)​.
Each of functions U
​ TNotifications.Manager.Instance.PostLocalNotification​,
UTNotifications.Manager.Instance.ScheduleNotification​ and
UTNotifications.Manager.Instance.ScheduleNotificationRepeating​ has optional argument ​string
notificationProfile​ which defines a name of a notification profile used for this notification.
For push notifications you can also specify a notification profile.
- iOS (APNS)​.
Notification profile name is specified as a sound in the APNS json payload:
{
"aps":
{
<...>
"sound" : "​Data/Raw/​​"
}
}

Note that ​​ should not contain any file extension.
-

Android​.
Notification profile name is stored in node ​“data”​ of the notification json.
FCM​:
{
"registration_ids":<...>,
"data":
{
<...>,
"notification_profile":​""
}
}

ADM:
{
"data":
{

<...>,
"notification_profile":​""
}
}

-

Windows Store (WNS):
Notification profile name is stored in the payload json root node:
{
<...>,
"notification_profile":​""
}

Push notifications sent from the UTNotificationsSample (​Notify all registered devices​) use
notification profile ​“demo_notification_profile”​. You can try configuring a profile with that name to
see how the feature works.
There is a predefined profile ​“default”​, which is used on Android when no notification profile is
specified for a notification. It’s ​important​ to configure at least its Small Icon (Android 5.0+): Android,
starting with version 5.0, ignores any color information of small notification icons: the icons are
considered to be completely white and only alpha channel of the icons is applied (so icons can be only
white & transparent). So any non-transparent icons turn into just white squares when using as small
notification icons.

Custom User Data & Handling Notifications
UTNotifications provides a way to handle a list of all notifications shown before or when an app was
running, and also a notification which was clicked by a user. Besides, each notification (local and push)
can contain some custom data which can be read when handling a clicked or received notification.
In order to do so, please subscribe to ​UTNotifications.​Manager​ ​events ​OnNotificationClicked​ ​/
OnNotificationsReceived​ ​before​ initializing UTNotifications. F.e.:
UTNotifications.​Manager​ notificationsManager = UTNotifications.​Manager​.Instance;
notificationsManager.OnNotificationClicked += (notification) =>
{
​Debug​.Log(notification.text + ​" clicked"​);
};
notificationsManager.OnNotificationsReceived += (receivedNotifications) =>
{
​foreach​ (​var​ notification ​in​ receivedNotifications)
{
​Debug​.Log(notification.text + ​" received/triggered"​);
}
};
notificationsManager.Initialize(​true​);

Here we specified ​true​ as the value of argument ​willHandleReceivedNotifications​ of
UTNotifications.​Manager​.Initialize​, as we’d like to handle received notifications with
OnNotificationsReceived​. Please never set it to ​true​ if you don’t intend to handle received notifications
as it can be heavy for the app performance. Handling clicked notifications doesn’t require turning on
willHandleReceivedNotifications​.
Note​ that iOS doesn't provide the list of all notifications shown when the app wasn't running in
foreground. Received notifications list will contain only the notification which was clicked and all the
notifications shown while the app is running in foreground. On the rest platforms you'll receive a list of all
the shown notifications, even ones shown while the app was closed.
You can specify a Dictionary​<​string​, ​string​>​ conaining any custom data which can then be accessed
when handling clicked or received notifications as ​ReceivedNotification​.userData​. Each of the methods
for creating local notifications can accept optional value u
​ serData​. Push notifications payload is used to
get the value of u
​ serData​ when handling them.
Local notifications example:
Dictionary​<​string​, ​string​> userData = ​new​ ​Dictionary​<​string​, ​string​>();
userData.Add(​"event_type"​, ​"DAILY_GIFT_RECEIVED"​);
Manager​.Instance.ScheduleNotificationRepeating(​DateTime​.Now.AddDays(​1​),
TimeUtils​.DaysToSeconds(​1​), ​"A gift for you!"​,
"Start the game to receive your gift"​, ​5​, userData);

Push notifications example (ADM payload format):
{
"data":
{
<...>,
"event_type":"DAILY_GIFT_RECEIVED"
}
}

Now, let’s handle the user data:
// Should be subscribed before initializing UTNotifications.Manager
UTNotifications.Manager.Instance.OnNotificationClicked += (notification) =>
{
​if​ (notification.userData != ​null​ &&
notification.userData.ContainsKey(​"event_type"​))
{
​string​ eventType = notification.userData[​"event_type"​];
​switch​ (eventType)
{
​case​ ​"DAILY_GIFT_RECEIVED"​:
ShowDailyGiftDialog();
​break​;

}

​default​:
Debug.LogWarning(​"Unexpected event_type: "​ + eventType);
​break​;

}
};

Notification Buttons (Android)
Any Android notification can contain an arbitrary number of custom buttons: local, scheduled or push.
Each of the buttons has a title and optionally custom user data as Dictionary​​.

Each of functions ​UTNotifications.Manager.Instance.PostLocalNotification​,
UTNotifications.Manager.Instance.ScheduleNotification​ and
UTNotifications.Manager.Instance.ScheduleNotificationRepeating​ has optional argument
ICollection​<​Button​> buttons​ to specify the notification buttons, f.e.:

using​ UTNotifications;
using​ System.Collections.Generic;
List​<​Button​> buttons = ​new​ ​List​<​Button​>();
// (Android only) Just a simple button with some custom user data assigned
buttons.Add(​new​ ​Button​(​"Open App"​, ​new​ ​Dictionary​<​String​, ​String​> {{​"button"​,
"first"​}}));
// (Android only) "open_url" in userData opens an URL on a notification click
instead of the application. Can be used for the whole notification or a specific
button, like here.
buttons.Add(​new​ ​Button​(​"Open URL"​, ​new​ ​Dictionary​<​String​, ​String​>{{​"open_url"​,
"https://assetstore.unity.com/packages/tools/utnotifications-professional-local-pu
sh-notification-plugin-37767"​}, {​"button"​,​"second"​}}));
// Repeating scheduled notification
Manager​.Instance.ScheduleNotificationRepeating(​DateTime​.Now.AddSeconds(​10​), ​25​,
"Scheduled Repeating Notification"​, ​"Click to open the app"​,
RepeatingNotificationId, userData, ​"demo_notification_profile"​, ​1​, buttons);

Push notifications (FCM & ADM) can contain custom buttons too:
"data":
{
<...>,
"buttons":
"[
{
\"title\":\"\",
\"\":\"\", ...
},
<...>
]"
}

Please note, that JSON value of node “​buttons​” is actually a JSON array converted to ​string​.
Buttons are not supported on the rest platforms at the moment and will be ignored on them.

Image Notifications (Android)
With UTNotifications you can create image notifications, i.e. notifications containing large images. It’s
supported with both local and push notifications. In order to create an image notification ​add a user data
argument​ ​“image_url”​ with a string value, containing an URL of a picture to use. ​“image_url”
value may be a normal http:// or https:// URL, or an Android file system URL: ​file:///​.

Open URL Notifications (Android)
You can also make clicking on a notification open a specified URL in a browser instead of activating your
application. It’s supported by both local and push notifications. To achieve that ​add a user data argument
“open_url”​ which string value should contain an URL to open on a click.
Note​, that on the rest platforms it still will activate your app.

Push Notifications Overview
Push notifications, also known as server notifications or remote notifications, are the notifications to a
device without a specific request from the client. Unlike local notifications, which don’t include any server
part, push notifications always originate from a server.
Different devices rely on different methods to deliver push notifications. Apple, for example, uses the
Apple Push Notification Service. Android doesn’t have a common system, but different Android devices
provide different push notifications services. ​Google Play​ featured ones (i.e. most of Android devices)
use Firebase Cloud Messaging (FCM, ex Google Cloud Messaging - GCM). Amazon Android devices
(entire ​Kindle Fire​ series) don’t support FCM and have their own Amazon Device Messaging (ADM)
API. Windows 8.1+ and Windows Phones use Windows Push Notification Services (WNS).
UTNotifications rely on OS specific push notifications systems internally, but externally provides the
common for all the supported services client side API.
No matter what OS and service is used, the general scheme is the same:

1. Initialize and request a unique registration id​. The client application using a push notifications
service (“PNS”: one of APNS, FCM, ADM and WNS) API requests a unique identifier for that
specific PNS of that specific application on that specific device. Please note that in general it
should be done on every start of the app because this identifier can get out of date and the
application would receive a new one. With UTNotifications it’s done by calling
UTNotifications.Manager.Instance.​Initialize(...)​ function.
2. Registration id received​. The application (game client) receives the id from PNS API
asynchronously or synchronously. In order to receive it you will subscribe to
UTNotifications.Manager.Instance.​OnSendRegistrationId​ event (please subscribe before
calling the I
​ nitialize​ function because in some cases receiving the registration id may be done
synchronously​).

3. Store the registration id on your game/notifications server​. You send the received id to your
own server which will later send push notifications. You do it in the delegate subscribed to the
OnSendRegistrationId​ event.
4. Use the stored registration id to send a notification​. Your server requests the server side of
PNS API to send (i.e. “push”) custom notification to one or more clients using their registration ids
which were previously stored. Please see D
​ emoServer.PushNotificator​ class source code
(​Assets/UTNotifications/Editor/DemoServer/src/DemoServer/PushNotificator.java​) for
an example.
5. The notification is delivered to the appropriate client​. PNS delivers the notification to the
client with specified registration id. You don’t have to do anything on this stage with
UTNotifications (cause it takes care of everything with both Android PNSes and there is nothing
to be done on iOS). A click on the notification will open your application: it’s being started if has’t
been and goes foreground if it was in a background. If you would like to handle incoming
notifications please see API Reference for
UTNotifications.Manager.​OnNotificationsReceived​ event and
UTNotifications.Manager.​Initialize(...)​ function.
Please note that every push notification service requires some configuring. This is described in the
sections below.

What You Need for Push Notifications
General
-

A server that is connected to the internet. Push notifications are always sent by a server. For
development you can use your computer as the server but for production use, you need at least
something like a VPS (Virtual Private Server).
A cheap shared hosting account is not good enough in most cases. You need to be able to run a
background process on the server and be able to make outgoing TLS connections on certain
ports.

iOS: Apple Push Notification Service (APNS)
-

-

An iPhone or iPad. Notifications do not work in the simulator, so you will need to test on the
device.
An iOS Developer Program membership. You need to make a new App ID and provisioning
profile for each app that uses push, as well as an SSL certificate for the server. You do this at the
iOS Provisioning Portal (this is described below).
An OS X computer.

Android: Firebase Cloud Messaging (FCM)
-

Any Google Play featured device with Android 4.4+.
Please note that you can’t use Firebase Console for sending push notifications to FCM-enabled
devices due to its limitations. Fore more details see ​Push Notifications Payload Format/FCM​.

Android: Amazon Device Messaging (ADM)
-

Any Amazon Kindle Fire device (tablet or phone) except the 1st generation of Kindle Fire tablets
which don’t support push notifications.

Windows Store: Windows Push Notification Services (WNS)
-

Any Windows Phone 8.1 or Windows 8.1/10 device.

Push Notifications Payload Format
APNS​ requires any push notifications sent by your server to have a specific format. It is described ​in this
document​.
Unlike it, FCM, ADM & WNS don’t have one common format of the message payload. Each of them
accepts a JSON data payload, which then is interpreted by the client application. The client application
itself is responsible for creating notifications based on the payload received from the appropriate service.
Fortunately, UTNotifications does this nasty job for you. This is why it requires the JSON payload to be in
a specific format, which though you can configure in the asset options in the Unity editor. The default
format looks like:
FCM:
{
"registration_ids":["", ...], 
"data":
{
"title":"