notification — iOSの通知機能

　notification モジュールを使うことにより、iOS の通知センター画面に、予約した通知メッセージを表示することができるようになります。予約通知メッセージは、pythonista 上のスクリプトを実行していなくても、pythonista そのものが起動されていなくても表示されます。

　通知に URL アドレスを添付することも可能です。通知センター画面やロック画面で通知をタップし、通知をアクティベートすれば、この URL で指定した HP を表示できます。通知に複数のボタンを配置し、それぞれに個別の URL を立ち上げるよう設定することもできます。

　一般的には、予約通知は未来の特定の日時に表示されるよう設定しますが、家とか仕事先のような特定の場所に到着したり離れたりしたことをトリガーとする、場所に基づいた予約もできます。

　このモジュールの通知機能は、「ローカルな」通知専用です。不特定多数の人に通知する、いわゆるプッシュ通知はサポートされていません。

関　数

notification.schedule(message=None, delay=0, sound_name=None, action_url=None, title=None, subtitle=None, attachments=None, trigger=None, actions=None, identifier=None)

　後述するパラメーターで指定した通知機能の実行を予約します。

　戻り値は、後で通知をキャンセルする際などに使用できる通知のIDとなる文字列です。

パラメーター：

message: 通知で表示するテキスト本文です。
delay: 通知を届ける時刻を現在からの秒単位で設定します。
sound_name: 通知が届いた際に鳴らしたい、システムに組み込まれている効果音や音楽ファイルの名前を指定します。通知時に無音またはデフォルトの通知オン設定をしている場合には、None にしておくことができます。
action_url: 通知をタップした際に立ち上げるURLを指定します。
title: 通知を画面表示した時にメッセージの上に表示するタイトルを設定します。
subtitle: 通知のサブタイトルを設定します。
attachments: 通知に添付する画像などファイルのリストです。これらのファイルは即座にコピーされ、後からの変更は効かないことにご注意下さい。
trigger: 単純な経過秒数ではなく、後述する複雑なトリガーを記述したディクショナリーです。
actions: 通知に埋め込んだボタンがタップされた時の挙動を記述します。ボタンが複数ある場合には、それぞれのボタンは別々の URL を開いたり、スクリプトを実行したりするよう設定可能です。通知に付随したアクションは、スクリーン上端の通知バナーをドラッグして下にスライドするか、３Dタッチ(サポートしている機種のみ)か、通知をタップしホールドし続ける(３Ｄタッチ未対応の機種の場合)のいずれかで実行できます。個々のアクションの定義の仕方の詳細については、後述します。
identifier: 通知のIDとして使用するための付加的な文字列です。既に予約された通知と同じIDの通知を予約した場合には、古い通知は新しい通知に置換えられます。

日時や場所によるトリガー：

　単純な残り時間設定ではなく、より複雑な通知のトリガーが必要な場合、トリガーのパラメーターをディクショナリー型で関数に渡すことができます。このトリガーには、日付に基づくものと場所に基づくものの多くの選択肢があります。日付に基づく通知のキーとしては、'repeats', 'year', 'quarter', 'month', 'day', 'weekday', 'weekday_ordinal', 'week_of_month', 'week_of_year', 'hour', 'minute', 'second'がサポートされています。これらの全てのキーを指定する必要はなく、必要に応じてdate/time コンポーネントを使用すれば十分です。繰り返し通知は1分間に1回以上の短い周期での繰り返しはできません。

　場所に基づく通知のキーとしては、 'latitude', 'longitude', 'radius' (単位メートル、デフォルト値は100), 'entry', 'exit', 'repeats'がサポートされています。'entry'(指定地点への到着を知らせる)と'exit'(指定地点からの退出を知らせる)オプションは、True または False に設定します。デフォルトでは、両方とも True になっています。場所に基づく通知には、アプリに対して位置情報のアクセスの許可が必要です。（自動的に許可を求める表示がなされ、設定＞プライバシーで変更をすることができます）

通知に付随したアクションのカスタマイズ：

　アクションに関するパラメーターは、（例えば、ロック画面での3Dタッチにより）通知がアクティベイトされた際にボタンの形で表示される、アクションのリストとして設定することができます。アクションは以下のキーからなるディクショナリー型のリストで定義します：

'title' – ボタンのタイトル
'url' または 'action_url' – ボタンがタップされた際に表示される URL です。この URL が pythonista:// から始まる URL の場合には、スクリプトを実行します。次項目の 'foreground' が True に設定されていない場合は、スクリプトはバックグラウンドで実行されます。
'foreground' – 'action_url' を参照。
'destructive' – 誤って操作した場合に致命的な結果をもたらすボタンの見た目を変えます。（文字色を赤にします）
'text_input' – True に設定すると、通知画面の中にテキスト入力画面を表示させることができるようになります。入力したテキストデータを使用するには、'url' キーで指定するアクションの URL に {text_input} というプレースホルダー（テキスト入力値の挿入位置指定の記号）を配置して下さい。このアクションでスクリプトを実行するために pythonista:// から始まる URL を使用した場合には、入力したテキストデータを URL の引数パラメーターとして使用し、スクリプト中で sys.argv によりアクセスすることができます。（例）pythonista3://MyScript.py?action=run&args={text_input}
'text_input_button_title' – 'text_input' が True の時、ボタンのタイトルを「OK」に指定します。
'text_input_placeholder' – 'text_input' が True の時、プレースホルダーのテキストを指定します。

notification.cancel(identifier)

　以前に予約されていた通知をキャンセルします。

　キャンセルする通知を指定する引数 identifier には、get_scheduled() で呼び出した文字列か、 schedule() 関数の戻り値の文字列を使用します。

notification.cancel_all()

　以前に予約していた通知を全てキャンセルします。

notification.get_scheduled()

　予約した通知のIDのリストを返します。

　リストの各項目は、cancel() 関数に使用できる UUID 文字列です。

notification.remove_delivered(identifier)

　通知センターに表示され終わった、引数 identifier で指定した通知を削除します。注：ユーザーが通知をアクティベイトすると、この処理は自動的に行われます。

notification.remove_all_delivered()

　通知センターに表示され終わった、全ての通知を削除します。注：このアプリの通知のみに適用されます。

notification — iOSの通知機能