跳到主要内容

0.6.1

注意

该门户网站正在开发中。文档的完整版本请看这里.

为了推送通知的运行，必须遵守以下条件：

  1. 用户的设备上必须安装 RuStore。
  2. RuStore 必须支持推送通知功能。
  3. RuStore 应用程序应允许在后台模式下运行。
  4. 用户必须在 RuStore 中获得授权。
  5. 应用程序的签名指纹必须与 RuStore 控制台中添加的指纹匹配。

在项目中集成​

要集成，请下载RuStorePush SDK并将其导入项目（Assets → Import Package → Custom Package）。依赖项将通过SDK中包含的External Dependency Manager自动连接。

MinimumAPIlevel应设置为不低于24。应用程序的缩减（ProGuard/R8）目前不受支持，因此需要在项目设置中将其关闭（File → Build Settings → Player Settings → Publishing Settings → Minify）。

编辑应用程序清单​

您必须声明 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 \>

果您想更改标准通知的图标或颜色，可以添加以下元数据：

\< 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\" /\>

可以添加以下元数据以重写通知渠道：

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

您添加自己的推送通知渠道时，您需要自行创建该渠道。

初始化​

为了初始化，需要在项目中重写 Application 类。所需的源代码已包含在文件 Assets/RuStoreSDK/PushClient/Android/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 - Application类的实例。

要在项目的 AndroidManifest.xml 中指定这个类：

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

将使用在Unity编辑器中设置的参数进行初始化。在编辑器菜单中选择Window → RuStoreSDK → Settings → Push Client:

  • VKPNSProjectId - 您在 RuStore 开发者控制台中项目的标识符；
  • AllowAllow Native Error Handling - 允许原生 SDK 中的错误处理。错误处理

从 C#### 代码中调用库方法之前，必须先调用它的初始化：

var сonfig =  new RuStorePushClientConfig() {    \`\`allowNativeErrorHandling =  true ,    \`\`messagingServiceListener = pushServiceListener,    \`\`logListener = pushLogListener};RuStorePushClient.Instance.Init(сonfig);
  • allowallowNativeErrorHandling - 允许原生 SDK 中的错误处理；错误处理
  • messagingServiceListener - 实现 IMessagingServiceListener 接口的类对象；
  • logListener - 实现 ILogListener 接口的类对象。

检查获得推送通知的可能性​

为了推送通知的运行，必须遵守几个条件：

  • 用户的设备上必须安装 RuStore。
  • RuStore 必须支持推送通知功能。
  • RuStore 应用程序应允许在后台模式下运行。
  • 用户必须在 RuStore 中获得授权。

了检查上述条件，可以使用 RuStorePushClient.checkPushAvailability 方法。

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

使用推送令牌的方法​

获取用户的推送令牌​

在库初始化之后，您可以使用 RuStorePushClient.GetToken() 方法来获取当前用户的推送令牌。如果用户没有推送令牌，则该方法将创建并返回新的推送令牌。

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

删除用户的推送令牌​

在库初始化之后，您可以使用 RuStorePushClient.DeleteToken() 方法来删除当前用户的推送令牌。

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

用于处理推送主题的方法​

订阅主题的推送通知​

在初始化库之后，您可以使用 SubscribeToTopic("your_topic_name") 方法来订阅主题。

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

取消订阅主题的推送通知​

在初始化库之后，您可以使用 UnsubscribeFromTopic("your_topic_name") 方法来取消订阅主题。

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

使用 RuStore 的操作MessagingService​

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

OnNewToken - 在接收到新的推送令牌时将被调用。

调用此方法后，您的应用程序负责将新的推送令牌传递到自己的服务器。

OnMessageReceived - 在接收到新的推送通知时将被调用。

可以从message.data字段获取推送通知的payload(Dictionary<string, string>)。

OnDeletedMessages - 如果一个或多个推送通知没有被送达到设备，将会调用此方法。

这可能是因为通知的生命周期在送达设备前已经结束。

在调用此方法时，建议与您的服务器同步，以免错过数据。

OnError - 如果在初始化过程中发生错误，将会调用此方法。

可能的错误：

  • UnauthorizedException - 用户未在 RuStore 中授权。
  • HostAppNotInstalledException - 用户设备上未安装RuStore应用程序。
  • HostAppBackgroundWorkPermissionNotGranted - RuStore 没有在后台工作的权限。

有上述方法都将在后台线程上被调用。

通知结构体​

完整通知的结构体​

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 - 消息的唯一ID。它是每个消息的标识符。
  • priority - （当前不考虑）返回优先级值。目前有以下选项：
    • 0 - UNKNOWN.
    • 1 - HIGH.
    • 2 - NORMAL.
  • ttl - Int类型的推送通知生命周期（以秒为单位）。
  • collapseKey - （当前不考虑）通知组的标识符。
  • data - 一个字典，在其中可以传递额外的通知数据。
  • rawData - data 字典以字节数组形式。
  • 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 - 通知的标题；

  • body - 通知的正文；

  • channelId - 可以指定的渠道，用于发送通知（适用于Android 8.0及更高版本）；

  • imageUrl - 插入通知中的图片的直接链接（图片大小不超过1兆字节）；

  • color - 通知的颜色（Notification.color）。颜色需要以十六进制格式传递，为字符串格式（例如："#A52A2A"）；

  • icon - 通知的图标。图标应存放在应用程序的资源中（res/drawable）。参数的值` - 一个字符串，与资源名称相匹配；

    • 例如：在 res/drawable 中有一个名为small_icon.xml的图标，在代码中通过R.drawable.small_icon访问。为了在通知中显示这个图标，服务器需要在 "icon" 参数中放入 "small_icon" 的值。

  • clickAction - intent点击通知时，用于打开活动的intent action。

创建发送通知的渠道​

对于将要发送通知的渠道，适用以下优先级顺序：

  1. 如果 push 通知中包含 channelId 字段，那么 SDK 将会把通知发送到这个渠道。同时，您的应用程序负责提前创建这个渠道。
  2. 如果 push 通知中没有 channelId 字段，但您的应用程序在 AndroidManifest.xml 中指定了带有渠道的参数，则将使用 AndroidManifest.xml 中的渠道。您的应用程序负责创建这个渠道。
  3. 如果推送通知中没有 channelId字段，并且您的应用程序的AndroidManifest.xml` 中没有设置默认渠道，则RuStoreSDK将自行创建一个渠道并向其发送通知。以后，所有未指定渠道的通知都将发送到这个渠道。

点击通知时打开 Activity​

默认情况下，当点击通知时，SDK 会打开带有 "android.intent.action.MAIN"的 action。如果存在 clickAction 字段，RuStoreSDK将打开符合指定action的 Intent filter 的活动。

为了使 SDK 能够在点击通知时打开活动 （这也适用于默认的活动 ），在应用程序的清单中相应的活动元素下需要添加字符串。如果没有这个字符串，SDK 将无法打开活动。

错误处理​

可能的错误：

  1. RuStoreNotInstalledException - 用户设备上未安装 RuStore。
  2. RuStoreOutdatedException - 用户设备上安装的 RuStore 不支持推送通知功能。
  3. RuStoreUserUnauthorizedException - 用户未在 RuStore 中授权。
  4. RuStoreFeatureUnavailableException - RuStore 没有在后台工作的权限。
  5. RuStoreException - RuStore的基本错误，其他错误均继承自此。

果在 SDK 初始化时传递了参数 allowNativeErrorHandling == true，在出现错误时，除了调用相应的 onFailure 处理程序外，该错误还会传递到原生 SDK 的 resolveForPush 方法中，以便向用户显示错误对话框：

fun RuStoreException.resolveForPush(context: Context)

初始化后，可以通过设置 AllowNativeErrorHandling 属性来更改此行为：

RuStorePushClient.Instance.AllowNativeErrorHandling =  false ;