概览
KlugPush 为 macOS 上的 AIR 应用带来远程推送通知。它将应用注册到 Apple 推送通知服务,为您的服务器提供设备令牌,并将收到的通知传递给 ActionScript。
在 macOS 上,曾拒绝通知的用户不会被再次询问。因此 KlugPush 可随时报告当前权限状态,并打开“系统设置”中的“通知”页面,以便用户之后开启通知。
KlugPush 每天都在我们的应用的 Mac 版本中使用,这就是我们的概念验证。
特性
- 自成一体:一个 ANE,无需添加核心库或依赖 ANE
- 请求权限并注册远程通知
- 注册完成后立即获得供您的服务器使用的设备令牌
- 收到的通知以 JSON 形式传递给 ActionScript
- 实时权限状态:尚未决定、已拒绝或已允许
- 直接在“系统设置”中打开“通知”
- 直接通过 Apple 推送服务发送,无需额外的推送服务商
支持的平台
macOS Apple 芯片 · Intel
在其他平台上,isSupported 返回 false,因此同一份代码可以保留在跨平台应用中。
入门
将扩展添加到您的应用描述文件中:
<extensions>
<extensionID>com.klug.push.Push</extensionID>
</extensions>
应用必须使用推送通知 entitlement 签名,并配有包含推送通知功能的描述文件。
代码示例
四个完整流程,取自在我们应用 Mac 版本中运行的 API。每次调用都会立即返回;结果通过您的回调函数以及 StatusEvent 到达。完整文档 →
1 · 注册并将令牌发送到您的服务器
import com.klug.push.Push; var push:Push = Push.getInstance(); if ( push.isSupported ) // macOS; false on every other platform { // asks for permission on the first start, then registers with Apple's push service. // The token also arrives when the user declines: permission only affects the display. push.register( onToken, onPushError, onNotification ); } function onToken( token:String ):void { if ( token != loadSavedToken() ) // your app functions sendTokenToServer( token ); // e.g. a POST to https://your.server/push } function onPushError( message:String ):void { // typical cause: the app is not signed with the push entitlement and a matching profile trace( "push registration failed: " + message ); }
2 · 应用运行时的通知
function onNotification( json:String ):void { // the full payload as your server sent it: the "aps" part plus your own keys var payload:Object = JSON.parse( json ); if ( payload.hasOwnProperty( "stationId" ) ) // a key your server adds openLiveView( payload.stationId ); // your app function } // later, e.g. after the user signed in to another account function onLogin():void { if ( push.token != null ) // the last token; null until registration finished sendTokenToServer( push.token ); }
3 · 权限状态与系统设置
import flash.events.Event; import flash.desktop.NativeApplication; // the live status arrives asynchronously; the callback stays set and // also receives the answer when register() shows the prompt push.refreshStatus( updateNotificationSwitch ); function updateNotificationSwitch( status:int ):void { if ( status == Push.STATUS_AUTHORIZED ) showSwitch( "on" ); // your app function else if ( status == Push.STATUS_DENIED ) showSwitch( "off" ); else if ( status == Push.STATUS_NOT_DETERMINED ) showSwitch( "not asked" ); } // macOS never asks a second time: the way back is System Settings function onSwitchTapped():void { if ( push.authStatus == Push.STATUS_DENIED ) push.openSettings(); } // the user may have changed it there: read it again when the app comes back NativeApplication.nativeApplication.addEventListener( Event.ACTIVATE, function( e:Event ):void { push.refreshStatus( updateNotificationSwitch ); });
4 · 使用事件而非回调进行监听
import flash.events.StatusEvent; push.addEventListener( StatusEvent.STATUS, function( e:StatusEvent ):void { // here the LEVEL names the kind and the CODE carries the value if ( e.level == Push.TOKEN ) sendTokenToServer( e.code ); else if ( e.level == Push.ERROR ) trace( "push error: " + e.code ); else if ( e.level == Push.NOTIFICATION ) onNotification( e.code ); // JSON }); push.register(); // all three callbacks are optional
API 概览
| Push.getInstance() | 返回唯一实例。 |
| isSupported | 在 macOS 上为 True,其他平台为 false。 |
| register(onToken, onError, onNotification) | 请求权限并注册远程通知。三个回调均为可选;onNotification 在应用运行期间触发。在不支持推送的平台上返回 false。 |
| token | 最近一次的设备令牌;注册完成前为 null。 |
| authStatus | 最近一次已知的权限状态;在 register() 或 refreshStatus() 运行之前为 -1。 |
| refreshStatus(onStatus) | 读取当前权限状态;结果到达时会调用 onStatus(status:int),并在 register() 的提示得到答复后再次调用。 |
| openSettings() | 在“系统设置”中打开“通知”。 |
| STATUS_NOT_DETERMINED, STATUS_DENIED, STATUS_AUTHORIZED | 权限状态值 0、1 和 2。macOS 还可能报告 3(临时授权)和 4(短暂授权)。 |
| TOKEN, ERROR, NOTIFICATION | 供监听器使用的 StatusEvent level:level 名称表示类型,code 携带值。 |
事件
| level token | code = 设备令牌,十六进制字符串 |
| level error | code = 注册时的错误消息 |
| level notification | code = JSON 格式的通知负载 |
购买 KlugPush
一个 AIR 应用的年度许可,含 12 个月内的所有更新。付款后,您将通过电子邮件收到扩展、ActionScript 库和文档,通常在一个工作日内。许可与条款
税费在结账时由 Link (Stripe) 计算。您需要在结账时输入 AIR 应用的应用 ID。
要求
| AIR SDK | 51.x (HARMAN) |
| macOS | macOS 11 或更高版本 |
| 签名 | 推送通知 entitlement 及匹配的描述文件 |
| 服务器 | 通过 Apple 推送服务发送通知 |