本文はGroovyTemplate形式で記述可能です。 次の例は、userでUserエンティティ、pointでIntegerのインスタンスがバインドされている場合を想定したものです。
通知機能を利用することにより、eメール、SMS、push通知などの手段でユーザにメッセージを送信することが可能です。
1. メール送信
CommandやListenerなどからメールを送信する機能です。 MailManagerクラスを介してメールを送信します。 送信する文面はMailTemplateとして登録・管理することが可能です。
1.1. MailTemplateの作成
MailTemplateアイコンを右クリックして「メールテンプレートを作成する」を選択してください。
1.2. 設定
テンプレートの編集
件名、文字コード(テキストメッセージ文字コード、HTMLメッセージ文字コード)、テキストメッセージ(Plainメッセージ)、HTMLメッセージを設定します。
項目 | 設定内容 |
---|---|
表示名 |
表示名を設定します。 |
説明 |
説明を設定します。 |
文字コード |
テキストメッセージの文字コードを設定します。 未指定の場合、メールの基本設定のデフォルトキャラクタセット(mail.charset)が設定されます。 |
HTML文字コード |
HTMLメッセージの文字コードを設定します。 未指定の場合、文字コードと同じ値が設定されます。 |
Fromアドレス |
標準の送信元アドレスを設定します。 詳細は送信元を参照してください。 |
ReplyToアドレス |
標準の返信先アドレスを設定します。 詳細は送信元を参照してください。 |
ReturnPathアドレス |
標準のエラーメール返信先アドレスを設定します。 詳細は送信元を参照してください。 |
件名 |
件名を設定します。 GroovyTemplate形式で記述します。 |
テキストメッセージ |
テキスト形式のメッセージを設定します。 テキストメッセージとHTMLメッセージが両方設定された場合は、「multipart/alternative」形式でメールを送信します。 GroovyTemplate形式で記述します。 |
HTMLメッセージ |
HTML形式のメッセージを設定します。 テキストメッセージとHTMLメッセージが両方設定された場合は、「multipart/alternative」形式でメールを送信します。 GroovyTemplate形式で記述します。 |
件名、メッセージ内部でバインド変数を利用する場合は、メール生成処理に引数としてバインド変数を渡す必要があります。
MailManager#createMail(String tmplDefName, Map<String, Object> bindings)
複数の言語に対応したメールテンプレートを作成し、利用することができます。 Multilingual MailTemplateの「Add」ボタンをクリックする事で多言語用メールテンプレート作成ダイアログが表示されます。
設定項目は以下のとおりです。 その他の項目はメールテンプレートの編集と同様です。 送信時に選択される言語については送信時の言語を参照してください。
項目 | 設定内容 |
---|---|
言語設定情報バインド名 |
この項目の設定値をバインド変数のキー、値に言語名かユーザEntity(内部で言語プロパティを参照)をセットすることで、Mail作成時にユーザに合わせた言語でメールを作成することができます。 例として、英語のメールテンプレートを送信する場合、言語設定情報バインド名に「sampleLangKey」と設定。 メール生成処理にて下記をバインド変数として渡します。
|
Language |
言語を設定します。 |
送信時の言語は以下の順で決まります。
-
本テンプレートで指定されている言語設定情報バインド名で取得できる値
取得した値がStringであれば、その値を言語として利用
取得した値がユーザEntityであれば、言語プロパティを利用 -
テナントの言語
-
システムのデフォルト言語
テナント
テナント情報に設定するメール送信関連の設定についてはテナント管理を参照してください。
MailService
メール送信時の基本設定はservice-configのMailServiceを参照してください。
1.3. 利用方法
メール送信処理
MailManagerを利用したメール送信は以下のように実装します。
import org.iplass.mtp.mail.Mail;
import org.iplass.mtp.mail.MailManager;
//メールの送信はMailManagerを利用
private MailManager mailManager = ManagerLocator.getInstance().get(MailManager.class);
private void sendMail() {
try {
//MailTemplateに渡すバインド変数設定(例ではtenantとuserを設定)
Map<String, Object> bindings = new HashMap<String, Object>();
bindings.put("tenant", tenant);
bindings.put("user", user);
//MailManager#createMail(メールテンプレート名, バインド変数) を呼び出し、Mailを生成
Mail mail = mailManager.createMail("sampleMailTemplateName", bindings);(1)
//送信先の設定(例ではTOの設定)
mail.addRecipientTo((String)user.getValue(User.MAIL), (String)user.getValue(User.LAST_NAME) + "様");(2)
//MailManager#sendMail(Mail)を呼び出し、メールを送信
mailManager.sendMail(mail);(3)
} catch (RuntimeException e) {
}
}
1 | MailTemplateを利用して送信用メッセージを作成。 バインド変数とGroovyTemplate書式を利用して動的にメッセージを生成。 |
2 | 宛先を設定。 送信元の設定も可能(省略時はテナント情報から設定) |
3 | メールを送信。 メールサーバ情報や認証情報はserver-config.xmlで設定。 |
宛先
作成したMail(org.iplass.mtp.mail.Mail)に対して宛先を設定します。 宛先(TO、CC、BCC)に対してアドレスと個人名(省略可)を指定します。
項目 | メソッド |
---|---|
TO送信アドレス |
addRecipientTo(String address) |
addRecipientTo(String address, String personal) |
|
CC送信アドレス |
addRecipientCc(String address) |
addRecipientCc(String address, String personal) |
|
BCC送信アドレス |
addRecipientBcc(String address) |
addRecipientBcc(String address, String personal) |
送信元
送信時の送信者情報を設定します。 設定内容は以下の優先度で決まります。
-
Mail
-
MailTemplate
-
Tenant
作成したMail(org.iplass.mtp.mail.Mail)に対して、以下の項目で設定することができます。
項目 | メソッド |
---|---|
送信元アドレス |
setFrom(String address) |
setFrom(String address, String personal) |
|
setFromAddress(javax.mail.internet.InternetAddress address) |
|
返信先アドレス |
setReplyTo(String address) |
setReplyToAddress(javax.mail.internet.InternetAddress address) |
|
ReturnPathアドレス |
setReturnPath(String returnPath) |
Mailに設定されていない場合は、MailTemplateに設定されている情報が設定されます。
MailにもMailTemplateにも設定されていない場合は、テナントに設定されている情報が設定されます。
ただし、ReturnPathアドレスについては、Tenantでは設定できません。 MailServiceの「mail.smtp.from」が設定されている場合はその値が利用されます。
添付ファイル
作成したMail(org.iplass.mtp.mail.Mail)に対して、以下のメソッドを利用することで添付ファイル付のメール送信が可能です。
項目 | メソッド |
---|---|
DataHandler形式 |
addAttachment(javax.activation.DataHandler dataHandler) |
BinaryReference形式 |
addAttachment(org.iplass.mtp.entity.BinaryReference bin) |
2. SMS送信
SMS(ショートメッセージサービス)を利用して、携帯電話・スマートフォン宛にテキストメッセージを送信します。 送信する文面はSMSTemplateとして登録・管理することが可能です。
iPLAssではSMS送信をTwilioを利用して実装しています。 Twilio連携も併せて確認してください。
2.1. SMSTemplateの作成
SMSTemplateアイコンを右クリックして「SMSテンプレートを作成する」を選択してください。
2.2. 設定
テンプレートの編集
テキストメッセージを設定します。
項目 | 設定内容 |
---|---|
表示名 |
表示名を設定します。 |
説明 |
説明を設定します。 |
言語設定情報バインド名 |
この項目の設定値をバインド変数のキー、値に言語名かユーザEntity(内部で言語プロパティを参照)をセットすることで、メッセージ作成時にユーザに合わせた言語でメッセージを作成することができます。 例として、英語のSMSテンプレートを送信する場合、言語設定情報バインド名に「sampleLangKey」と設定。 メッセージ生成処理にて下記をバインド変数として渡します。
|
テキストメッセージ |
テキスト形式のメッセージを設定します。 GroovyTemplate形式で記述します。 |
複数の言語に対応したSMSテンプレートを作成し、利用することができます。 Multilingual SmsTemplateの「Add」ボタンをクリックする事で多言語用SMSテンプレート作成ダイアログが表示されます。
設定項目は以下のとおりです。
項目 | 設定内容 |
---|---|
Language |
言語を設定します。 |
テキストメッセージ |
テキスト形式のメッセージを設定します。 GroovyTemplate形式で記述します。 |
SmsService
SMS送信時の基本設定はservice-configのSmsServiceを参照してください。
2.3. 利用方法
メッセージ送信処理
SmsMailManagerを利用したメッセージ送信は以下のように実装します。
import org.iplass.mtp.sms.SmsMail;
import org.iplass.mtp.sms.SmsMailManager;
//メッセージの送信はSmsMailManagerを利用
private SmsMailManager manager = ManagerLocator.getInstance().get(SmsMailManager.class);
private void sendMessage() {
try {
//SmsMailTemplateに渡すバインド変数設定(例ではtenantとuserを設定)
Map<String, Object> bindings = new HashMap<String, Object>();
bindings.put("tenant", tenant);
bindings.put("user", user);
//SmsMailManager#createMail(SMSテンプレート名, バインド変数) を呼び出し、SmsMailを生成
SmsMail message = manager.createMail("sampleSmsMailTemplateName", bindings);(1)
//送信元の設定
mail.setFrom("+12345678901");
//送信先の設定
mail.setTo("+819012345678");(2)
//SmsMailManager#sendMail(SmsMail)を呼び出し、メッセージを送信
manager.sendMail(message);(3)
} catch (RuntimeException e) {
}
}
1 | SmsMailTemplateを利用して送信用メッセージを作成。 バインド変数とGroovyTemplate書式を利用して動的にメッセージを生成。 |
2 | 送信先の電話番号を設定。国番号を付与した電話番号を指定します。 |
3 | メッセージを送信。認証情報等はserver-config.xmlで設定。 |
3. プッシュ通知
モバイル端末へのプッシュ通知を行うための機能です。 繰り返し利用する通知メッセージ、タイトルなどをPushNotificationTemplateとして登録・管理することも可能です。
iPLAssではプッシュ通知サービスとしてFirebase Cloud Messaging(FCM) を利用したモジュールを標準提供します。サービスインタフェース(PushNotificationService)を独自実装することにより、Firebase Cloud Messaging以外のプッシュ通知サービスを利用することも可能です。
3.1. プッシュ通知の方法
プッシュ通知する場合はPushNotificationManagerのapiを利用します。 また、実際にプッシュ通知を行う場合は、service-config.xmlにて外部プッシュ通知サービスの設定を正しく行う必要があります。
以下にapi利用のサンプルコードを示します。
import org.iplass.mtp.ManagerLocator;
import org.iplass.mtp.pushnotification.*;
:
:
//プッシュ通知の際には、PushNotificationManagerを利用
PushNotificationManager pnm =
ManagerLocator.getInstance().get(PushNotificationManager.class);
PushNotification pn = new PushNotification();
//通知先(registrationId)を指定
pn.addTo("ds...");(1)
//メッセージをNotificationPayloadにて指定
pn.setNotification(
new NotificationPayload(
"Caution!",
"Check your login history!",
"ic_stat_notification"));
//送信オプションを指定
pn.getOptions().put("priority", "high");(2)
PushNotificationResult res = pnm.push(pn);
//PushNotificationResult#isSuccess()で通知成功したかどうか判断可能
System.out.println(res.isSuccess());
//PushNotificationResult#getDetails()で通知結果の詳細取得可能
System.out.println(res.getDetails());
1 | 通知先の指定はredistrationId、もしくはtopic、もしくはtopicの条件式(condition)を指定可能です。redistrationIdを指定する場合、addTo()メソッドを複数回呼び出すことにより、複数指定が可能です。 |
2 | その他プッシュ通知に設定可能なオプションについては、FCMの ドキュメントを参照ください。 |
apiの詳細はPushNotificationManagerのjavadocを参照ください。
3.2. PushNotificationTemplateの利用
繰り返し利用する通知メッセージ、タイトルなどをPushNotificationTemplateとして登録・管理し、そのテンプレートを利用して通知メッセージを作成することが可能です。 PushNotificationTemplateはadminConsoleにて登録・管理します。
PushNotificationTemplateの作成
adminConsoleからNotificationカテゴリにあるPushNotificationTemplateの定義を作成します(PushNotificationTemplate → 右クリック → 作成)。
設定項目の説明
次の項目を設定可能です。
Default PushNotificationTemplateタブでは、言語設定によらない共通のメッセージを設定します。
設定項目 | 設定内容 |
---|---|
タイトル |
プッシュ通知のタイトルを指定します。この値は iOS のスマートフォンやタブレットには表示されません。 |
アイコン |
通知アイコンを設定します。Androidのみ有効です。 |
本文 |
プッシュ通知のメッセージ本文を指定します。本文はGroovyTemplate形式で設定可能です。テンプレート呼び出し時にバインドされたオブジェクトを利用し、値の埋め込みが可能です。 次項に本文の記述例を示します。 |
ConfigScript |
プッシュ通知のオプション、DataPayloadなどをGroovyScript形式で設定可能です。pnという変数名でPushNotificationのインスタンスがバインドされています。 次項にConfigScriptの記述例を示します。 |
${user.name}さん、
あなたのポイントは${point}ポイントです。
ConfigScriptはGroovyScript形式で記述可能です。 pnという変数名でPushNotificationのインスタンスがバインドされています。
//priorityをhighに設定
pn.options.priority = 'high'
//メッセージに追加のパラメータを設定
pn.notification.color = '#FF9900'
//DataPayloadの設定
pn.data.score = '3x1'
Multilingual PushNotificationTemplateタブでは、言語毎のメッセージを定義可能です。
設定項目 | 設定内容 |
---|---|
言語設定情報バインド名 |
ここに設定した値をキーとして、PushNotificationManagerに渡すバインド変数として言語キー(enやjaなど)、もしくはUserエンティティをセットすることで、受信側の設定言語にあわせた言語でのプッシュ通知が可能です。 |
Language |
addボタンにより、言語毎にタイトル、本文を定義します。 |
PushNotificationTemplateを利用したプッシュ通知の方法
PushNotificationTemplateを利用してプッシュ通知する場合もPushNotificationManagerのapiを利用して行います。 また、実際にプッシュ通知を行う場合は、service-config.xmlにて外部プッシュ通知サービスの設定を正しく行う必要があります。
以下にapi利用のサンプルコードを示します。
import org.iplass.mtp.ManagerLocator;
import org.iplass.mtp.auth.AuthContext;
import org.iplass.mtp.pushnotification.*;
:
:
PushNotificationManager pnm =
ManagerLocator.getInstance().get(PushNotificationManager.class);
//PushNotificationTemplateに渡すバインド変数設定(例ではuserとpointを設定)
Map<String, Object> bindings = new HashMap<>();
bindings.put("user", AuthContext.getCurrentContext().getUser());(1)
bindings.put("point", 10);
//テンプレートを指定してPushNotificationを作成
PushNotification pn = pnm.createNotification("pointNotification", bindings);(2)
//通知先(registrationId)を指定
pn.addTo("ds...");
PushNotificationResult res = pnm.push(pn);
1 | 言語設定情報バインド名にuserと定義している場合、ユーザのlanguageプロパティに設定されている値により、適切な言語のテンプレートが利用されます |
2 | バインド変数に与えたオブジェクトがPushNotificationTemplate定義にて参照可能となります。 |
apiの詳細はPushNotificationManagerのjavadocを参照ください。
3.3. service-config.xmlの設定
プッシュ通知する際には、Push通知を実際に行う外部サービスの設定を行う必要があります。
Firebase Cloud Messagingを利用する場合
Firebase Cloud Messaging(FCM)を利用する場合、service-config.xmlのPushNotificationServiceの実装クラスとして、FCMPushNotificationServiceを指定し設定を行います。 FCMから発行されるサーバ認証のためのサーバキー、リトライに関する設定などを行います。
設定例を以下に示します。
<service>
<interface>org.iplass.mtp.impl.pushnotification.PushNotificationService</interface>
<class>org.iplass.mtp.impl.pushnotification.fcm.FCMPushNotificationService</class>
<!-- FCMで発行される認証のためのサーバキー -->
<property name="authorizationKey" value="AA...." />
<!--
リトライ処理を行う場合、enableRetry、exponentialBackoffにて設定。
-->
<property name="enableRetry" value="true" />
<property name="exponentialBackoff"
class="org.iplass.mtp.impl.pushnotification.fcm.ExponentialBackoff">
<property name="retryIntervalMillis" value="500" />
<property name="randomizationFactor" value="0.5" />
<property name="multiplier" value="1.5" />
<property name="maxIntervalMillis" value="60000" />
<property name="maxElapsedTimeMillis" value="300000" />
</property>
<!--
実行結果のRegistrationIdの状態により何らか処理する場合、
org.iplass.mtp.pushnotification.fcm.RegistrationIdHandler
の実装クラスを指定可能。
デフォルト実装として、ロギングするLoggingRegistrationIdHandler
を基盤側では提供。
-->
<property name="registrationIdHandler"
class="org.iplass.mtp.impl.pushnotification.fcm.LoggingRegistrationIdHandler" />
<!-- proxy利用する場合設定 -->
<property name="httpClientConfig"
class="org.iplass.mtp.impl.http.HttpClientConfig">
<property name="proxyHost" value="xxxxxx.isid.co.jp" />
<property name="proxyPort" value="8080" />
</property>
</service>
設定内容の詳細は、PushNotificationServiceを参照してください。
その他のプッシュ通知サービスを利用する場合
Firebase Cloud Messaging以外の外部プッシュ通知サービスを利用する場合、PushNotificationServiceの実装クラスを実装し、その実装クラスをservice-config.xmlに設定します。