概要
KlugPush は、macOS 上の AIR アプリにリモートプッシュ通知をもたらします。アプリを Apple のプッシュ通知サービスに登録し、サーバー用のデバイストークンを提供し、受信した通知を ActionScript に配信します。
macOS では、一度通知を拒否したユーザーに再度確認が表示されることはありません。そのため KlugPush は、いつでも現在の権限状態を報告し、システム設定の通知ページを開くことで、ユーザーが後から通知をオンにできるようにします。
KlugPush は、実証の場である当社のアプリの Mac 版で毎日使われています。
機能
- 自己完結型:ANE 1つで完結し、コアライブラリや依存 ANE の追加は不要
- 権限を要求し、リモート通知に登録
- 登録が完了すると、サーバー用のデバイストークンを取得
- 受信した通知を JSON として ActionScript に配信
- リアルタイムの権限状態:未決定、拒否、許可
- システム設定の「通知」を直接開く
- Apple のプッシュサービス経由で直接送信。追加のプッシュプロバイダーは不要
対応プラットフォーム
他のプラットフォームでは isSupported が false を返すため、同じコードをクロスプラットフォームのアプリにそのまま残せます。
はじめに
アプリケーション記述子に拡張機能を追加します:
<extensions>
<extensionID>com.klug.push.Push</extensionID>
</extensions>
アプリは、プッシュ通知の entitlement と、Push Notifications capability を含むプロビジョニングプロファイルで署名されている必要があります。
コード例
当社アプリの Mac 版で稼働している API から取り出した、4つの完全なフローです。すべての呼び出しは即座に返り、結果はコールバックと StatusEvent を通じて届きます。完全なドキュメント →
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 ); }
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 ); }
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 ); });
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) | 権限を要求し、リモート通知に登録します。3つのコールバックはすべて省略可能で、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(provisional)と 4(ephemeral)も報告する場合があります。 |
| TOKEN, ERROR, NOTIFICATION | リスナー向けの StatusEvent の level:level が種類を示し、code が値を運びます。 |
イベント
| level token | code = デバイストークン(16進数文字列) |
| level error | code = 登録時のエラーメッセージ |
| level notification | code = JSON 形式の通知ペイロード |
KlugPush を購入
AIR アプリケーション1つ分の年間ライセンスで、12か月間のすべてのアップデートが含まれます。お支払い後、拡張機能、ActionScript ライブラリ、ドキュメントをメールでお送りします(通常は1営業日以内)。ライセンスと条件
動作要件
| AIR SDK | 51.x(HARMAN) |
| macOS | macOS 11 以降 |
| 署名 | プッシュ通知の entitlement と、対応するプロビジョニングプロファイル |
| サーバー | Apple のプッシュサービス経由で通知を送信 |