跳到主要内容

1.1.0

注意

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

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

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

添加存储库​

连接本地存储库：

repositories {    \`\`maven {        \`\`url = uri( \"https://artifactory-external.vkpartner.ru/artifactory/maven\" )    \`\`}}

集成依赖项​

在您的配置文件中添加以下代码以连接依赖项：

dependencies {    \`\`implementation( \"ru.rustore.sdk:pushclient:1.2.0\" )}\<br\>

编辑您的应用程序的清单​

声明扩展 RuStoreMessagingService 的服务：

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

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

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

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

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

加推送通知渠道时，您必须自行创建该渠道。

初始化​

要进行初始化，需要在RuStore 控制台系统中获得项目 ID。 为此，请转到应用程序页面的"推送通知"部分，然后选择"项目"。

要进行初始化，请在项目的 Application 中添加以下代码：

classApp: Application() {    \`\`override fun onCreate() {        \`\`super .onCreate()        \`\`RuStorePushClient.init(            \`\`application =  this ,            \`\`projectId =  \"i5UTx96jw6c1C9LvdlE4cdNrWHMNyRBt\" ,            \`\`logger = DefaultLogger()        \`\`)    \`\`}}
  • application - Application 类的实例；
  • projectId - 您在 VKPNS 系统中项目的标识符；
  • logger - 日志器，默认使用 logcat 输出。

事件日志记录​

如果要记录推送通知库事件，请在 RuStorePushClient.init 调用中添加 logger 参数（初始化时该参数为可选参数）。

为此，您需要实现 Logger 接口：

接口Logger

interface Logger {    \`\`fun verbose(message: String, throwable: Throwable? =  null )    \`\`fun debug(message: String, throwable: Throwable? =  null )    \`\`fun info(message: String, throwable: Throwable? =  null )    \`\`fun warn(message: String, throwable: Throwable? =  null )    \`\`fun error(message: String, throwable: Throwable? =  null )    \`\`fun createLogger(tag: String): Logger}

果 Logger 没有被传递，将使用默认的实现，它使用 AndroidLog。

日志器实现示例

public class DefaultLogger(    \`\`private val tag: String? =  null ,) : Logger {    \`\`override fun verbose(message: String, throwable: Throwable?) {        \`\`Log.v(tag, message, throwable)    \`\`}    \`\`override fun debug(message: String, throwable: Throwable?) {        \`\`Log.d(tag, message, throwable)    \`\`}    \`\`override fun info(message: String, throwable: Throwable?) {        \`\`Log.i(tag, message, throwable)    \`\`}    \`\`override fun warn(message: String, throwable: Throwable?) {        \`\`Log.w(tag, message, throwable)    \`\`}    \`\`override fun error(message: String, throwable: Throwable?) {        \`\`Log.e(tag, message, throwable)    \`\`}    \`\`override fun createLogger(tag: String): Logger {        \`\`val newTag =  if ( this .tag !=  null ) {            \`\`\"\${this.tag}:\$tag\"        \`\`}  else {            \`\`tag        \`\`}        \`\`return DefaultLogger(newTag)    \`\`}}

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

关键词：RuStore，开发者，文档，RuStoreSDK，推送通知，检查获得推送通知。为了推送通知的运行，必须遵守几个条件：

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

了检查设备上是否安装了 RuStore，可以使用 RuStorePushClient.checkPushAvailability 方法：

RuStorePushClient.checkPushAvailability()    \`\`.addOnCompleteListener(object : OnCompleteListener\<FeatureAvailabilityResult\> {        \`\`override fun onSuccess(result: FeatureAvailabilityResult) {            \`\`when (result) {                \`\`FeatureAvailabilityResult.Available -\> {                    \`\`// Process push available                \`\`}                \`\`is FeatureAvailabilityResult.Unavailable -\> {                    \`\`result.cause.resolveForPush(requireContext())                \`\`}            \`\`}        \`\`}        \`\`override fun onFailure(throwable: Throwable) {            \`\`// Process error        \`\`}    \`\`})

使用推送令牌的方法​

关键词：RuStore，开发者，文档，RuStoreSDK，推送通知，使用推送令牌，推送令牌#####。用户获取推送令牌

在库初始化之后，您可以使用 RuStorePushClient.getToken() 方法来获取当前用户的push令牌。

如果用户没有推送令牌，则该方法将创建并返回新的推送令牌。

RuStorePushClient.getToken().addOnCompleteListener(object : OnCompleteListener\<String?\> {    \`\`override fun onFailure(throwable: Throwable) {        \`\`// Process error    \`\`}    \`\`override fun onSuccess(result: String?) {        \`\`// Process success    \`\`}})

删除用户的推送令牌​

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

RuStorePushClient.deleteToken().addOnCompleteListener(object : OnCompleteListener\<Unit\> {    \`\`override fun onFailure(throwable: Throwable) {        \`\`// Process error    \`\`}    \`\`override fun onSuccess(result: Unit) {        \`\`// Process success    \`\`}})

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

订阅主题的推送通知​

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

RuStorePushClient.subscribeToTopic( \"your_topic_name\" ).addOnCompleteListener(object : OnCompleteListener\<Unit\> {    \`\`override fun onFailure(throwable: Throwable) {        \`\`// Process subscribe error    \`\`}    \`\`override fun onSuccess(result: Unit) {        \`\`// Process subscribe success    \`\`}})

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

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

RuStorePushClient.unsubscribeFromTopic( \"your_topic_name\" ).addOnCompleteListener(object : OnCompleteListener\<Unit\> {    \`\`override fun onFailure(throwable: Throwable) {        \`\`// Process unsubscribe error    \`\`}    \`\`override fun onSuccess(result: Unit) {        \`\`// Process unsubscribe success    \`\`}})

从RuStore SDK 获取数据​

关键词: RuStore，开发者，文档，RuStoreSDK，推送通知 数据 数据获取。为了从RuStoreSDK获取数据，创建您自己的服务，该服务继承自 RuStoreMessagingService。

class MessagingService: RuStoreMessagingService() {            \`\`override fun onNewToken(token: String) {        \`\`}            \`\`override fun onMessageReceived(message: RemoteMessage) {        \`\`}            \`\`override fun onDeletedMessages() {        \`\`}        \`\`override fun onError(errors: List\<RuStorePushClientException\>) {        \`\`}    \`\`}

方法​

  1. onNewToken - 在接收到新的推送令牌时将被调用。调用此方法后，您的应用程序负责将新的推送令牌传递到自己的服务器。
  2. onMessageReceived - 在接收到新的推送通知时将被调用。如果notification对象中有数据，RuStoreSDK将自动显示通知。如果您不希望RuStoreSDK自动显示通知，应使用data对象，并保留notification对象为空。但无论如何都会调用onMessageReceived方法。可以从message.data字段获取推送通知的payload（Map<String, String>）。
  3. onDeletedMessages - 如果一个或多个推送通知没有被送达到设备，将会调用此方法。这可能是因为通知的生命周期在送达设备前已经结束。在调用此方法时，建议与您的服务器同步，以免错过数据。
  4. onError - 如果在初始化过程中发生错误，将会调用此方法。

可能的错误​

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

有方法将在后台模式下被调用。

通知结构体​

关键词: RuStore，开发者，文档，RuStoreSDK，推送通知，结构体#####，完整通知的结构体

public data  class RemoteMessage(    \`\`val messageId: String?,    \`\`val priority: Int,    \`\`val ttl: Int,    \`\`val collapseKey: String?,    \`\`val data: Map\<String, String\>,    \`\`val rawData: ByteArray?,    \`\`val notification: Notification?)

  • messageId - 消息的唯一ID。它是每个消息的标识符；

  • priority - 返回优先级值**（当前不考虑）**。可能的选项包括：

    • 0 - UNKNOWN:

| - 1 - HIGH; | - 2 - NORMAL.

  • ttl - 返回Int类型的推送通知生命周期（以秒为单位）；
  • collapseKey - 通知组的标识符**（当前不考虑）**；
  • data - 一个字典，在其中可以传递额外的通知数据；
  • rawData - 以二进制数组形式的data字典；
  • notification - 通知对象。

对象的结构体Notification​

public data  class Notification(    \`\`val \#### String?,    \`\`val body: String?,    \`\`val channelId: String?,    \`\`val imageUrl: Uri?,    \`\`val color: String?,    \`\`val icon: String?,     \`\`val clickAction: String?  \`\`)

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

当点击通知时打开Activity​

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

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

事件日志记录​

关键词：RuStore，开发者，文档，RuStoreSDK，推送通知，连接，事件日志记录。如果您想要日志记录推送通知库的事件，请在调用 RuStorePushClient.init 时添加 logger 参数 - 这个参数对于初始化是可选的。

为此，您需要实现 Logger 接口：

interface Logger {    \`\`fun verbose(message: String, throwable: Throwable? =  null )    \`\`fun debug(message: String, throwable: Throwable? =  null )    \`\`fun info(message: String, throwable: Throwable? =  null )    \`\`fun warn(message: String, throwable: Throwable? =  null )    \`\`fun error(message: String, throwable: Throwable? =  null )    \`\`fun createLogger(tag: String): Logger}

果 Logger 没有被传递，将使用默认的实现，它使用 AndroidLog。

public class DefaultLogger(    \`\`private val tag: String? =  null ,) : Logger {    \`\`override fun verbose(message: String, throwable: Throwable?) {        \`\`Log.v(tag, message, throwable)    \`\`}    \`\`override fun debug(message: String, throwable: Throwable?) {        \`\`Log.d(tag, message, throwable)    \`\`}    \`\`override fun info(message: String, throwable: Throwable?) {        \`\`Log.i(tag, message, throwable)    \`\`}    \`\`override fun warn(message: String, throwable: Throwable?) {        \`\`Log.w(tag, message, throwable)    \`\`}    \`\`override fun error(message: String, throwable: Throwable?) {        \`\`Log.e(tag, message, throwable)    \`\`}    \`\`override fun createLogger(tag: String): Logger {        \`\`val newTag =  if ( this .tag !=  null ) {            \`\`\"\${this.tag}:\$tag\"        \`\`}  else {            \`\`tag        \`\`}        \`\`return DefaultLogger(newTag)    \`\`}}

错误处理​

可能的错误：

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

果您想使用 UI 接口来处理错误，请使用 resolveForPush 方法。

fun RuStoreException.resolveForPush(context: Context)

E2ESDK push-通知的集成测试​

进行测试需要遵守以下条件：

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

了开始测试 SDK，您需要启用测试模式：

RuStorePushClient.init(    \`\`application =  this ,    \`\`projectId =  \"some_project_id\" ,    \`\`testModeEnabled =  true)

测试模式下，将生成测试 push-令牌，并且只有使用以下方法发送的测试 push-通知才会被送达：

val testNotificationPayload = TestNotificationPayload(     \`\`title =  \"Test notification title\" ,     \`\`body =  \"Test notification message\" ,     \`\`imgUrl =  \"some_image_http_url\" ,     \`\`data = mapOf( \"some_key\" to  \"some_value\" ))RuStorePushClient.sendTestNotification(testNotificationPayload).addOnCompleteListener(object : OnCompleteListener\<Unit\> {    \`\`override fun onFailure(throwable: Throwable) {        \`\`// Process send test push error    \`\`}    \`\`override fun onSuccess(result: Unit) {        \`\`// Process send test push success    \`\`}})