Configure push notifications for Unity

Introduction

Even if your game is not currently active, you can notify the user when a certain event takes place. Some typical examples are: building completed, a friend message has arrived, etc.

Push notifications can trigger different events:

  • Display a short text message
  • Play a brief sound
  • Set a number in a badge on the game’s icon

Gamedonia Backend offers the possibility to send Push notifications from:

If you haven't done it yet, you need to configure the push certificates on your Apple or Google account and at the Gamedonia Dashboard.

Follow these guides to configure them on:

Setup a Unity project

Gamedonia Push Script

The Gamedonia prefab comes only with the Gamedonia main component attached, so the first step to start using Push Notifications in your game is to attach the GamedoniaPushNotifications script to the Gamedonia game object on your scene. The script is located under Assets/Plugins/Gamedonia.

Android Sender Id: Project Number assigned when setting up Google Cloud Messaging.

You don't need to fill this field if you’re developing for iOS only.

Next, you will have to edit the Manifest code to allow your game to send Push Notifications.

Client configuration

Android manifest

You don't need to do this step if you’re developing for iOS only.

  1. Open the project file AndroidManifest.xml. Google Cloud Messaging has some minimum API level requirements for development and testing, which the minSdkVersion property in the Manifest must conform to. Consult Set Up Google Play Services SDK to determine how low you can set this value when you need to set it below 16 due to using an older device. Set the property appropriately.

  2. Add the following new permissions after the existing element, replacing **your_package_name** with the name of the app package for your project. To check the current name of your package go to File > Build Settings > Player Settings and select the Android tab. You will find it at the Bundle Identifier field.

        <permission android:name="**your_package_name**.permission.C2D_MESSAGE" 
            android:protectionLevel="signature" />
        <uses-permission android:name="**your_package_name**.permission.C2D_MESSAGE" /> 
        <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
        <uses-permission android:name="android.permission.GET_ACCOUNTS" />
        <uses-permission android:name="android.permission.WAKE_LOCK" />
    
  3. Modify the main activity class. We need to change the class com.unity3d.player.UnityPlayerProxyActivity to com.gamedonia.sdk.GamedoniaUnityPlayerProxyActivity. The main activity in the manifest should look like the one in the following code block:

    <activity android:name="com.gamedonia.sdk.GamedoniaUnityPlayerProxyActivity"
                      android:label="@string/app_name"
                      android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>

     

  4. Add the following code after the main activity inside your application tag, replacing it with the name of the app package for your project:

        <activity android:name="com.gamedonia.pushnotifications.GamedoniaPushHandlerActivity" />
        <receiver android:name="com.gamedonia.pushnotifications.PushBroadcastReceiver"
            android:permission="com.google.android.c2dm.permission.SEND">
            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />
                <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
                <category android:name="**your_package_name**" />
            </intent-filter>
        </receiver>
    
        <service android:name="com.gamedonia.pushnotifications.PushIntentService" />

Receive push notifications

To receive push notifications on on your game, you only need to add a couple of lines to your code:

Attach a handler in your Start() function with the following code:

//Handle push
GDPushService service = new GDPushService();
service.RegisterEvent += new RegisterEventHandler(OnNotification);
GamedoniaPushNotifications.AddService(service);

Then, create a new OnNotification delegate into the body of your script:

void OnNotification(Dictionary<string,object> notification) {
    Hashtable payload = notification["payload"] != null ? (Hashtable) notification["payload"] : new Hashtable();
    string type = payload.ContainsKey("type") ? payload["type"].ToString() : "";
    switch(type) {
        case "**type_of_the_notification**":
            //TODO: process the message
            break;
        default:
            // Do nothing
            break;
    }
}

Send Push from Server Code

You can send push notifications from a server script. To know more about how to create a Server script, check out our Server Code guide. The following code is an example of how to send a push notification from server script:

var notification = new Object();
notification.type = "**type_of_the_notification**";
notification.alert = "New Notification!!";
notification.badge = 1;
gamedonia.push.send(notification, PLAYER_ID);

To send a push notification like this, you need to know the Gamedonia PLAYER_ID of the user you want to send the notification to. To learn more about user management, check our Users guide.

Send Push from Composer

Gamedonia’s Push Notification Composer allows you to send quick messages to your users, or to the user segment ( group of users who share common properties) of your choice.

You’ll be able to set up the following:

  • Message
  • Platforms
  • Recipients
  • Delivery Time
  • Optional settings

Message

It's the text users will receive on their devices. You can preview how it will look like on different devices.

Platforms

You can send push notifications to Android and iOS devices only if you have previously set up Push Credentials on the Dashboard for those platforms.

Recipients

Broadcast: to send the push to all of your users.

Segment: add a segment for your users to target specific groups of users.

Then, on the Recipients section of the Composer, select the segment you want to send the push to.

Delivery Time

At the moment, we deliver all push notifications at the very moment you click on Send Notifications. So, your recipients will receive them as soon as possible.

Optional settings

Sound (iOS)

Choose a special sound file to play when your push is received.

The sound file you specify here needs to be shipped with the game.

Badge Number (iOS)

Sets the number of messages delivered to the device. It’ll appear inside the notification badge in the top right corner of the game icon. This is typically reset every time a user restarts the app or resumes it from the background.

Sending +1 will add one to the number displayed in the badge. If you set 50 it will show 50 and if you send 0 it will clear the count, though using increments (+1) is the most common badge count.

Delay while idle & Collapse key (Android)

If the device is connected but idle, the message will still be delivered right away unless the delay_while_idle flag is set to true. Otherwise, it will be stored at the GCM servers until the device becomes awake. And that's where the collapse_key flag plays a role: if there is already a message with the same collapse key (and registration ID) stored and waiting for delivery, the old message will be discarded and the new message will take its place (that is, the old message will be collapsed by the new one). However, if the collapse key is not set, both the new and the old messages are stored for future delivery. Collapsible messages are also called send-to-sync messages.

Time to Live (Android)

This defines how long (in seconds) the message should be kept on GCM storage if the device is offline. The default timeout is 4 weeks, unless the time_to_live flag is set.

Key & Value (Android)

You can send key/value pairs of data directly with any push from within the Push Composer.

Your game can be programmed to respond to the data in some way (open to a particular section, load an article, etc).

When you’re finished composing, simply click on the Send Notifications button to send the push notifications.

Congrats! You’ve just sent a custom tailored push notification.