跳到主要内容

1.0.0

注意

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

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

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

在项目中集成​

  1. 从RuStore的官方gitflic仓库复制'Plugins'文件夹的内容到您项目中的*'Plugins'*文件夹。重启Unreal Engine，在插件列表中（Edit → Plugins → Project → Mobile），选择'RuStoreBilling'和'RuStoreCore'插件。
  2. 在文件 "YourProject.Build.cs" 中，在 PublicDependencyModuleNames 列表中连接模块 "RuStoreCore" 和 "RuStorePush"。
  3. 在项目设置中（Edit → Project Settings → Android），设置 Minimum SDK Version 为不低于24，Target SDK Version 为不低于31。

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

"RuStorePush" 插件将声明 RuStoreUnityMessagingService 服务。

AndroidManifest.xml

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

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

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

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

AndroidManifest.xml

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

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

初始化​

在调用库的方法之前，必须先调用其初始化：

初始化

FURuStorePushClientConfig config;config.allowNativeErrorHandling =  true ;config.messagingServiceListener = pushMessagingServiceListener;config.logListener = pushLogListener;FURuStorePushClient::Instance()-\>Init(сonfig);

有与客户端的操作也可以通过Blueprints进行。初始化的例子：

  • allowallowNativeErrorHandling -- 允许原生 SDK 中的错误处理。
  • messagingServiceListener-- 实现 IRuStoreMessagingServiceListenerInterface 接口的类对象。
  • logListener-- 实现 IRuStoreLogListenerInterface 接口的类对象LogListenerInterface
  • projectId-- 您在 RuStore 控制台的项目标识符

RuStoreMessagingServiceListener 和 URuStoreLogListener 类分别实现了 IRuStoreMessagingServiceListenerInterface 和 IRuStoreLogListenerInterface 接口。它们的应用允许直接从 blueprint 中处理接口事件。

URuStoreMessagingServiceListener 和 URuStoreLogListener 的初始化与 URuStorePushClient 一起进行：

IRuStore接口MessagingServiceListenerInterface

class RUSTOREPUSH_API IRuStoreMessagingServiceListenerInterface{    \`\`GENERATED_BODY()    public :    \`\`UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category =  \"RuStore Messaging Service Listener Interface\" )    \`\`void NewTokenResponse(int64 requestId, FString& token);    \`\`UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category =  \"RuStore Messaging Service Listener Interface\" )    \`\`void MessageReceivedResponse(int64 requestId, FURuStoreRemoteMessage& message);    \`\`UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category =  \"RuStore Messaging Service Listener Interface\" )    \`\`void DeletedMessagesResponse(int64 requestId);    \`\`UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category =  \"RuStore Messaging Service Listener Interface\" )    \`\`void ErrorResponse(int64 requestId, TArray\<FURuStoreError\>& errors);};

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

  • MessageReceivedResponse-- 在接收到新的推送通知时将被调用。
  • DeletedMessagesResponse-- 如果一个或多个推送通知没有被送达到设备，将会调用此方法。这可能是因为通知的生命周期在送达设备前已经结束。在调用此方法时，建议与您的服务器同步，以免错过数据。
  • ErrorResponse-- 如果在初始化过程中发生错误，将会调用此方法。

能的错误：

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

知结构体。

完整通知的结构体

USTRUCT(BlueprintType)struct RUSTOREPUSH_API FURuStoreRemoteMessage{    \`\`GENERATED_USTRUCT_BODY()public :    \`\`UPROPERTY()    \`\`FString collapseKey;        \`\`UPROPERTY()    \`\`TMap\<FString, FString\> data;        \`\`UPROPERTY()    \`\`FString messageId;        \`\`UPROPERTY()    \`\`FURuStoreNotification notification;        \`\`UPROPERTY()    \`\`int priority;        \`\`char \* rawData;        \`\`UPROPERTY()    \`\`int ttl;};

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

  • priority- （当前不考虑）返回优先级值。目前有以下选项：

    • 0 - UNKNOWN.

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

ttlInt类型的推送通知生命周期（以秒为单位）；

  • collapseKey- （当前不考虑）通知组的标识符。
  • data- 一个字典，在其中可以传递额外的通知数据。
  • rawData- data 字典以字节数组形式。
  • notification- 通知对象。

对象的结构体Notification

USTRUCT(Blueprintable)struct RUSTOREPUSH_API FURuStoreNotification{    \`\`GENERATED_USTRUCT_BODY()public :    \`\`FURuStoreNotification()    \`\`{        \`\`title =  \"0\" ;        \`\`body =  \"0\" ;        \`\`channelId =  \"0\" ;        \`\`imageUrl =  \"0\" ;        \`\`color =  \"0\" ;        \`\`icon =  \"0\" ;        \`\`clickAction =  \"0\" ;    \`\`}    \`\`UPROPERTY()    \`\`FString title;    \`\`UPROPERTY()    \`\`FString body;    \`\`UPROPERTY()    \`\`FString channelId;    \`\`UPROPERTY()    \`\`FString imageUrl;    \`\`UPROPERTY()    \`\`FString color;    \`\`UPROPERTY()    \`\`FString icon;    \`\`UPROPERTY()    \`\`FString 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- 点击通知时，用于打开activity的intent action。

IRuStore接口LogListenerInterface

class RUSTOREPUSH_API IRuStoreLogListenerInterface{    \`\`GENERATED_BODY()public :    \`\`UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category =  \"RuStore Log Listener Interface\" )    \`\`void LogResponse(int64 requestId, FString& logString);    \`\`UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category =  \"RuStore Log Listener Interface\" )    \`\`void LogWarningResponse(int64 requestId, FString& logString);    \`\`UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category =  \"RuStore Log Listener Interface\" )    \`\`void LogErrorResponse(int64 requestId, FString& logString);    \`\`UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category =  \"RuStore Log Listener Interface\" )    \`\`void LogExceptionResponse(int64 requestId, FURuStoreError& error);};

LogResponse- 当普通日志记录出现在事件日志中时将被调用。

  • LogWarningResponse- 当警告记录出现在事件日志中时将被调用。
  • LogErrorResponse- 当错误日志记录出现在事件日志中时将被调用。
  • LogExceptionResponse- 当异常日志记录出现在事件日志中时将被调用。

错误结构体

USTRUCT(BlueprintType)struct RUSTORECORE_API FURuStoreError{    \`\`GENERATED_USTRUCT_BODY()    \`\`FURuStoreError()    \`\`{        \`\`name =  \"\" ;        \`\`description =  \"\" ;    \`\`}    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString name;    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString description;};

name- 错误名称。

  • description- 错误描述。

URuStorePushClient、URuStoreMessagingServiceListener、URuStoreLogListener 调用 Init() 将对象绑定到场景根部。如果不打算进一步使用这些对象，为了释放内存，需要执行 Dispose() 方法。调用 Dispose() 方法将从根部解绑对象，并安全地完成所有已发送的请求。

反初始化

URuStorePushClient::Instance()-\>Dispose();URuStoreMessagingServiceListener::Instance()-\>Dispose();URuStoreLogListener::Instance()-\>Dispose();

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

要检查支付的可用性，需要使用 CheckPushAvailability() 方法。在调用时，将检查以下条件：

  1. 用户的设备上必须安装 RuStore。
  2. RuStore 必须支持推送通知功能。
  3. 用户必须在 RuStore 中获得授权。
  4. 用户和应用程序不应在RuStore中被封锁。
  5. 应用程序的签名指纹必须与 RuStore 控制台中指定的指纹匹配。

次调用 CheckPushAvailability() 都会返回一个在应用程序单次启动期间唯一的 requestId。每个事件都会返回触发该事件的请求的 requestId。

RuStore实现示例PushClient.CheckPushAvailability

long responseId = URuStorePushClient::Instance()-\>CheckPushAvailability(    \`\`\[\]( long responseId, TSharedPtr\<FUFeatureAvailabilityResult, ESPMode::ThreadSafe\> response) {        \`\`// Process response    \`\`},    \`\`\[\]( long responseId, TSharedPtr\<FURuStoreError, ESPMode::ThreadSafe\> error) {        \`\`// Process error    \`\`});

blueprint实现：

Success回调返回FURuStoreFeatureAvailabilityResult结构体，在Response参数中：

响应CheckPushAvailability

USTRUCT(BlueprintType)struct RUSTORECORE_API FURuStoreFeatureAvailabilityResult{    \`\`GENERATED_USTRUCT_BODY()    \`\`FURuStoreFeatureAvailabilityResult()    \`\`{        \`\`isAvailable =  false ;    \`\`}    \`\`UPROPERTY(BlueprintReadWrite)    \`\`bool isAvailable;        \`\`UPROPERTY(BlueprintReadWrite)    \`\`FURuStoreError cause;};

sAvailable- 表示是否满足执行支付的条件。

cause- 错误信息。

Failure回调返回FURuStoreError结构体，包含错误信息，在Error参数中。所有可能的FURuStoreException错误在"错误处理"部分有描述。

错误结构体

USTRUCT(BlueprintType)struct RUSTORECORE_API FURuStoreError{    \`\`GENERATED_USTRUCT_BODY()    \`\`FURuStoreError()    \`\`{        \`\`name =  \"\" ;        \`\`description =  \"\" ;    \`\`}    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString name;    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString description;};

name- 错误名称。

  • description- 错误描述。

使用推送令牌的方法​

获取用户的推送令牌​

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

RuStore实现示例PushClient.GetToken

long responseId = URuStorePushClient::Instance()-\>GetToken(    \`\`\[\]( long responseId, FString response) {        \`\`// Process response    \`\`},    \`\`\[\]( long responseId, TSharedPtr\<FURuStoreError, ESPMode::ThreadSafe\> error) {        \`\`// Process error    \`\`});

blueprint实现：

Success 回调以字符串形式在 Response 参数中返回令牌：

响应GetProducts

FString response

response- 当前的 push-令牌。

ailure回调返回FURuStoreError结构体，包含错误信息，在Error参数中。所有可能的FURuStoreException错误在错误处理部分有描述。

错误结构体

USTRUCT(BlueprintType)struct RUSTORECORE_API FURuStoreError{    \`\`GENERATED_USTRUCT_BODY()    \`\`FURuStoreError()    \`\`{        \`\`name =  \"\" ;        \`\`description =  \"\" ;    \`\`}    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString name;    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString description;};

name- 错误名称。

  • description- 错误描述。

删除用户的推送令牌​

在库初始化之后，您可以使用 RuStorePushClientt::Instance()->DeleteToken() 方法来删除当前用户的push令牌。

RuStore实现示例PushClient.DeleteToken

long responseId = URuStorePushClient::Instance()-\>DeleteToken(    \`\`\[\]( long responseId) {        \`\`// Process success    \`\`},    \`\`\[\]( long responseId, TSharedPtr\<FURuStoreError, ESPMode::ThreadSafe\> error) {        \`\`// Process error    \`\`});

blueprint实现：

Failure回调返回FURuStoreError结构体，包含错误信息，在Error参数中。所有可能的FURuStoreException错误在错误处理部分有描述。

错误结构体

USTRUCT(BlueprintType)struct RUSTORECORE_API FURuStoreError{    \`\`GENERATED_USTRUCT_BODY()    \`\`FURuStoreError()    \`\`{        \`\`name =  \"\" ;        \`\`description =  \"\" ;    \`\`}    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString name;    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString description;};

name- 错误名称。

  • description- 错误描述。

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

订阅主题的推送通知​

在初始化库之后，您可以使用 URuStorePushClientt::Instance()->SubscribeToTopic() 方法来订阅主题。

RuStore实现示例PushClient.GetToken

long requestId = URuStorePushClient::Instance()-\>SubscribeToTopic(    \`\`topicName,    \`\`\[\]( long requestId) {      \`\`// Process error    \`\`},    \`\`\[\]( long requestId, TSharedPtr\<FURuStoreError, ESPMode::ThreadSafe\> error) {      \`\`// Process error    \`\`});

blueprint实现：

Failure回调返回FURuStoreError结构体，包含错误信息，在Error参数中。所有可能的FURuStoreException错误在错误处理部分有描述。

错误结构体

USTRUCT(BlueprintType)struct RUSTORECORE_API FURuStoreError{    \`\`GENERATED_USTRUCT_BODY()    \`\`FURuStoreError()    \`\`{        \`\`name =  \"\" ;        \`\`description =  \"\" ;    \`\`}    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString name;    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString description;};

name- 错误名称。

  • description- 错误描述。

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

在初始化库之后，您可以使用 RuStorePushClientt::Instance()->UnsubscribeToTopic() 方法来取消订阅主题。

RuStore实现示例PushClient.DeleteToken

long responseId = URuStorePushClient::Instance()-\>UnsubscribeFromTopic(    \`\`\[\]( long responseId) {        \`\`// Process success    \`\`},    \`\`\[\]( long responseId, TSharedPtr\<FURuStoreError, ESPMode::ThreadSafe\> error) {        \`\`// Process error    \`\`});

blueprint实现：

Failure回调返回FURuStoreError结构体，包含错误信息，在Error参数中。所有可能的FURuStoreException错误在错误处理部分有描述。

错误结构体

USTRUCT(BlueprintType)struct RUSTORECORE_API FURuStoreError{    \`\`GENERATED_USTRUCT_BODY()    \`\`FURuStoreError()    \`\`{        \`\`name =  \"\" ;        \`\`description =  \"\" ;    \`\`}    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString name;    \`\`UPROPERTY(BlueprintReadOnly)    \`\`FString description;};

name- 错误名称。

  • description- 错误描述。

创建发送通知的渠道​

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

1. 如果 push 通知中包含 channelId 字段，那么 SDK 将会把通知发送到这个渠道。同时，您的应用程序负责提前创建这个渠道。

2. 如果 push 通知中没有 channelId 字段，但您的应用程序在 AndroidManifest.xml 中指定了带有渠道的参数，则将使用 AndroidManifest.xml 中的渠道。您的应用程序负责创建这个渠道。

3. 如果 push 通知中没有 channelId 字段，并且在您的应用程序的 AndroidManifest.xml 中没有设置默认渠道，则 SDK 将自行创建一个渠道并发送通知到该渠道。以后，所有未指定渠道的通知都将发送到这个渠道。

点击通知时打开 Activity​

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

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

错误处理​

可能的错误：

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

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

resolveForPush

fun RuStoreException.resolveForPush(context: Context)

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

禁止原生的错误处理

URuStorePushClient::Instance()-\>SetAllowNativeErrorHandling( false );