Push notifications SDK for Unity (version 1.0.0)

Push notification terms and conditions:

• The current version of RuStore is installed on the user's device.
• RuStore app should support push notification functionality.
• The RuStore app is allowed access to work in the background..
• The user is authorized in RuStore.
• The application's signature fingerprint must match the fingerprint added to RuStore Console.

Implementation example

Checkout example app to learn how to implement push notification SDK.

Connecting to project

1. Download RuStore Push SDK.

2. Import SDK to your project: Assets — Import Package — Custom Package. Dependencies are included automatically using the External Dependency Manager (included in the SDK).

3. Minimum API level must be set to at least 24.

4. Application minification (ProGuard/R8) must be disabled in the project settings (File → Build Settings → Player Settings → Publishing Settings → Minify). It is not currently supported.

Editing app manifest

Declare RuStoreUnityMessagingService:

<service
    android:name = "ru.rustore.unitysdk.pushclient.RuStoreUnityMessagingService"
    android:exported = "true"
    tools:ignore = "ExportedService">
    <intent-filter>
        <action android:name = "ru.rustore.sdk.pushclient.MESSAGING_EVENT" />
    </intent-filter>
</service>

If you need to change the icon or colour of the standard notification, add:

AndroidManifest.xml

<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_icon"
    android:resource="@drawable/ic_baseline_android_24" />
<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_color"
    android:resource="@color/your_favorite_color" />

If you need to override the notification channel, add:

AndroidManifest.xml

<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_channel_id"
    android:value="@string/pushes_notification_channel_id" />

You must create the channel yourself if you add a push notification channel.

Initialization

Override the Application class in the project for initialisation. The Assets/RuStoreSDK/PushClient/Android/RuStoreUnityApplication.java file already contains the required source code:

RuStoreUnityApplication.java

package ru.rustore.unitysdk;
import android.app.Application;
import ru.rustore.unitysdk.pushclient.RuStoreUnityPushClient;
public class RuStoreUnityApplication extends Application {
    @Override public void onCreate() {
         super .onCreate();
         RuStoreUnityPushClient.init(
            application = this
         );
    }
}

• application is an instance of the Application class.

Specify this class in AndroidManifest.xml:

AndroidManifest.xml

<application android:name = "ru.rustore.unitysdk.RuStoreUnityApplication">

The library initialization parameters are configured in the Unity editor. In the editor menu select Window → RuStoreSDK → Settings → Push Client.

• VKPNS Project Id — project ID from RuStore Console. To get it, go to "Push Notifications" - "Projects" and copy the value into the "Project ID" field.
• Allow Native Error Handling — allows error handling in a native SDK.

Call the library initialisation before calling library methods from C# code:

var сonfig =  new RuStorePushClientConfig() {
    allowNativeErrorHandling = true ,
    messagingServiceListener = pushServiceListener,
    logListener = pushLogListener
};
RuStorePushClient.Instance.Init(сonfig);

• allowNativeErrorHandling — allows error handling in a native SDK (see more in Error handling.
• messagingServiceListener — class object that implements the IMessagingServiceListener interface.
• logListener — class object that implements ILogListener.

Push notifications availability check

To check the listed prerequisites, use the RuStorePushClient.checkPushAvailability method.

RuStorePushClient.Instance.CheckPushAvailability(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (response) => {
        if (!response.isAvailable) {
            // Process push unavailable
        }
    });

Push token methods

Getting user push token

caution

The method will create and return a new push token if the user does not have one.

Once the library has been initialised, you can use the RuStorePushClient.getToken(), method to get the user's current push token.

RuStorePushClient.Instance.GetToken(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (token) => {
        // Process success
    });

Deleting user push token

After the library has been initialised, the user's current push token can be removed using the RuStorePushClient.deleteToken() method.

RuStorePushClient.Instance.DeleteToken(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    });

Push topic methods

Push topic subscription

Once the library is initialised, you can use the SubscribeToTopic(your_topic_name) method to subscribe to a topic.

RuStorePushClient.Instance.SubscribeToTopic(
    topicName: "your_topic_name" ,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    });

Unsubscribe from push topic

Once the library is initialised, you can use the UnsubscribeFromTopic(your_topic_name) method to unsubscribe from the topic.

RuStorePushClient.Instance.UnsubscribeFromTopic(
    topicName: "your_topic_name" ,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    });

Retrieving data from RuStore SDK

public interface IMessagingServiceListener {
    public void OnNewToken(string token);
    public void OnMessageReceived(RemoteMessage message);
    public void OnDeletedMessages();
    public void OnError(List<RuStoreError> errors);
}

Method name	Description
onNewToken	Called when a new push token is received. After this method is called, your app will be responsible for delivering the new push token to its server. This method returns the value of the new token.
onMessageReceived	Called when a new push token is received < p/> If there is data in notification object, RuStoreSDK will display the notification itself. If you don’t want RuStoreSDK to display notification itself, use data object, and leave notification object empty. Called in any case. < p/> Push notification’s payload Dictionary<string, string> may be obtained from message.data field.
DeletedMessagesResponse	Called when one or more push notifications fail to reach the device. For example, if the notification's lifetime has expired before delivery. < p/> When calling this method, it is recommended that you synchronise with your server to avoid missing data.
ErrorResponse	Called when an error occurs during initialisation. It returns an array of objects with errors. < p/> Possible errors: UnauthorizedException — user not authorized on RuStore. HostAppNotInstalledException — user’s device doesn’t have RuStore app installed. HostAppBackgroundWorkPermissionNotGranted — RuStore app is not allowed to run in the background. All possible errors are described in Error handling.

Notification structure

Структура полного уведомления

public class RemoteMessage {
    public string collapseKey;
    public Dictionary< string ,  string > data;
    public string messageId;
    public Notification notification;
    public int priority;
    public sbyte [] rawData;
    public int ttl;
}

• messageId — unique message ID. It corresponds to an ID of each message.

• priority — returns the priority value (currently disregarded).

  The following options are now available:

  • 0 — UNKNOWN.
  • 1 — HIGH.
  • 2 — NORMAL.

  < p/>

• ttl — push notification lifetime of Int type in seconds.

• from — field which shows the notification's origin: < p/>

  • The field displays the topic name for notifications sent to it.
  • Otherwise it is part of your service token.

  < p/>

• collapseKey - notification group ID (currently disregarded).

• data — dictionary to which additional notification data can be passed.

  .

• rawData — dictionary of data as an array of bytes.

• notification — notification object.

Структура объекта Notification

public class Notification {
    public string title;
    public string body;
    public string channelId;
    public string imageUrl;
    public string color;
    public string icon;
    public string clickAction;
}

• title — notification header.

• body — notification body

• channelId — option to create the channel to which notification will be sent. For Android 8.0 or later.

• imageUrl — direct link to an image to be inserted into the notification. The size of the image must not exceed 1 Mbyte .

  .

• color — notification colour in HEX format, string. For example, #0077FF.

• icon — notification icon from res/drawable in a string format that matches the resource name. < p/> For example, res/drawable has an icon small_icon.xml, which is accessible in code via R.drawable.small_icon. For the icon to be displayed in the notification, the server must specify a icon value of small_icon. < p/>

• clickAction — intent action, with which activity is opened when a notification is pressed on..

Creating notification channel

The channel to which the message is sent will be given the following priority:

• If the push notification has a channelId field, RuStore SDK will send the notification to the specified channel. Your app must create this channel in advance.

• If there is no channelId field in the push notification, but your app has specified a parameter with a channel in AndroidManifest.xml, the specified channel will be used. Your app must create this channel in advance.

• If there is no channelId field in the push notification and the default channel is not set in AndroidManifest.xml, RuStore SDK will create a channel and send the notification to it. From now on, all notifications without an explicit channel will be sent to that channel..

Errors

• RuStoreNotInstalledException — RuStore not installed on user's device.

• RuStoreOutdatedException — RuStore app on the user's device does not support push notifications.

• RuStoreUserUnauthorizedException — user not authorized on RuStore.

• RuStoreFeatureUnavailableException — RuStore app is not allowed to run in the background..

• RuStoreException — basic RuStore error, from which all other errors are inherited..

If you passed the allowNativeErrorHandling == true parameter when initialising the SDK, in case of an error:

• The corresponding onFailure handler will be called.

• The error will be passed to the resolveForPush method of the native SDK. This is used to show the error dialogue to the user.

Метод resolveForPush

fun RuStoreException.resolveForPush(context: Context)

To disable passing the error to the native SDK, set the false value for the AllowNativeErrorHandling property.

Запрет нативной обработки ошибок

RuStorePushClient.Instance.AllowNativeErrorHandling =  false ;

See also

• Sending push notifications (API)
• Sending push notifications by topic (API)
• Working with user segments (API)